X-Payments:Tokenization and Re-Use of Saved Credit Cards (X-Payments 2.x and later)

From X-Payments Help
Jump to: navigation, search
X-Payments user manual
  1. X-Payments:General information
  2. What's New
  3. System requirements
  4. Installation
  5. Two-factor user authentication
  6. Configuring X-Payments
  7. Managing users
  8. Customizing the interface
  9. Managing payments
  10. Unistalling X-Payments
  11. Upgrading
  12. Moving X-Payments from one host to another
  13. Viewing X-Payments logs
  14. FAQ
  15. Troubleshooting
  16. Glossary
  17. Supported payment gateways

In this section:

Tokenization: Overview

As an online merchant, you might like the idea of enabling your customers to save a credit card for repeated use at your store. If you have returning customers or want to sell subscriptions, this certainly makes sense, as this way credit card details will have to be entered and saved just once, and you won't have to ask your customers for their payment details every time they need to make a purchase.

However, according to PCI DSS, an industry-wide standard that must be met by any organization that stores, processes, or transmits cardholder data, storing customers' credit card details is not allowed for regular merchants - unless they take steps to implement a number of security aspects and undergo an expensive and time-consuming process of certification to ensure that all the PCI DSS requirements have been thoroughly met.

X-Payments versions 2.x and later provide a PCI DSS compliant solution that allows you to charge customer credit cards again (for new orders or for subscriptions) when you use certain payment gateways. You get all the benefits of storing your customers' credit card details - without actually storing them on your system. This is made possible through the use of the so-called "tokenization". Tokenization is a means of protecting sensitive cardholder data that was designed to reduce the risks associated with storing credit card information for merchants. The technology is meant to prevent the theft of the credit card information in storage. It replaces your customer's credit card details with a special number (token) that can be used to charge again the customer’s credit card via an integrated payment gateway. As sensitive information is stored not on the merchant site, but in a secure PCI DSS compliant environment of the payment system, use of tokenization significantly simplifies PCI DSS compliance for the merchant.

Support for tokenization and re-use of saved credit card data stored in a secure data center of the payment system away from the merchant site are new features introduced in X-Payments 2.0 (supported by all later X-Payments versions; not supported by X-Payments 1.x).

These features are supported by:

  • X-Cart versions 4.1.0 and later (Important: Installation of the updated X-Payments connector module is required for X-Cart versions 4.1.0-4.6.0. As to X-Cart versions 4.6.1 and later, they already support tokenization and re-use of saved credit cards out of the box, but for X-Cart versions 4.6.1-4.6.3 we still recommend installing the updated connector module so you can get the many fixes and improvements of the updated version.)
  • Magento Community edition 1.6 or later; Magento Enterprise.

To find out whether a specific payment gateway integrated with X-Payments supports tokenization, see the list of Supported payment gateways for X-Payments.

Enabling Payments with Saved Credit Cards

To enable payments with saved credit cards, do the following:

  1. Ensure that you are using an X-Payments integrated payment method with support for tokenization.
  2. In X-Cart Admin area, open the payment method's configuration page, select the Use for recharges check box and click Update:
    XP2.0 use for recharges.png
  3. Go to the 'Payment methods' page. You should see a new payment method added to the list - Use saved credit card:
    XP2.0 use saved credit card method.png
  4. Configure the Use saved credit card method as needed. For example, you can edit the name of this payment method, set an extra charge fee or make this payment method available only to users with a specific membership.
  5. Make sure the Use saved credit card method is enabled.

This is all. Now your store has some exciting new features:

  • During checkout, registered customers can save their credit card details for future orders at your store:
    XP2.0 want 2 use cc future.png
    Customers who have saved credit cards in their account can choose which card to use for each specific order:
    XP2.0 pay using saved cc.png
    They can also manage saved credit cards in their user account details:
    XP2.0 saved cc.png


  • You can create subscriptions and accept subscription payments from your customers' saved credit cards. See Managing Subscriptions.

Tokenization related configuration for Authorize.Net CIM by Authorize.Net / QuickBooks Payments by Intuit Inc

Using sensitive customer payment information tokenization with the payment gateways named in the heading of this section has some specifics described below.

During the initial transaction - when a customer chooses to save their credit card for future use and enters the credit card information to be saved using a secure form provided by X-Payments - this secure form in which the information is entered requires them to enter a Card Security Code (CSC/CVV2). This code is required only for the authorization of the transaction used to save the credit card info, and it is not saved or stored anywhere. Further payment transactions on the saved credit card do not require that CSC/CVV2 be entered.

However, the merchant back end of each of the above-named payment gateways provides some security settings allowing the merchant to customize the credit card authorization process for online transactions. Among them, there is a setting that can be used to allow or forbid processing of transactions with Card Security Code unavailable. If this setting is adjusted in such a way that CSC/CVV2 is required for all payment transactions at all times, it will cause problems related to the store's ability to use the tokenization feature: for a saved credit card all payment transactions but for the very first one (the one that was used to save the credit card info) will be rejected by the payment gateway because of the missing CSC/CVV2. The payment gateway may generate errors similar to the following: "A validation error occurred while processing this transaction: Card Verification Code not available."

To avoid this problem, make sure that the payment gateway setting requiring the gateway to reject payment transactions with no CSC/CVV2 is not enabled. This will not cause your store to stop requesting CSC/CVV2 altogether because the X-Payments secure form employed by your store to collect credit card information treats the CVV field as required at all times - regardless of the payment gateway settings.

Following are instructions for how to achieve proper payment gateway account configuration for specific payment gateways.

  • QuickBooks Payments by Intuit Inc.
    In the merchant setting, change the setting for If CSC is not available to Accept Transaction:
Qb transaction security settings.png
  • Authorize.Net CIM
  1. Log on to the Merchant Interface at https://account.authorize.net.
  2. Select Settings under Account in the main menu on the left.
  3. Click Card Code Verification in the Security Settings section
  4. Click to select the check box(es) next to the Card Code responses for which the payment gateway should reject transactions. Make sure you do not enable the option to reject transactions where the Card Code is unavailable. This, however, is different from transactions for which the Card Code is incorrect; we strongly recommend you keep the option to reject any transactions with incorrect Card Code enabled.
  5. Click Submit.

Charging Saved Credit Cards

X-Payments 2.x or later connected to your X-Cart store allows you to charge again credit cards that have been used at your store to pay you via an X-Payments integrated payment method with support for tokenization and have been saved in the customer's user account for future use.

There are two ways you can go about charging a saved credit card - via the X-Payments back end or via the X-Cart back end.

To charge a saved credit card via the X-Payments back end:

  1. Find the initial payment that was made using the credit card that needs to be charged and open its details for viewing. To find the payment, use filtering/advanced search.
  2. On the 'Payment details' page displaying the details of the initial payment, click the 'Charge this card again' link. A popup form titled 'Charge this card again' will appear where the parameters of the new payment can be specified:
    XP2.0 charge cc again.png
  3. In the 'Charge this card again' form, enter the amount that needs to be charged. If you wish you can also provide a comment for yourself - something to make your job easier later when you will be figuring out what this payment is for.
  4. Click the Charge this card again button at the bottom of the form. Confirm the action. The credit card will be charged, and the new payment will be created in X-Payments. The newly created payment will be marked as associated with the initial payment:
    XP2.0 initial payment link.png
  5. Once the credit card has been charged, go to your X-Cart store's Admin back end and check the 'Order management' section. This section should now contain an empty new order with an order total equalling the amount that has been charged.
  6. Use X-Cart's built-in Advanced Order Management module to edit the empty new order and add the missing information (products, shipping and taxes information, customer information, etc) as needed.

Video - How to make new orders via the back end of X-Payments 2.x:


To charge a saved credit card via the X-Cart back end:

  1. In X-Cart's Admin area, go to the 'Create order' page and start creating a new order like you normally do using the built-in Advanced Order Management module. At the step of selecting the customer, select the owner of the credit card that needs to be charged (The credit card needs to be stored in this customer's user account). Click Create new order.
  2. Continue creating the new order - add products, customer information, etc. At the step of selecting a payment method, select Other + Use saved credit card:
    XP2.0 use saved credit card AOM.png
    Important: At each step of creating the order (Edit ordered products, Edit customer information, Edit order totals), click the Save button after making any changes; otherwise your changes will not be applied.
  3. After providing all the necessary information and saving the changes, click the Back to details button to go back to review order details. On the 'Order details' page you will see a list of credit cards that the customer has saved in their user account:
    XP2.0 select cc AOM.png
  4. Select the card you require, use the 'Amount' input box to specify the amount that needs to be charged and click Charge card. The store will connect to X-Payments, and the selected card will be charged.

Video - How to create a new order in X-Cart 4.6.1 integrated with X-Payments 2.x:

Viewing Payments Made with Saved Credit Cards

In X-Payments, all payments made using a saved credit card are linked to the initial payment made using this card and are considered "based" on this payment. You can tell whether a payment was made using a saved credit card by the contents of its Reference ID field: independent payments have reference IDs like "#N", whereas payments based on another payment (payments made using a saved credit card) have a link in the Reference ID field that looks like "Payment #N" and points to the 'Payment details' page of the initial payment.

You can view the full list of payments for a specific saved credit card by using this button on the 'Payment details' page of the initial payment made using this credit card:
XP2.0 related payments.png

Managing Subscriptions (deprecated)

X-Payments 2.x connected to an X-Cart store enables you to set up a subscription (recurring payments) based on any payment made by a customer using a payment method that supports tokenization. Starting with X-Payments 3.0, the recurring payments feature is deprecated and is supported for backward compatibility only.

To set up a subscription:

  1. In your X-Cart store, create a product buying which will serve as a subscription setup fee, or first subscription payment, for your customers.
  2. When a customer buys this product, find the respective payment in X-Payments and open its details. If the payment was made using a saved credit card, locate the initial payment made using this card and open its details.
  3. On the 'Payment details' page, click on the 'Recurring payments' link:
    XP2.0 recurring payments.png
    The 'Subscription management' page opens:
    XP2.0 subscription management.png
  4. On the 'Subscription management' page, use the 'Subscription charges settings' form to configure the subscription: choose how frequently the customer is to be charged for the subscription and specify the amount that will be charged every period. Click Save at the bottom of the form to save the changes.
  5. After saving the subscription settings, note that the subscription now has the disabled status:
    XP2.0 subscription disabled.png
    To activate the subscription, click the button dropdown element at the bottom of the form and select Activate subscription:
    XP2.0 activate subscripion.png

That is all. Now X-Payments can charge the customer's saved credit card according to the subscription settings you have specified.

When you start receiving subscription payments from your customers, you will be able to track each subscription payment down to the initial payment on which it was made: simply follow the "Payment #N" link in the table cell specifying the payment's Reference ID.

To view all payments for a specific subscription, open the details of its initial payment and, on the 'Payment details' page, click on the 'Recurring payments' link. The list of all payments made on this subscription will be displayed in the 'Related payments' section of the 'Subscription management' page.

Every subscription payment is a separate payment in X-Payments, and you can manage it the same way as any other ordinary payment in X-Payments (refund, decline, etc).

In X-Cart, a separate order is created automatically for each subscription payment. Orders created for subscription payments are initially empty (no products, no shipping, no taxes - just the order total), but, if you need, you can edit them using X-Cart's built-in Advanced Order Management module to complete the missing information.


Video - Built-in subscriptions management in X-Payments 2.x integrated with X-Cart 4.6.1:

Get/update tokenized card feature

Starting with X-Payments version 3.0, X-Payments supports the Get/update card feature for some payment integrations. These include:

  • Authorize.Net;
  • Chase Paymentech Orbital.

The Get/update card feature aims to protect your customer relationships by enabling you to quickly and easily update the details of tokenized cards that have been used for payment at your store (including the masked card number, expiry date, etc.)

Customer card information may change for a variety of reasons, including card expirations, lost or stolen cards, upgrades and so on. The Get/update tokenized card feature enables you to provide uninterrupted service to your customers keeping the updating process transparent to them.

To use the feature, you will need to enable the payment gateway's card information updating service in your payment gateway account (or, depending on the gateway, to have the gateway support enable it for you). This way you will get access to the gateway's interface allowing you to request an update of information for the credit cards that have been previously saved for use at your store and are now stored in the gateway's secure vault. Depending on the gateway, the tools you will get for updating your customers' payment card information will range from the simplest button that you click to request an update to more complex schedulers enabling you to schedule payment information updates according to your needs. After you request an update of your customers' payment information, the gateway will submit a request to VISA/Master Card to check if there have been any changes for the cards stored by the gateway for use in your store. After VISA/Master Card has processed the request (which may take up to 2-3 days), the gateway will get a report of any changed payment card details. Based on the report, the information stored by the payment gateway will be updated to reflect the changes. The updated cards will then be linked to the existing tokens. This way your store will be able to charge the cards after re-issue using the same old tokens already stored by X-Payments.

In X-Payments, you also get a button allowing you to request an update of information for any card involved in tokenized payments directly from the page of any payment made using that card: Xp3 update card button.png

If a customer with a tokenized card makes a payment at your store via X-Payments after the card has been re-issued, the card information will be updated automatically and transparently to the customer.



PDF button.png This article can be downloaded as a PDF file