X-Payments:Charge again transaction request (Tokenization)
- API versions supported
- Samples
- API requests
- API Requests from the store to X-Payments
- Callback requests (web-hooks) from X-Payments to the store
- Browser-related
- Appendix A. Status codes.
- See also
Detailed information about tokenization can be found here: Tokenization and Re-Use of Saved Credit Cards (X-Payments 2.x and later)
In general, the key features are:
- The credit card information itself is not stored in any way (neither in X-Payments, nor in the connected shopping cart).
- X-Payments stores a tokenized credit card internally. This is gateway-specific information, and, in some cases, it is not available to the connected shopping cart.
- The connected shopping cart can execute payment by token using txnId - a unique ID of the original payment which was processed using the real credit card details.
To be able to execute such a request, the following conditions must be met:
- The payment gateway supports the tokenization feature.
- Tokenization is enabled in the payment configuration in X-Payments (provided that there is such a setting). For example, this is true for Authorize.Net, NetBilling, Beanstream, etc.
- The buyer has chosen to save their credit card at checkout, or the card has been saved automatically for subscription/recurring payments.
Contents
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal recharge |
txnId | Y | string, 32 | Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway |
amount | Y | currency | The amount for which the "saved" card is to be charged using the token from the previous successful transaction |
description | Y | string | Description of the transaction |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
refId (supported by API 1.4 and later) | N | string, 128 | Order ID in the online store |
callbackUrl | Y | string | URL to which X-Payments sends background requests with service information |
cart | N | container | A container with addresses, purchased items, etc. See: Payment initialization request |
Request example
<api_version>1.7</api_version> <target>payment</target> <action>recharge</action> <amount>12.99</amount> <description>Recurring payment for the new issue of Playboy</description> <refId>order_1234</refId> <callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>; <txnId>143079cd2eec1645e332965f374f832a</txnId>
Request example with detailed cart information
<api_version>1.7</api_version> <target>payment</target> <action>recharge</action> <amount>49.98</amount> <description>Recurring payment for the new issue of Playboy</description> <refId>order_1234</refId> <callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>; <cart> <login>customer</login> <billingAddress> <firstname>John</firstname> <lastname>Young</lastname> <address>1610 N Main St</address> <city>Kissimmee</city> <state>FL</state> <country>US</country> <zipcode>34744</zipcode> <company></company> <email>user@example.com</email> <phone>18005551234</phone> <fax></fax> </billingAddress> <shippingAddress> <firstname>John</firstname> <lastname>Young</lastname> <address>1610 N Main St</address> <city>Kissimmee</city> <state>FL</state> <country>US</country> <zipcode>34744</zipcode> <company></company> <email>user@example.com</email> <phone>18005551234</phone> <fax></fax> </shippingAddress> <items type="cell"> <sku>10022</sku> <name>Playboy</name> <price>34.99</price> <quantity>1</quantity> </items> <currency>USD</currency> <shippingCost>15.95</shippingCost> <taxCost>0</taxCost> <discount>0</discount> <totalCost>49.98</totalCost> <description>Recurring payment for the new issue of Playboy</description> <merchantEmail>merchant@example.com</merchantEmail> <forceTransactionType></forceTransactionType> </cart> <txnId>143079cd2eec1645e332965f374f832a</txnId>
Response specification
Field | Type | Description |
status | integer, 1 | Operation status code |
data | array | |
data[status] | integer | Status of the new payment (See Payment status codes) |
data[transaction_id] | string | ID of the created payment for further references (capture/void/refund etc) |
data[error] | string | |
data[error_message] | string | |
data[is_error_message] | string |
Response example
<data> <status>4</status> <transaction_id>9f0811ad772a86aafb104d03afcb10ec</transaction_id> <error></error> <error_message></error_message> <is_error_message></is_error_message> <version>3.0.2</version> </data>