X-Payments:Charge again transaction request (Tokenization)

X-Payments API

1. API versions supported
2. Samples
3. API requests
   • Request/Response encryption
   • Encryption and communication
   • cURL as a means of sending requests
   • Data types
4. API Requests from the store to X-Payments
   1. Admin area/X-Payments configuration
      • Test connection request
      • Payment configurations list request
   2. Payment creation (Regular payment and tokenization)
      • Payment initialisation request
      • Charge again transaction request (Tokenization)
   3. Payment information
      • Payment information request
      • Detailed payment and transaction information request
   4. Actions on payments (secondary actions)
      • Capture authorized transaction request
      • Void authorized transaction request
      • Refund captured transaction request
      • Accept potentially fraudulent transaction request
      • Decline potentially fraudulent transaction request
5. Callback requests (web-hooks) from X-Payments to the store
   • Callback request with service payment information
   • Check cart callback request
6. Browser-related
   • Redirecting a customer to the cardholder data entering page
   • Communication between X-Payments iframe and the store
7. Appendix A. Status codes.
   • Payment status codes
   • Operation status codes
8. 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.

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

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<description>Recurring payment for the new issue of Playboy</description>
<target>payment</target>
<action>recharge</action>
<api_version>1.2</api_version>

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