X-Payments:API
Contents
- 1 API versions supported
- 2 Samples
- 3 API requests
- 4 Payment configurations list request
- 5 Test connection request
- 6 Payment initialisation request
- 7 Redirecting a customer to the cardholder data entering page
- 8 Payment information request
- 9 Detailed payment and transaction information request
- 10 Capture authorized transaction request
- 11 Void authorized transaction request
- 12 Refund captured transaction request
- 13 Blocked by gateway transaction accept request (Accept)
- 14 Blocked by gateway transaction decline request (Decline)
- 15 Charge again transaction request (Tokenization)
- 16 Callback request with service payment information
- 17 Check cart callback request
- 18 Communication between X-Payments iframe and the store
- 19 Appendix A. Status codes.
- 20 See also
API versions supported
API v1.1: X-Payments 1.0.2-1.0.5
API v1.2: X-Payments 1.0.6, 2.0.0, 2.0.1
API v1.3: X-Payments 2.1.0, 2.1.1
API v1.4: X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015)
API v1.5: X-Payments 2.2 (June 2015)
API v1.6: X-Payments 3.x (June 2016)
Samples
While we are doing an addition to our API docs I suggest to use function xpc_api_request from X-Cart 4 file modules/XPayments_Connector/xpc_func.php as a sample.
Especially function xpc_request_test() to make a test call.
API requests
All API requests are made to the https ://<xpayments_url>/api.php URL. Only HTTPS protocol is used. A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.
Request/Response encryption
- Encryption method used: RSA;
- Key length: 2048 bit;
- A private key is created with a 32 character password;
- The password is generated randomly;
- The number of password characters varies from 33 to 127.
For each online store X-Payments generates 2 pairs of keys:
- a public and a private key to encrypt requests/responses from the online store to X-Payments;
- a public and a private key to encrypt requests/responses from X-Payments to the online store.
So when the online store sends a request to X-Payments, this request is encrypted using the public key from the first pair, X-Payments decrypts it using the private key of the first pair. Then X-Payments response is encrypted using the public key of the second pair, and the online store decrypts this response using the private key of the second pair.
To ensure full-featured two-way communication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:
- Public key from the first pair (Online store -> X-Payments),
- Private key from the second pair (X-Payments -> Online store),
- Private key password,
and have them stored on the side of the online store by an appropriate X-Payments connector.
Encryption algorithm
I. Encryption. Data is passed as an XML string.
- Get the Salt block.
- Generate a 32-character string formed of random characters from 33 to 255.
- Get the CRC block.
- Generate MD5 in the binary format of the passed data.
- Prepend it with the " MD5" prefix (the spaces are mandatory!)
- Get the Data block.
- For each Salt, CRC and Data calculate the length: it is formatted as a 12-digit number, e.g. 000000000032.
- Compose the data block. Write consecutively: length of Salt, Salt, length of CRC, CRC, length of Data, Data.
- Split the data into chunks of 128 characters.
- Encrypt each chunk consecutively using the public key.
- Encode each chunk with base64.
- Compose the encrypted data.
- Start with the "API" prefix.
- Write the encrypted and encoded chunks separated with line-breaks.
II. Send the request
POST the encrypted data to https ://<xpayments_url>/api.php in the following format:
cart_id=CART_D&request=REQUEST
Where:
- CART_ID is the Store ID - REQUEST is the encrypted XML
III. Decrypt the response
The response is a string starting with "API".
- Remove the leading "API" word. If the response does not start with "API", it means that it is incorrect.
- Split and decode the encrypted chunks.
- Chunks are separated by line-breaks.
- Each chunk is decoded with base64.
- Decrypt each chunk using the private key.
- Combine the decrypted chunks together in a single line.
- Validate the CRC of the encrypted response.
IV. CRC Validation.
A response is received in a single line. It contains the following data, consecutively:
length of Salt, Salt, length of CRC, CRC, length of Data, Data.
- Extract Salt
- Get the salt length from the first 12 characters.
- Shift the salt block by its length.
- Extract CRC:
- Get the CRC length from the first 12 characters.
- Shift the CRC block by its length.
- Remove the " MD5" prefix from CRC.
- Extract data
- Get the data length from the first 12 characters
- Shift the data block by its length
- Calculate the MD5 checksum in the binary format of the received data.
- Compare it with CRC.
cURL as a means of sending requests
Using libcurl v.7.10 and above is recommended.
TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.
It is recommended to use SSL v.3 and above.
Data types
Data types used:
- string - a UTF-8 string;
- email - an email address no longer than 255 characters;
- URL - a URL address no longer than 255 characters;
- currency - a floating point number denoting a certain sum of money. The mantissa size is the same as the payment currency mantissa size, but not longer than 3. All the exceeding characters will be truncated.
- integer - an integer number.
ISO 4217 Alpha-3 in the upper register is always used as the payment currency code.
ISO 639-1 Alpha-2 in the lower register is always used as the language code.
Payment configurations list request
Returns a list of payment configurations that are configured, enabled, and assigned to this online store/shopping cart.
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment_confs |
action | Y | string, 128 | Must equal get |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<api_version>1.5</api_version> <target>payment_confs</target> <action>get</action>
Response specification
Field | Type | Description |
payment_module | container | |
payment_module/name | string | Name of the payment configuration, as set by the X-Payments admin |
payment_module/id | integer | Identifier of the payment configuration (autoincrement) |
payment_module/transactionTypes | container | |
payment_module/transactionTypes/sale | string | Whether the payment configuration allows "Sale" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/auth | string | Whether the payment configuration allows "Authorize only" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/capture | string | Whether the payment configuration allows "Capture" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/capturePart | string | Whether the payment configuration allows partial "Capture" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/captureMulti | string | Whether the payment configuration allows multiple "Capture" operations ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/void | string | Whether the payment configuration allows "Void" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/voidPart | string | Whether the payment configuration allows partial "Void" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/voidMulti | string | Whether the payment configuration allows multiple "Void" operations ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/refund | string | Whether the payment configuration allows "Refund" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/refundPart | string | Whether the payment configuration allows partial "Refund" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/refundMulti | string | Whether the payment configuration allows multiple "Refund" operations ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/getInfo | string | Whether the payment configuration allows to receive information from the payment gateway ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/accept | string | Whether the payment configuration allows "Accept" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/decline | string | Whether the payment configuration allows "Decline" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/transactionTypes/test | string | Whether the payment configuration allows "Test" operation ("1" - allows, "" empty - doesn't allow) |
payment_module/authCaptureInfo | container | |
payment_module/authCaptureInfo/authExp | integer | How many days the transaction can stay in the Authorized status before being declined automatically |
payment_module/authCaptureInfo/captMinLimit | float | Minimum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no minimum limit, 0.2 - minimum 20% of authorized total, 0.5 - 50% of authorized total, etc.) |
payment_module/authCaptureInfo/captMaxLimit | Maximum capture limit allowed by the payment gateway. Presented as a part of 1 (0 - no maximum limit, 0.5 - 50% of authorized total, 1 - 100% of authorized total, etc.) | |
payment_module/moduleName | string | Default X-Payments name of the payment configuration |
payment_module/settingsHash | string | MD5 hash of the payment configuration settings |
payment_module/currency | string | 3-characters code of currency (ISO 4217). API v1.3 and later. |
payment_module/canSaveCards | string | Whether the payment configuration supports tokenization, i.e. customers' credit card can be saved on the payment gateway ("Y" - supports, "N" - doesn't support). API v1.3 and later. |
payment_module/class | string | Service field of the class name. It is unique for a payment module so it can be used to detect a certain payment gateway. E.g. XPay_Module_SagePayDirect for SagePay, XPay_Module_AuthorizeNet for Authorize.Net AIM, etc. API v1.4 and later. |
payment_module/isTestMode | string | Indicates if the payment configuration is configured in test mode ("Y" - test mode, "N" - live mode). API v1.4 and later. |
Response example
<data> <payment_module type="cell"> <name>First Data Global Gateway e4(SM) Web Service API</name> <id>1</id> <transactionTypes> <sale>1</sale> <auth>1</auth> <capture>1</capture> <capturePart>1</capturePart> <captureMulti></captureMulti> <void>1</void> <voidPart></voidPart> <voidMulti></voidMulti> <refund>1</refund> <refundPart>1</refundPart> <refundMulti>1</refundMulti> <getInfo></getInfo> <accept></accept> <decline></decline> <test></test> </transactionTypes> <authCaptureInfo> <authExp>30</authExp> <captMinLimit>0</captMinLimit> <captMaxLimit>1</captMaxLimit> </authCaptureInfo> <moduleName>First Data Payeezy Gateway (ex- Global Gateway e4)</moduleName> <settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash> <currency>USD</currency> <canSaveCards>Y</canSaveCards> <class>XPay_Module_FirstDataE4</class> <isTestMode>Y</isTestMode> </payment_module> <payment_module type="cell"> <name>Chase Paymentech</name> <id>2</id> <transactionTypes> <sale>1</sale> <auth>1</auth> <capture>1</capture> <capturePart>1</capturePart> <captureMulti></captureMulti> <void>1</void> <voidPart></voidPart> <voidMulti></voidMulti> <refund>1</refund> <refundPart>1</refundPart> <refundMulti></refundMulti> <getInfo></getInfo> <accept></accept> <decline></decline> <test></test> </transactionTypes> <authCaptureInfo> <authExp>30</authExp> <captMinLimit>0</captMinLimit> <captMaxLimit>1</captMaxLimit> </authCaptureInfo> <moduleName>Chase Paymentech</moduleName> <settingsHash>d41d8cd98f00b204e9800998ecf8427e</settingsHash> <currency>USD</currency> <canSaveCards>Y</canSaveCards> <class>XPay_Module_Chase</class> <isTestMode>Y</isTestMode> </payment_module> </data>
Test connection request
Use this request to test the connection between the store and X-Payments. It can also help to detect the version of the X-Payments installation and the API version supported by X-Payments.
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal connect |
action | Y | string, 128 | Must equal test |
testCode | Y | string, 128 | Any string |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<testCode>123</testCode> <api_version>1.5</api_version> <target>connect</target> <action>test</action>
Response specification
Field | Type | Description |
hashCode | string | MD5 hash of the sent code |
error | string | Error code (if any) |
error_message | string | Error message |
is_error_message | string | Flag indicating the error message presence |
version | string | X-Payments version |
Response example
Example of a good response:
<data> <hashCode>202cb962ac59075b964b07152d234b70</hashCode> <error></error> <error_message></error_message> <is_error_message></is_error_message> <version>2.2.0</version> </data>
Example of a response with an error:
<data> <error>506</error> <error_message>Your X-Payments connector module supports API version "1.9". This X-Payments supports the following API versions only: "1.1, 1.2, 1.3, 1.4, 1.5, 1.6".</error_message> <is_error_message></is_error_message> </data>
Payment initialisation request
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal init |
confId | Y | integer | Payment module configuration ID |
refId | Y | string, 128 | Order ID in the online store |
returnUrl | Y | URL, 255 | URL of the page to redirect the customer after payment |
callbackUrl | Y | URL, 255 | URL to which X-Payments sends background requests with service information |
language | N | code of ISO 639-1 (Alpha-2) | Language code. If not specified - en |
cart | Y | container | A container with addresses description |
cart/billingAddress | Y | container | A container with the billing address description |
cart/billingAddress/firstname | Y | string, 255 | |
cart/billingAddress/lastname | N | string, 255 | |
cart/billingAddress/company | N | string, 255 | |
cart/billingAddress/address | Y | string, 255 | |
cart/billingAddress/city | Y | string, 255 | |
cart/billingAddress/state | Y | string, 255 | |
cart/billingAddress/country | Y | string, 2 | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 |
cart/billingAddress/zipcode | Y | string, 32 | |
cart/billingAddress/email | Y | emai, 255l | |
cart/billingAddress/phone | Y | string, 255 | |
cart/billingAddress/fax | N | string, 255 | |
cart/shippingAddress | Y | container | A container with the shipping address description |
cart/shippingAddress/firstname | Y | string, 255 | |
cart/shippingAddress/lastname | N | string, 255 | |
cart/shippingAddress/company | N | string, 255 | |
cart/shippingAddress/address | Y | string, 255 | |
cart/shippingAddress/city | Y | string, 255 | |
cart/shippingAddress/state | Y | string, 255 | |
cart/shippingAddress/country | Y | string, 2 | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 |
cart/shippingAddress/zipcode | Y | string, 32 | |
cart/shippingAddress/email | Y | email, 255 | |
cart/shippingAddress/phone | Y | string, 255 | |
cart/shippingAddress/fax | N | string, 255 | |
cart/items | Y | container | A container with product description |
cart/items/sku | Y | string, 64 | SKU (product code) |
cart/items/name | Y | string, 255 | Product name |
cart/items/price | Y | currency | Product item price |
cart/items/quantity | N | integer | Ordered number of products. If not specified - 1 |
cart/login | Y | string, 255 | Unique customer ID in the online store (login, username, userid, etc.) |
cart/currency | N | string, 3 | Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used |
cart/shippingCost | - | currency | Shipping cost. By default - 0 |
cart/taxCost | - | currency | Tax amount. By default - 0 |
cart/discount | - | currency | Discount amount. By default - 0 |
cart/totalCost | Y | currency | Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount |
cart/description | - | string, 65536 | |
cart/merchantEmail | Y | email, 255 | |
cart/forceTransactionType | - | one of values: A or S or empty A - authorize S - sale |
A flag of forced Sale or Authorize operation. Overrides the setting from the payment configuration. If the value is empty or the field is omitted, the operation is performed according to the payment configuration settings. |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
template (supported by API 1.3 and later) |
N | string | The name of a template in X-Payments requested by the store. Forces the use of the specified template for the payment. If the string passed in this field does not match any template available in X-Payments, it will be ignored. |
saveCard (supported by API 1.3 and later) |
N | string | Customer's choice at checkout ("Y" if customer would like to save the card) |
cart/kountCustomerUniq (supported by API 1.6 and later) |
N | string, 32 | This field is a unique customer identifier in the Kount system, which is send as a UNIQ field. |
List of template names in X-Payments 2.1.x (API v1.3):
- default: A template for the separate page. Used if the payment form is displayed on a separate page of your checkout process (not iframe).
- fast: Iframe for X-Cart 4 Fast Lane Checkout. Used for X-Cart 4 with the Fast Lane Checkout module. The payment form is displayed at the last step of the checkout process.
- lite: Iframe for X-Cart 4 One Page Checkout. Used for X-Cart 4 with the One Page Checkout module. The payment form is displayed in the payment section at checkout.
- magento_iframe: Iframe for Magento. Use this template for Magento and iframe.
- mobile: Template for mobile devices. Used with the X-Cart Mobile module.
- xc5: Iframe for X-Cart 5. Used for X-Cart 5 and iframe.
Request example
<confId>8</confId> <refId>1120</refId> <cart> <login>customer</login> <billingAddress> <firstname>John</firstname> <lastname>Smith</lastname> <address>10 Main street</address> <city>Fillmore</city> <state>UT</state> <country>US</country> <zipcode>84631</zipcode> <company>IQ testing</company> <email>bit-bucket@x-cart.com</email> <phone>927348572</phone> <fax></fax> </billingAddress> <shippingAddress> <firstname>John</firstname> <lastname>Smith</lastname> <address>10 Main street</address> <city>Fillmore</city> <state>UT</state> <country>US</country> <zipcode>84631</zipcode> <company>IQ testing</company> <email>bit-bucket@x-cart.com</email> <phone>927348572</phone> <fax></fax> </shippingAddress> <items type="cell"> <sku>SKU17513</sku> <name>Three Stone Princess Cut Diamond Ring</name> <price>399.99</price> <quantity>1</quantity> </items> <currency>USD</currency> <shippingCost>15</shippingCost> <taxCost>0</taxCost> <discount>0</discount> <totalCost>414.99</totalCost> <description>Order(s) #1120</description> <merchantEmail>bit-bucket@x-cart.com</merchantEmail> <forceTransactionType></forceTransactionType> </cart> <returnUrl>https://example.com/xcart/payment/cc_xpc.php</returnUrl> <callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl> <language>ru</language> <target>payment</target> <action>init</action>
Response specification
Field | Type | Description |
token | string,32 | Temporary payment token, expires immediately after the customer has submitted the cardholder data form |
txnId | string,32 | A unique payment ID. Is used for all further requests to this payment through the API. |
Response example
<data> <token>41b2ef3b34698d4f6ed73151ae7307d2</token> <txnId>e7f398cee98ec062abac0d2c937da181</txnId> <error></error> <error_message></error_message> </data>
Redirecting a customer to the cardholder data entering page
A POST form is created that sends data to the URL <XPayments_web_root>/payment.php; the form contains the following fields:
- target - has the value "main";
- token - uses the value from the token field received in the response to the payment initialisation request.
Request protocol - HTTPS
The form must be sent by the POST method. All data must also be sent as POST variables.
Payment information request
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal get_info |
txnId | Y | string, 32 | Unique payment ID |
refresh | N | 0 or 1 | A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0 |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <refresh>0</target> <target>payment</target> <action>get_info</action>
Response specification
Field | Type | Description |
status | integer, 1 | Payment status code |
message | string, 65536 | Human readable message containing the payment status |
isFraudStatus | 0 or 1 | Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check |
currency | string, 3 | Payment currency code |
amount | currency | Payment total |
authorized | currency | Authorized payment total |
chargedAmount | currency | Charged payment total |
capturedAmount | currency | Captured amount of the authorized amount |
capturedAmountAvail | currency | Amount that is authorized and can be captured |
voidedAmount | currency | Amount that is authorized but voided |
voidedAmountAvail | currency | Amount that is authorized and can be voided |
refundedAmount | currency | Amount that can be refunded |
refundedAmountAvail | currency | Amount that can be refunded |
fraudAuthorized | currency | A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check |
fraudCharged | currency | A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check |
authorizeInProgress | currency | A part of the authorized amount that is being handled by the gateway |
chargeInProgress | currency | A part of the charged amount that is being handled by the gateway |
transactionInProgress | 0 or 1 | Are there any payment transactions handled by the gateway? |
capturedAmountAvailMin | currency | Minimum amount that can be captured from the authorized amount |
capturedAmountAvailGateway | currency | Amount that can be captured from the authorized amount through the gateway |
capturedAmountAvailMinGateway | currency | Minimum amount that can be captured from the authorized amount through the gateway |
voidedAmountAvailGateway | currency | Amount that can be voided from the authorized amount through the gateway |
refundedAmountAvailGateway | currency | Amount that can be refunded from the authorized amount through the gateway |
txnId | string, 32 | Unique payment ID |
lastMessage | string, 65536 | Last gateway message |
error | string, 128 | Error code |
error_message | string, 65536 | Error message |
Response example
<data> <status>2</status> <message>Payment is authorized</message> <isFraudStatus></isFraudStatus> <currency>USD</currency> <amount>414.99</amount> <authorized>414.99</authorized> <chargedAmount>0.00</chargedAmount> <capturedAmount>0.00</capturedAmount> <capturedAmountAvail>414.99</capturedAmountAvail> <voidedAmount>0.00</voidedAmount> <voidedAmountAvail>414.99</voidedAmountAvail> <refundedAmount>0.00</refundedAmount> <refundedAmountAvail>0.00</refundedAmountAvail> <fraudAuthorized>0.00</fraudAuthorized> <fraudCharged>0.00</fraudCharged> <authorizeInProgress>0.00</authorizeInProgress> <chargeInProgress>0.00</chargeInProgress> <transactionInProgress></transactionInProgress> <capturedAmountAvailMin>0.00</capturedAmountAvailMin> <capturedAmountAvailGateway>414.99</capturedAmountAvailGateway> <capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway> <voidedAmountAvailGateway>414.99</voidedAmountAvailGateway> <refundedAmountAvailGateway>0.00</refundedAmountAvailGateway> <txnId>8e67e0da23ce7ed451b2c1adbbd7373c</txnId> <lastMessage>Success</lastMessage> <error></error> <error_message></error_message> </data>
Detailed payment and transaction information request
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal get_additional_info |
txnId | Y | string, 32 | A unique payment ID received in the payment initialisation request response |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <target>payment</target> <action>get_additional_info</action>
Response specification
Field | Type | Description |
payment | container | Payment information request response |
transactions | container | Transaction list |
transactions/date | integer, 11 | Transaction date (Unix timestamp) |
transactions/action | string, 255 | Transaction name |
transactions/status | string, 255 | Transaction status |
transactions/message | string, 65536 | Gateway transaction message |
transactions/total | string, 32 | Transaction amount and currency |
transactions/txnid | string, 255 | Gateway transaction unique ID |
transactions/payment_status | string, 255 | The payment status after the transaction |
transactions/fields | container | Transaction additional fields list |
transactions/fields/name | string, 255 | Field name |
transactions/fields/name | string, 255 | Field value |
payment/cardValidation (API 1.5 and later) |
container | container for Address validation system (AVS) |
payment/cardValidation/avs_z (API 1.5 and later) |
string | Flag for AVS ZIP-code ("0" - unknown, "1" - matches, "2" - does not match) |
payment/cardValidation/avs_c (API 1.5 and later) | string | Flag for AVS cardholder name ("0" - unknown, "1" - matches, "2" - does not match) |
payment/cardValidation/avs_a (API 1.5 and later) | string | Flag for AVS street address ("0" - unknown, "1" - matches, "2" - does not match) |
payment/cardValidation/cvv (API 1.5 and later) | string | Flag for CVV/CVV2/CVD ("0" - unknown, "1" - matches, "2" - does not match) |
payment/maskedCardData (API 1.5 and later) | container | container for Credit Card details (which are allowed to store and display by PA-DSS) |
payment/maskedCardData/first6 (API 1.5 and later) | string | First six digits of the credit card number |
payment/maskedCardData/last4 (API 1.5 and later) | string | Last four digits of the credit card number |
payment/maskedCardData/type (API 1.5 and later) | string | Credit card type: VISA, MC, AMEX, etc |
payment/maskedCardData/expire_month (API 1.5 and later) | string | Credit card expiration month |
payment/maskedCardData/expire_year (API 1.5 and later) | string | Credit card expiration year |
Response example
<data> <payment> <status>2</status> <message>Payment is authorized</message> <isFraudStatus>1</isFraudStatus> <currency>USD</currency> <amount>10.61</amount> <authorized>10.61</authorized> <chargedAmount>0.00</chargedAmount> <capturedAmount>0.00</capturedAmount> <capturedAmountAvail>10.61</capturedAmountAvail> <voidedAmount>0.00</voidedAmount> <voidedAmountAvail>10.61</voidedAmountAvail> <refundedAmount>0.00</refundedAmount> <refundedAmountAvail>0.00</refundedAmountAvail> <fraudAuthorized>0.00</fraudAuthorized> <fraudCharged>0.00</fraudCharged> <authorizeInProgress>0.00</authorizeInProgress> <chargeInProgress>0.00</chargeInProgress> <advinfo> <Message></Message> <Response code>1</Response> <txn_id>6583</txn_id> <Authorization number>ET154399</Authorization> <AVS>5: Cardholder name incorrect, billing address and postal code match</AVS> <Bank message>Approved</Bank> <Bank response code>100</Bank> <CVV2>M: CVV2 / CVC2/CVD Match.</CVV2> <Processing status>Transaction Normal</Processing> <Transarmor Token>8393008475641111</Transarmor> <[Kount] 702650>Distance from Device to Billing > 1000km</[Kount] 702650> <[Kount] 702656>Billing Country not equal to BIN Country (Visa/MC)</[Kount] 702656> <[Kount] 702662>Billing Country not equal to Device Country</[Kount] 702662> <[Kount] Auto>R</[Kount] Auto> <[Kount] Errors></[Kount] Errors> <[Kount] Score>26</[Kount] Score> <[Kount] Transaction ID>3Z7903KDCTT0</[Kount] Transaction ID> <[Kount] Warnings></[Kount] Warnings> </advinfo> <transactionInProgress></transactionInProgress> <capturedAmountAvailMin>0.00</capturedAmountAvailMin> <capturedAmountAvailGateway>10.61</capturedAmountAvailGateway> <capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway> <voidedAmountAvailGateway>10.61</voidedAmountAvailGateway> <refundedAmountAvailGateway>0.00</refundedAmountAvailGateway> <cardValidation> <avs_z>1</avs_z> <avs_c>2</avs_c> <avs_a>1</avs_a> <cvv>1</cvv> </cardValidation> <maskedCardData> <first6>411111</first6> <last4>1111</last4> <type>VISA</type> <expire_month>03</expire_month> <expire_year>2020</expire_year> </maskedCardData> </payment> <transactions type="cell"> <date>1438098759</date> <action>Authorize</action> <status>Success</status> <message>Transaction Normal</message> <total>10.61 USD</total> <txnid>57629270</txnid> <fields type="cell"> <name>Authorization number</name> <value>ET154399</value> </fields> <fields type="cell"> <name>AVS</name> <value>5: Cardholder name incorrect, billing address and postal code match</value> </fields> <fields type="cell"> <name>Bank message</name> <value>Approved</value> </fields> <fields type="cell"> <name>Bank response code</name> <value>100</value> </fields> <fields type="cell"> <name>CVV2</name> <value>M: CVV2 / CVC2/CVD Match.</value> </fields> <fields type="cell"> <name>Processing status</name> <value>Transaction Normal</value> </fields> <fields type="cell"> <name>Transarmor Token</name> <value>8393008475641111</value> </fields> <fields type="cell"> <name>[Kount] 702650</name> <value>Distance from Device to Billing > 1000km</value> </fields> <fields type="cell"> <name>[Kount] 702656</name> <value>Billing Country not equal to BIN Country (Visa/MC)</value> </fields> <fields type="cell"> <name>[Kount] 702662</name> <value>Billing Country not equal to Device Country</value> </fields> <fields type="cell"> <name>[Kount] Auto</name> <value>R</value> </fields> <fields type="cell"> <name>[Kount] Score</name> <value>26</value> </fields> <fields type="cell"> <name>[Kount] Transaction ID</name> <value>3Z7903KDCTT0</value> </fields> <payment_status>Charged</payment_status> </transactions> <error></error> <error_message></error_message> <is_error_message></is_error_message> <version>2.2.0</version> </data>
The following pertains to API 1.5 and later:
If the transaction was checked by Kount antifraud screening service, the "advinfo" and "tansaction/fields" containers contain information of kount results. The field names related to Kount start with the [Kount] prefix. The information can be extracted as follows:
Field | Description |
[Kount] %%%%%, where %%%%% is some number | triggered rule, the number is the number of this rule |
[Kount] Auto | The status of the transaction in Kount ("R" - review, "D" - declined, "A" - approved) |
[Kount] Errors | list of errors (if any) |
[Kount] Warnings: | list of warnings (if any) |
[Kount] Score | Risk score |
[Kount] Transaction ID | Transaction ID in Kount, can be used to display the direct link to the transaction in Kount, https://awc.test.kount.net/workflow/detail.html?id=%%%%%% for test mode or https://awc.kount.net/workflow/detail.html?id=%%%%%%, where %%%%% should be replaced with the transaction ID |
Capture authorized transaction request
Request specification
Field | Required | Type | Description |
target | Y | string,128 | Must equal payment |
action | Y | string, 128 | Must equal capture |
txnId | Y | string, 32 | Unique payment ID |
amount | N | currency | The amount to capture from the previously authorized transaction. By default equals the amount of the authorized transaction |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <amount>50.00</amount> <target>payment</target> <action>capture</action>
Response example
Field | Type | Description |
status | integer, 1 | Operation status code |
message | string, 65536 | Gateway transaction message |
Response example
<data> <status>1</status> <message>Success</message> <error></error> <error_message></error_message> </data>
Void authorized transaction request
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal void |
txnId | Y | string, 32 | Unique payment ID |
amount | N | currency | Amount to void of the authorized transaction. By default equals to the amount of the authorized transaction |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <amount>50.00</amount> <target>payment</target> <action>void</action>
Response specification
Field | Type | Description |
status | integer, 1 | Operation status code |
message | string, 65536 | Gateway transaction message |
Response example
<data> <status>1</status> <message>Success</message> <error></error> <error_message></error_message> </data>
Refund captured transaction request
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal capture |
txnId | Y | string, 32 | Unique payment ID |
amount | N | currency | Amount to be refunded to the customer of the previously captured transactions. By default equals to the amount of captured transactions |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <amount>50.00</amount> <target>payment</target> <action>refund</action>
Response specification
Field | Type | Description |
status | integer, 1 | Operation status code |
message | string, 65536 | Gateway transaction message |
Response example
<data> <status>1</status> <message>Success</message> <error></error> <error_message></error_message> </data>
Blocked by gateway transaction accept request (Accept)
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal accept |
txnId | Y | string, 32 | Unique payment ID |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <target>payment</target> <action>accept</action>
Response example
Field | Type | Description |
status | integer, 1 | Operation status code |
message | string, 65536 | Gateway transaction message |
Response example
<data> <status>1</status> <message>Success</message> <error></error> <error_message></error_message> </data>
Blocked by gateway transaction decline request (Decline)
Request specification
Field | Required | Type | Description |
target | Y | string, 128 | Must equal payment |
action | Y | string, 128 | Must equal decline |
txnId | Y | string, 32 | Unique payment ID |
api_version | Y | string | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc. |
Request example
<txnId>e7f398cee98ec062abac0d2c937da181</txnId> <target>payment</target> <action>decline</action>
Response specification
Field | Type | Description |
status | integer, 1 | Operation status code |
message | string, 65536 | Gateway transaction message |
Response example
<data> <status>1</status> <message>Success</message> <error></error> <error_message></error_message> </data>
Charge again transaction request (Tokenization)
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 |
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 |
Callback request with service payment information
This is a background request that X-Payments sends to the store after a payment has been completed and its result (accepted, declined, etc) has been received from the payment gateway. The request is sent via HTTP POST to the callbackURL defined in the Payment initialisation request. Once this request has been sent, the customer is redirected back to the store.
POSTed data
Field | Value | Type | Description |
action | callback | fixed string | Identifies the callback request |
txnId | (mixed) | string (MD5 hash) | A unique ID of the payment on the side of X-Payments |
updateData | (mixed) | string | Encrypted response from X-Payments |
X-Payments does not expect a response from the store for this request; however, if the HTTP status of the response is not 200 OK, the request is considered failed, and a special notification is sent to the X-Payments admin. The store needs to decrypt the encrypted part of the response and update the order on its side accordingly. Once the updateData value has been decrypted, it is an XML document with the same structure as the response for Payment information request.
Check cart callback request
After the customer has submitted credit card data, right before sending this data to the payment gateway, X-Payments connects to the store to verify the cart total and contents.
The HTTP POST request is sent to the callbackURL defined in the Payment initialisation request.
POSTed data
Field | Value | Type | Description |
action | check_cart | fixed string | Identifies the check-cart callback request |
txnId | (mixed) | string (MD5 hash) | A unique ID of the payment on the side of X-Payments |
refId | (mixed) | string | Order ID (or any other reference) in the online store |
As of API v1.3, the store must respond to this callback request. The response must be an encrypted XML document (i.e. the same way as for other communication between the store and X-Payments).
Encrypted response for check-cart callback request
Field | Required | Type | Description |
status | Y | fixed string | Should be "cart-changed" or "cart-not-changed" |
cart | Y | container | A container with cart/order description. See Payment initialisation request specification for details. This container must be included for "status = cart-changed" and is not necessary for "status = cart-not-changed" |
saveCard | N | string | Whether the customer has chosen to save their card for future use ("Y" if the customer would like to save the card) |
Communication between X-Payments iframe and the store
Communication structure
Communication between the online store (parent frame) and X-Payments (iframe) is implemented with the help of the javascript Window.postMessage method. Notifictions to both the sides represent stringified JSON formatted texts that consist of a service message (string) and an optional list of parameters:
- height: height of the iframe
- error: human readable message
- type: message type. X-Payments sends it as 2, which indicates that the online store should re-initialize the payment. In API v1.3 no other values are supported.
Messages sent from the online store to X-Payments
Submit payment form
X-Payments' iframe does not have a Submit button, so instead of it the payment form should be submitted from the parent window by any kind of "Submit order" or "Place order" button at checkout. At the same time, the special message submitPaymentForm with no parameters should be sent.
{
- message: 'submitPaymentForm',
- params: {}
}
Messages sent from X-Payments to the online store
Iframe is loaded and ready
The message ready notifies the parent window that the payment form is ready. The actual height of the iframe is included in the parameters, so the parent window (checkout page) can perform the necessary adjustments.
{
- message: 'ready',
- params: {
- height: $(document).height()
- }
}
Payment form submitted with an error
The message paymentFormSubmitError with no parameters is sent in the case of any validation error. This may be the case, for example, if the customer's credit card expiration date is in the past, or the credit card number does not match the card type (e.g. VISA, MasterCard), or when a required field has not been submitted (e.g. CVV2). Once the message paymentFormSubmitError with no parameters has been received, the store should not proceed to the next step of the checkout process, but should expect the payment form to be submitted again.
{
- message: 'paymentFormSubmitError',
- params: {}
}
Internal error
The paymentFormSubmitError message with a special set of parameters is used to notify the store if something is wrong outside X-Payments, and X-Payments cannot do anything about it (for example, if the payment gateway has sent an unknown/unexpected piece of data).
{
- message: 'paymentFormSubmitError',
- params: {
- height: $(document).height(),
- error: 'Internal error',
- type: '2'
- }
}
Session is expired
For security reasons the length of the session is limited to 15 minutes. After this period the store has to re-initialize the payment. In this case X-Payments sends the paymentFormSubmitError message with the "Payment session expired" error.
{
- message: 'paymentFormSubmitError',
- params: {
- height: $(document).height(),
- error: 'Payment session expired',
- type: '2'
- }
}
Payment form in Iframe is submitted (supported by API v1.4 and later)
The message paymentFormSubmit notifies the parent window that the payment form has been submitted from the X-Payments side; for example, if a customer clicks the Enter key inside the iframe. Once the store receives this message, it should operate in the same way as though the customer has clicked the Place order button at checkout.
{
- message: 'paymentFormSubmit',
- params: {}
}
Appendix A. Status codes.
Payment status codes
- 1 - New
- 2 - Authorized
- 3 - Declined
- 4 - Charged
- 5 - Refunded
- 6 - Partially refunded
Operation status codes
- 0 - transaction failed
- 1 - transaction is successful
- 2 - transaction is successful and is duplicate