X-Payments:Using X-Payments with Magento

A Magento store can be connected to X-Payments web-based payment application to process payments from customers and save their credit card data in a PCI DSS compliant way.

This article provides information on how to connect X-Payments to your Magento store and how to handle payments in your Magento store using X-Payments.

Connecting Magento to X-Payments

System requirements

• Magento Community edition 1.6 or newer or Magento Enterprise
• X-Payments 2.1.1 or newer

Installing the X-Payments connector extension for Magento

Connecting Magento to X-Payments is done via a special Magento extension called 'X-Payments connector'. This extension can be installed using Magento's standard extension installation procedure via the Magento Connect Manager (System -> Magento Connect -> Magento Connect Manager):

The latest available version of the X-Payments connector for Magento can be downloaded using one of the methods below:

• through Magento Connect;
• using the link https://drive.google.com/folderview?id=0B6p7sehSZL8_bEhkZnFNNnpFSVU&usp=sharing.

On certain server configurations, the installation of extensions through Magento Connect may not work as expected. In this case, we recommend downloading the latest Magento connector package using the Google Drive link above, then uploading it to your Magento from your workstation or home computer.

Connecting X-Payments and Magento

Once the X-Payments connector extension for Magento has been installed, it is time to connect your Magento and X-Payments installations to each other.

You should begin by logging in to the admin back end of your X-Payments and completing a few preliminary steps that will enable your X-Payments to connect to your Magento store and to the payment gateway through which your customers' payments will be processed. An overview of this process is provided further in this article in the section "Configuring the connection in the X-Payments back end". More information on configuring X-Payments is available in the section "Configuring X-Payments" of the X-Payments user manual.

After configuring the connection in X-Payments, you should then log in to your Magento Admin panel and complete setting up the connection on the Magento end. For instructions, see the section "Configuring the connection in the Magento Admin panel" further below.

Configuring the connection in the X-Payments back end:
Complete the following steps:

1. Log in to X-Payments as administrator.
2. Provide your X-Payments application with data required to connect to your chosen payment gateway:
   
   You need to configure only one payment configuration since currently the Magento X-Payments integration only supports using a single payment service provider for payments via X-Payments.
   
   
   1. In the X-Payments back end, go to the 'Payment Configurations' page (Settings -> Payment configurations):
      
      
      
   2. From the New configuration drop-down box, select the payment module that X-Payments should use to connect to the payment gateway that will process your Magento store payment transactions.
   3. Click Add new.
   4. On the page that opens, enter all the required configuration parameters.
   5. Click Save to save the changes. You have created a payment configuration.
   6. Make sure the payment configuration you have created is enabled.
3. Provide your X-Payments application with data required to connect to your Magento store:
   1. In the X-Payments back end, go to the 'Online Stores' page (Settings -> Online stores).
   2. Click Add new.
   3. On the page that opens, enter your Magento store name, store title and order prefix.
   4. Specify the templates that you would like to use for the payment pages in your Magento store (a template for laptop and desktop users, a template for mobile users and a template for users who have 3-D Secure protection enabled).
   5. Specify the payment configuration you would like to use for this store (Select the payment configuration you have configured at the previous step).
   6. Click Save to save the changes.
   7. Make sure the online store is enabled.

You have completed configuring the connection in X-Payments.

Before you proceed to configuring the connection in your Magento Admin panel, please pay attention to the Connection section on the right-hand side of the page with your Magento store's details in X-Payments. Here you should be able to see the so called configuration bundle for your Magento store. The configuration bundle provides a quick method to deploy X-Payments connection settings in your Magento store. You will need this bundle when you will be configuring the connection in your Magento Admin panel. For now, simply click the Copy button to copy the bundle to clipboard so you have it at the ready when it is time to paste it on the Magento end.

Now let's configure the connection in your Magento Admin panel.

Configuring the connection in the Magento Admin panel:
The following procedure assumes that your Magento store has the X-Payments connector extension installed.
Complete the following steps:

1. Log in to the Admin panel of your Magento store.
2. Go to System -> Configuration:
   
   
   
3. In the left-hand side menu, select X-Payments connector:
   
   
   This opens the 'X-Payments Connector Settings' section:
   
   
   
4. Configure the connection settings needed for your Magento store to interact with X-Payments:
   • X-Payments configuration bundle: This is where you need to paste the configuration bundle you copied earlier while in the X-Payments back end.
   • IP addresses for X-Payments callbacks: Use this field to enter the IP addresses from which your X-Payments callbacks will originate.
     Comment: X-Payments will send callback requests to your store from specific IP addresses. To ensure that your store accepts callback requests only from these IP addresses, specify the allowed IP addresses here as a comma-separated list. Note that the address "127.0.0.1" may not be used here. For better understanding of what IP address(es) to put here, see Callback from X-Payments to the store.
   • Payment currency: Specify the currency in which payments that will be made via X-Payments will need to be processed. The currency specified here should be the same as the currency specified in the settings of the X-Payments payment configuration connected to your Magento store (You can check the payment configuration details in the X-Payments back end).
   • Setup minimum payment amount for recurring orders and customer card authorization actions: Use this field to set the minimal authorisation amount for recurring subscriptions ordered with start date in the future and customer card authorization actions.
     Comment:When a customer purchases a recurring subscription with a start date in the future or chooses to save their credit card with your store for future payments, you need to run an authorization against their card to have the card details saved by the payment service provider and to obtain a token which will later need to be submitted for any future authorization/charge requests for that customer to use their card for payment. By default the Magento X-Payments integration performs a zero value authorization on the customer's card in this case. However, some payment service providers do not support zero value authorizations. If this is the case with the PSP you are using for your Magento store, you need to adjust the authorization amount value in the "Setup minimum payment amount for recurring orders..." field according to the requirements of your PSP so you can obtain non-zero value authorizations.
5. Click the Save Config button at the top right-hand corner of the screen to save the changes:
   
   
   
6. Go to System -> X-Payments connector:
   
   
   
7. Test the connection between your Magento store and X-Payments by running a test transaction:
   Click the Test module button.
   
   
   If the connection is configured properly, a message saying "The test transaction has been completed successfully" will be displayed at the top of the page:
   
   
   
8. Import payment methods from X-Payments:
   Click the Import payment methods from X-Payments button:
   
   
   X-Payments will return a list of payment methods available for your Magento store:
   
   
   
9. Configure the X-Payments payment methods you are going to use:
   
   1. Go to System -> Configuration again:
      
      
      
   2. Select Payment Methods from the left-hand side menu:
      
      
      
   3. Scroll down the page to locate the three sections pertaining to X-Payments payment methods: X-Payments connector, Use saved credit cards (X-Payments) and Prepaid Payments (X-Payments).
   4. Use the X-Payments connector section:
      
      
      to adjust the settings for your main X-Payments payment method - the one allowing buyers to pay by entering their credit card details at checkout:
      • Enabled: Use this setting to enable/disable payments via X-Payments for buyers at your Magento store. If enabled, the payment method will be available for selection by shoppers at checkout. If disabled, the method will not appear on the list of methods available for selection.
      • Sort order: Use this to control the sort order of payment methods in the list of methods displayed to buyers.
      • Title: Enter a name that will help buyers to identify this payment method. This name will appear on the list of available payment methods. By default, the name is "Credit Card (X-Payments)".
      • Payment from applicable countries: Use this field to specify whether you are going to accept payments from any countries supported by your PSP (select All Allowed Countried), or only from some specific countries (select Specific Countries).
      • Payment from Specific countries: If you have specified that you are going to accept payments only from Specific Countries, specify those specific countries here. More than one item may be selected by holding down the Ctrl key while clicking on the country names.
      • Payment configuration: Select the payment configuration to use with your Magento store.
      • Use iFrame: This setting determines what method will be used to provide the form for entering credit card details to the buyer. Select Yes if you want the form to be displayed in your Magento store using iFrame; in this case, the form will be embedded into your store's page. Select No if you want this form to be provided to the buyer on a separate page, without the use of iFrame. Please note that if you choose to enable the "Use iFrame" option in Magento, you should also enable the template Iframe for Magento in the X-Payments back end.
      • Show credit card form at: This field is displayed only if you have enabled the "Use iFrame" option at the previous step. It allows you to specify at what step of your Magento store checkout routine the form for entering the customer's credit card information needs to appear. The available options are ORDER REVIEW step:
        
        
        and PAYMENT INFORMATION step:
        
        
        Important: In Magento stores allowing customers to partially pay for their order using reward points, where at the PAYMENT INFORMATION step of the checkout routine, at which the method of payment is chosen, customer is allowed to specify the amount of reward points they wish to redeem, it is not recommended to use the checkout routine configuration where the form for entering credit card details is displayed via iframe at the PAYMENT INFORMATION step. When such a configuration is used, the contents of the iframe may be displayed on the page before the customer applies their reward points to the order, which may result in payment problems, for example:
        1. The customer's card may be charged the full amount instead of the amount that has been reduced by reward points.
        2. The card may be charged successfully, but the order will be immediately canceled in Magento.
        To avoid the above named problems, it is recommended to use a configuration in which the credit card form is displayed using iframe at the ORDER REVIEW step of the standard Magento checkout routine, or is output without the use of iframe - on a separate page.
        
        
      • Use forced Authorize operation: This setting determines how the buyer's credit card is charged when they pay you using this method:
        
        If this is set to Yes, a two-step process is used in which the authorization of payment is separated from the capture of the authorized payment. At the time of the initial transaction, you perform only an authorization on the buyer's card without actually capturing the funds. This corresponds to the payment status "Authorized" in X-Payments, the status "X-Payments Pending payment" in the Magento admin and the status "X-Payments Authorized payment" in the Magento front end. Later you need to take additional steps to capture the funds or void the authorization.
        
        If this is set to No, an actual charge is made on the buyer's card as soon as the buyer's payment information is processed by the payment gateway - without any further interaction on your part. In X-Payments the status of such payments appears as "Charged", which corresponds to the Magento status "Processing".
        
        Some payment gateways do not support two-step payments with separate authorization and capture, so if you choose the "Use forced Authorize operation" option, make sure your payment gateway supports this feature.
        
        The option "Use forced Authorize operation" can be used to override the value of the "Initial transaction" setting of the payment configuration used by your Magento store - as provided on the respective Payment configuration details page in X-Payments: Setting "Use forced Authorize operation" to Yes in Magento allows you to have a two-step payment process with separate authorization and capture - even if the payment configuration in X-Payments is configured to use the "Auth and capture" mode for the initial transaction.
      • Use forced Authorize operation for initial fee: This setting is similar to "Use forced Authorize operation", but applies only to the initial fee of products with recurring profiles.
        
        
   5. If your payment gateway supports tokenized payments, and you wish to allow your Magento store shoppers to save their credit cards for future use at the store, adjust the settings in the section Use saved credit cards (X-Payments):
      
      
      
      • Enabled: Use this setting to enable/disable payments with saved credit cards for buyers at your Magento store. If enabled, registered customers will be provided with an option to save their credit card details for future orders - either during checkout, or at any other time via the "MY PAYMENT CARDS" section of their account.
        
        Note: The credit card details will be saved in a PCI compliant manner (by your payment service provider, not by your Magento store itself) . After having their credit card details saved, customers will be able to use their saved credit cards for new orders. You - as the store administrator - will also be able to use your customers' saved credit cards to create orders for your customers via the Magento store's admin panel.
        
        If disabled, your customers will not be able to save their cards or use them for payment.
        
        
      • Sort order: Use this to control the sort order of payment methods in the list of methods displayed to buyers.
      • Title: Enter a name that will help buyers to identify this payment method. This name will appear on the list of available payment methods. By default, the name is "Use saved payment cards (X-Payments)".
   6. If your payment gateway supports tokenized payments, and you wish to use the prepaid payments feature, adjust the settings in the section Prepaid Payments (X-Payments):
      
      
      
      • Enabled: Use this setting to enable/disable prepaid payments.
      • Sort order: Use this to control the sort order of payment methods in the list of methods displayed to buyers.
      • Title: Enter a name that will help buyers to identify this payment method. This name will appear on the list of available payment methods. By default, the name is "Prepaid payments (X-Payments)".
        
        
   7. Click the Save Config button at the top right-hand corner of the screen to save the changes:
      

That's it. You have connected your Magento store to X-Payments.

Updating your X-Payments connector for Magento

We recommend using the latest available version of the X-Payments connector extension at all times. As new versions of the X-Payments connector become available, you may want to update your installed connector. To update your X-Payments connector for Magento, use one of the methods below.

Manual updating
To update your X-Payments connector manually, complete the following steps:

1. Unarchive the extension package and copy its contents to your Magento site's root directory (without the file package.xml, as you do not need this file for this type of installation).
2. Make sure the files responsible for displaying the X-Payments Iframe have been copied to the correct design package folder.
   For example, you may be using a design package other than default.
   (To find out what design package you are currently using, go to System -> Configuration -> Design (General) and review the section titled Package.)
   If the Current Package Name field in the Package section shows anything other than "default", you need to copy the template folders from your unarchieved X-Payments connector package to the folder of the design package listed in this field.
   
   

Example:
The name in the Current Package Name field shows as ultimo.
In this case you need to copy the template folder and layout:

• app/design/frontend/default/default/template/xpaymentsconnector
• app/design/frontend/default/default/layout/xpaymentsconnector.xml

to:

• app/design/frontend/ultimo/default/template/xpaymentsconnector
• app/design/frontend/ultimo/default/layout/xpaymentsconnector.xml

Automated updating
This method requires that your Magento folders have sufficient write permissions so you can use the Magento Connect Manager in the Admin Panel. To update your X-Payments connector, complete the following steps:

1. In the Magento Admin panel, go to System -> Magento Connect-> Magento Connect Manager.
2. Re-enter your Magento Adminstration Credentials.
3. Uninstall the currently installed version of the X-Payments connector:
   
   
   
4. If the uninstallation is completed successfully, you should see something like the following:
   
   
   
5. Install the new version of the X-Payments connector using one of the following methods:
   
   
   
6. If in the process of insalling the connector you get an error like the following:
   
   
   it may mean that not all the files and folders that were supposed to be removed during the uninstallation process have been removed successfully, and you will need to remove them manually.
   In our example, as demonstrated by the snapshot above, the problem is caused by the file /app/code/community/Cdev/XPaymentsConnector/Block/Adminhtml/System/Config/Form/Subselect.php
   To resolve this problem, we need to remove this file. In this situation, it is probably better to remove the entire folder app/code/community/Cdev/XPaymentsConnector - this way we'll get through the installation process faster.
   After removing all the files and folders of your old X-Payments connector installation, click the Refresh button, then try to install the extension again. You may have to do so more than once before all the files hindering the installation are removed.
7. In the end, you should get something like the following:
   
   
   
8. If you are using a design package other than default, please remember to check that the X-Payments connector theme files and folders have been copied there. A detailed explaination of what needs to be done is provided in the section 'Manual updating' above (See Step 2).

Payments via X-Payments in Magento: Customer experience

Magento checkout routine when using X-Payments

After the payment method for accepting credit card payments via X-Payments has been enabled in the admin panel of your Magento store, this method is added to the list of payment methods available to buyers:

Depending on the "Use iFrame" setting as provided in your store's Payment Methods configuration, the checkout process for buyers who choose to pay using this method may follow two alternative paths. One of them - the one relying on the iFrame technology - allows the buyer to enter their credit card details using a secure X-Payments-generated credit card form that is embedded directly into your Magento store's checkout page. The other one - which does not involve using iFrame - requires that the buyer should complete the secure credit card form on a separate page, which involves redirecting them off your site.

iFrame vs. Separate page
Let's see what the checkout process looks like in stores providing the credit card form to buyers using the iFrame method.

If, according to the "Show credit card form at" setting in your store's Payment Methods configuration, the secure credit card form is configured to appear at the Payment Information step, the form is displayed to the buyer immediately after they have selected the payment method:


After completing their payment information, the buyer reviews their order:


and submits it:


If the "Show credit card form at" setting says the credit card form must appear at the Order Review step, the only thing the buyer does at the Payment Information step is select the payment method, whereas the entering of credit card details takes place at the Order Review step:


Once the order is submitted, the buyer's payment information is processed, and the buyer sees the order received screen:

Now let's see what the checkout process looks like in a store using the secure credit card form on a separate page.

If the store is configured not to use iFrame, at the Payment Information step the buyer selects the payment method:


and continues to the Order Review step where they can review the order before completing the purchase:


Once the PLACE ORDER button is clicked, the buyer is redirected away from the store site to a page with the credit card form:


The buyer enters their credit card details into the form and selects "Pay". As a result, the information they entered is submitted to the payment gateway:


The buyer returns to the store site and, provided that the transaction has been successful, sees the order received screen:

PCI compliant credit card saving

When you enable the "Use saved credit cards" X-Payments payment method, your customers get the option to save their credit card details so they won't have to re-enter them every time they make a purchase at your store. Note that the option is available only to registered customers.

Credit card details are saved in a PCI compliant manner: no credit card information is stored in your Magento store; instead, the information is stored in a PCI compliant credit card vault of the payment system. Re-use of saved credit cards by your Magento store is made possible through the use of tokenization - an approach that replaces sensitive cardholder info with a unique identifier (a "token").

A Magento store configured to support credit card saving provides two places where a customer can choose to save their card: the checkout page and the section "MY PAYMENT CARDS" in the customer's user account.

The checkout page allows the customer to save the details of the credit card with which they are going to pay for the current purchase. If the secure credit card form is embedded into the checkout page as iFrame, the option "I want to save this credit card for my future orders in this shop" apears right beneath the credit card form and can be selected after completing the credit card details:


If the store is configured to display the secure credit card form on a separate page, the option "I want to save a credit card for my future orders in this shop" is displayed before the customer goes to the page with the credit card form:

The "MY PAYMENT CARDS" section in the customer's account can be accessed by selecting ACCOUNT -> My Account -> MY PAYMENT CARDS:


The customer can use this section to add new cards and manage the cards they have saved previously:


When a customer has at least one saved credit card, they can use it to pay for orders. This is done using the "Use saved credit cards (X-Payments)" payment method:


When the customer has more than one saved credit card, they can choose which of the credit cards to use:

Payments via X-Payments in Magento: Administrator experience

Capturing payments

If payment for an order is performed in the "Auth and capture" mode ("Initial transaction = Auth and capture" in the payment configuration settings in X-Payments and "Use forced Authorize operation = No" in the X-Payments connector payment method settings in Magento), the customer is charged for the order at the time of order creation. However, in a workflow where the initial payment transaction is performed in the "Authorization only" mode ("Initial transaction = Auth" in X-Payments and/or "Use forced Authorize operation = Yes" in Magento), no money changes hands immediately after order creation: the payment transaction is done only to obtain an authorization for the amount listed as the order Grand Total, and you have to take a few additional steps to capture the amount that was authorized.

Below we discuss how to capture the funds for which an authorization has been obtained as a result of the customer making a payment in the "Authorization only" mode.

For orders for which an authorization has been obtained via X-Payments, Magento uses a special status: X-Payments Pending Payment (In the Magento front end, the same status is named "X-Payments Authorized Payment").

When an order has this status, you know that a capture needs to be performed on it. Please note that when an authorization to capture a certain amount is obtained, this amount is reserved on the customer's account for you to capture only for a limited time; for this reason, when you get an order with the "X-Payments Pending Payment" status, be sure to keep an eye on it and perform the capture before the authorization expires.

The main method that can be used to capture a previously authorized amount is based on creating an invoice. If required, multiple invoices can be created for a single order, each containing as many or as few of the purchased items as you specify.

Important: If your workflow does not use invoices, or the order for which you need to perform a capture has been modified using Magento's default Edit feature, DO NOT use this procedure; instead, please refer to the section "Capture, Void and Refund via the X-Payment Order State tab".

To perform a capture:

1. In the Admin panel, select Sales > Orders:
   
   
   
2. In the Orders list, locate the order for which you want to perform a capture and click to open the order details.
   
   
   
3. In the upper right, click the Invoice button:
   
   
   This opens a new invoice page:
   
   
   
4. Scroll down to the Items to Invoice section.
   
   
   This section provides a list of items you can invoice and their respective quantities. By default, the invoice will be created for the entire order. If you are going to invoice only some of the items and do a partial capture this time, update the quantities to invoice (specify the correct quantities in the Qty to invoice column and click the Update Qty's button); the invoice totals will be re-calculated.
   
   Important: Before using partial capture, make sure your payment gateway supports this feature.
5. Work through the invoicing process as usual: add a tracking number, create a packing slip, enter invoice comments as needed, specify whether a copy of the invoice needs to be emailed to the customer and whether your comments need to be appended to it.
6. In the Amount field, select the payment action you require:
   
   
   
   • Capture Online: Upon invoice submission, the invoice amount will be captured (a request to capture the specified amount will be sent through X-Payments to the payment gateway). After the capture, you will have the ability to create a credit memo should you require to issue a refund.
   • Capture Offline: Upon invoice submission, the system will not capture the payment (no request to capture the payment will be sent). This option should be selected if the capture of funds is performed directly through the gateway or through the X-Payments back end. Note that after using the "Capture Offline" option you will no longer have the option to capture this payment through your Magento store. You will have the ability to create a credit memo.
   • Not Capture: Upon invoice submission, the system will not capture the payment (no request to capture the payment will be sent). This option assumes that you will capture the payment at a later date. The completed invoice (you will be able to access it through Order View > Invoices) will have a Capture button allowing you to complete the task:
     
     
     Before the payment is captured, you will able to cancel the invoice. After capturing you will be able to create a credit memo.
     
     Important: Do not select “Not Capture” unless you are certain that you are going to capture the payment through Magento at a later date. You will not be able to create a credit memo until the payment has been captured using the Capture button.
7. Click the Submit Invoice button to process the invoice.
   
   
   The invoice will be created. The selected payment action (Capture Online, Capture Offline or Not Capture) will be applied.
   
   Now if you go back to the order details and click on the Invoices tab under the Order View menu, you should be able to see the new invoice added to the list of invoices pertaining to the order:
   
   
   An invoice created with the "Capture Online" option or captured after it has been created with the "Not Capture" option will have the status Paid. The respective capture transaction will appear in the X-Payments back end with the status Charged.
   An invoice created with the "Capture Offline" or "Not Capture" option will have the status Pending; no transaction will be reflected in X-Payments.
   
   

Issuing refunds

After an order has been paid and invoiced, the entire order, or a portion of it, can be refunded. The basic method to do a refund in Magento is by issuing a credit memo.

Important: If your workflow does not use invoices, or the order for which you need to issue a refund has been modified using Magento's default Edit feature, DO NOT use this procedure; instead, please refer to the section "Capture, Void and Refund via the X-Payment Order State tab".

To issue a refund:

1. In the Admin panel, select Sales > Orders:
   
   
   
2. In the Orders list, locate the order for which you want to issue a refund and click to open the order details:
   
   
   
3. In the Order View menu on the left-hand side of the screen, select the Invoices tab. This opens a list of invoices pertaining to the order:
   
   
   
4. Locate the invoice for the item(s) you need to refund and click to open it.
   
   
   
5. In the upper right of the Invoice page, click the Credit Memo button to start the refund process by generating a credit memo.
   
   
   
6. Scroll down to the "Items to Refund" section.
   
   
   This section provides a list of items pertaining to the invoice and their respective quantities. By default, a refund will be issued for the entire invoice amount. If you are going to refund only some of the items and do a partial refund this time, update the quantities to refund (specify the correct quantities in the Qty to Refund column and click the Update Qty's button); the total amount to be credited will be re-calculated. Select the Return to Stock checkbox for the items that will be returned to inventory (Do not select the checkbox if the items will not be returned). If you want to refund shipping, issue an adjustment refund or add an adjustment fee, specify the respective amounts.
   
   Important: Before doing a partial refund, make sure your payment gateway supports this feature.
7. Work through the process of creating a credit memo as usual: enter credit memo comments as needed, specify whether a notification of the credit memo needs to be emailed to the customer and whether your comments need to be appended to the notification.
8. Click Refund or Refund Offline to process the refund (Select the button based on the action you require).
   
   If you select Refund, a refund request will be submitted to the payment gateway via X-Payments, and a refund will be given at the same time that the credit memo is issued. If you select Refund Offline, no refund request will be sent (This option assumes that you will handle the refund directly through the gateway or through the X-Payments back end).
   
   

Once you have completed the above steps, the credit memo should be created. Now if you go back to the order details and select the Credit Memos tab under the Order View menu, you should be able to see the new credit memo added to the list of credit memos pertaining to the order:


The status will be shown as Refunded.
If you have chosen to complete the refund online, the refund transaction will appear in X-Payments with the same status, Refunded.
If you have chosen the "Refund Offline" option, the transaction will not be reflected in X-Payments.

Canceling payments

In the "Auth only" workflow - as opposed to the "Auth and capture" workflow - it is possible to cancel (void) a payment before it has been captured. For example, if you have a payment for which an invoice was created with the "Not Capture" payment option, you can cancel it via the invoice page.

Important: If your workflow does not use invoices, or the order for which you need to cancel a payment has been modified using Magento's default Edit feature, DO NOT use this procedure; instead, please refer to the section "Capture, Void and Refund via the X-Payment Order State tab".

To cancel a payment:

1. In the Admin panel, select Sales > Orders:
   
   
   
2. In the Orders list, locate the order for which you want to cancel a payment and click to open the order details.
   
   
   
3. In the Order View menu on the left-hand side of the screen, select the Invoices tab. This opens a list of invoices pertaining to the order. Locate the invoice you need to cancel and click to open it.
   
   
   
4. In the upper right of the Invoice page, click the Cancel button.
   
   
   The authorization to capture the invoice amount will be voided. The invoice status will be updated to Canceled.
   
   
   In X-Payments, you should be able to find the respective Void transaction with the status Voided. The status of the payment in X-Payments should be updated to Declined by merchant.
   
   

Finding out the order state for X-Payments orders

General information about the current state of an X-Payments order can be viewed in the X-Payment Order State section of the order details.

To access this section:

1. In the Admin panel, select Sales > Orders:
   
   
   
2. In the Orders list, locate the X-Payments order for which you want to view the information and click to open the order details.
   
   
   
3. In the Order View menu on the left-hand side of the screen, select the X-Payment Order State tab. This opens a page like the following:
   
   
   This is the most up-to-date information about the order state, since the information is updated every time the page is loaded or refreshed in the web browser.
   On the snapshot above, we see information pertaining to Order #100000098 created on Jan 14, 2015 7:20:43 AM. Based on the table data, we can assume that the order was created for the amount of $110.80. An authorization was obtained for $110.80, of which $110.80 were captured. No refunds were given. The result payment status is charged.
   Should we need more information about the specific transactions that were performed on this order, we can expand the section Transaction list for order # by clicking on its header:
   
   
   The result will be detailed information about all the payment related transactions that have been performed on this order:
   

Capture, Void and Refund on orders modified using Magento's default Edit feature

Sometimes you may require to make changes to an order in your store. For example, you may want to change an order if a customer asks you to add an item to their order or if some of the items in the order are out of stock.

When you need to remove an item from an X-Payments order in Magento, you use the Credit Memo feature (For more info, see the section Issuing refunds). When you need to add an item to an order, you do it using Magento's default Edit feature:

You need to know that if you have used Magento's default Edit feature to add items to an X-Payments order, you will need to treat this order in a special way when performing payment related operations like Capture, Void or Refund.

The thing is, when you edit an order in Magento, the original order is canceled, and a new ("child") order is generated based on it. Because one or more items are added to the order, the grand total amount of the "child" order is greater than the grand total amount of the "parent" order. When your store creates a new order, it requests an authorization for the amount equal to the difference between the grand total amount of the child order and the grand total amount of the parent order:

Xp Transaction amount = Child Order (new order) — Parent order (Edited Order)

The existing authorization inherited from the parent order also keeps for the new order.

Now if you attempt to do a capture of funds on this new order through creating an invoice, you are highly likely to request a capture of an amount that does not match any of the two authorizations. This means, if you use the "Capture Online" option, you won't be able to complete the capture transaction successfully. That is why, when performing a capture on an order that has been edited using Magento's default Edit feature, you should refrain from using the "Capture Online" option. Instead, you may want to use the option "Capture Offline" or (in the event that you do not need an invoice) to perform a capture through the X-Payment Order State tab.

The same holds true for Void and Refund: when you need to perform these actions on an X-Payments order that has been edited in Magento, avoid using the "online" options of the invoice (Invoice: Cancel or Invoice: Credit Memo→Refund Online).

Example:
In our Magento store, an order was created (Order #100000110) for a single unit of "Simple product 1".

The initial transaction on this order was performed in the "Auth only" mode, and the amount for which an authorization was obtained was $61 ($56 one unit of "Simple product 1" + $5 shipping):

We edited the order by adding to it another unit of "Simple product 1". The order #100000110 was canceled, and, based on it, another order, Order #100000110-1, was generated. On this order, a new authorization was obtained for the difference of #100000110-1 and #100000110 grand total amounts, which was also $61 ($56 one unit of "Simple product 1" + $5 shipping).

Now if you take a look at the information in the X-Payment Order State section, you should see the authorization that Order #100000110-1 inherited from Order #100000110, as well as the new authorization that was created for the difference between the two order amounts:

Please note that these are two separate authorizations ($61 + $61).

Now if we include both the units of "Simple product 1" from this order into a single invoice, the invoice total amount will be $122 ($112 two units of "Simple product 1" + $10 shipping):

If we invoice the two units of "Simple product 1" separately, the invoice totals will be $66 ($56 first unit of "Simple product 1" + $10 shipping of both the units):

and $56 ($56 second unit of "Simple product 1", no shipping):

In any case, neither of the above amounts equals $61, the amount for which we have two authorizations. So, if you choose the "Capture Online" option when doing a capture, the capture transaction will not be processed successfully.

Capture, Void and Refund via the X-Payment Order State tab

If your store's workflow does not involve invoicing, or you are dealing with an X-Payments order that has previously been edited using Magento's default Edit feature, you can perform Capture, Void and Refund operations via the X-Payment Order State section of the order details (The section can be accessed by clicking the X-Payment Order State tab in the Order View menu). The specific operations available to you depend on the current order state, and you can only see the buttons for the operations that you can perform. If necessary, you can edit the amount on which the operation is performed by editing the contents of the iput field in the Actions column of the table.

Important: If you have already performed a Capture, Void or Refund operation on an order via the X-Payment Order State section, you should not attempt to do any further payment related operations on this order using the online options of the invoice (like Invoice: Cancel, Invoice: Capture Online or Invoice: Credit Memo→Refund Online), as it may cause the following problems:

• Sending a duplicate request for the current transaction;
• Requesting a transaction for an unavailable amount (For example, by doing Invoice: Credit Memo→Refund Online you may be requesting a refund for an amount exceeding the amount that you have captured originally via the Order(s) state block in the X-Payment Order State section).

The opposite is also true: If you have used on a certain order a payment related operation based on an online option of the invoice (Invoice: Cancel, Invoice: Capture Online or Invoice: Credit Memo→Refund Online), do not attempt to perform any further payment related operations on this order via the X-Payment Order State section, as it is likely to cause similar problems.

Recurring Billing in Magento with X-Payments

See the article Recurring Billing in Magento with X-Payments.

Export of order information to StoneEdge Order Manager

Starting with version 1.7.0, the X-Payments connector for Magento supports export of payment information (stuff like transaction IDs, the last four digits of the credit card number, etc.) to StoneEdge Order Manager. If you use X-Payments with Magento and need to export information about payments conducted via X-Payments to StoneEdge Order Manager, contact the X-Payments team for help.

Materials for users of older X-Payments versions

How to connect and configure X-Payments 1.x with Magento

This video provides a demonstration of the obsolete method of connecting and configuring X-Payments for use with Magento. It is provided here exclusively for support of legacy X-Payments versions.