Difference between revisions of "X-Payments:API"

From X-Payments Help
Jump to: navigation, search
m
m
Line 42: Line 42:
 
and have them stored on the side of the online store by an appropriate X-Payments connector.
 
and have them stored on the side of the online store by an appropriate X-Payments connector.
  
−
===Encryption algorithm===
+
===Encryption and communication===
  
−
I. Encryption.
+
'''I. Encryption'''<br />
 
Data is passed as an XML string.
 
Data is passed as an XML string.
  
Line 62: Line 62:
 
#* Write the encrypted and encoded chunks separated with line-breaks.
 
#* Write the encrypted and encoded chunks separated with line-breaks.
  
−
II. Send the request
+
'''II. Send the request'''<br />
  
 
POST the encrypted data to https ://<xpayments_url>/api.php in the following format:
 
POST the encrypted data to https ://<xpayments_url>/api.php in the following format:
Line 73: Line 73:
  
  
−
III. Decrypt the response
+
'''III. Decrypt the response'''<br />
 
The response is a string starting with "API".
 
The response is a string starting with "API".
  
Line 79: Line 79:
 
# Split and decode the encrypted chunks.
 
# Split and decode the encrypted chunks.
 
#* Chunks are separated by line-breaks.
 
#* Chunks are separated by line-breaks.
−
#* Each chunk is decoded with base64.
+
#* Each chunk is encoded with base64.
 
# Decrypt each chunk using the private key.
 
# Decrypt each chunk using the private key.
 
# Combine the decrypted chunks together in a single line.
 
# Combine the decrypted chunks together in a single line.
Line 85: Line 85:
  
  
−
IV. CRC Validation.
+
'''IV. CRC Validation.'''<br />
 
A response is received in a single line. It contains the following data, consecutively:
 
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.
 
length of Salt, Salt, length of CRC, CRC, length of Data, Data.

Revision as of 11:18, 20 July 2016

Contents

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:

  1. a public and a private key to encrypt requests/responses from the online store to X-Payments;
  2. 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 and communication

I. Encryption
Data is passed as an XML string.

  1. Get the Salt block.
    • Generate a 32-character string formed of random characters from 33 to 255.
  2. Get the CRC block.
    • Generate MD5 in the binary format of the passed data.
    • Prepend it with the "     MD5" prefix (the five preceding spaces are mandatory!)
  3. 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.
  4. Split the data into chunks of 128 characters.
  5. Encrypt each chunk consecutively using the public key.
  6. Encode each chunk with base64.
  7. 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".

  1. Remove the leading "API" word. If the response does not start with "API", it means that it is incorrect.
  2. Split and decode the encrypted chunks.
    • Chunks are separated by line-breaks.
    • Each chunk is encoded with base64.
  3. Decrypt each chunk using the private key.
  4. Combine the decrypted chunks together in a single line.
  5. 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.

  1. Extract Salt
    • Get the salt length from the first 12 characters.
    • Shift the salt block by its length.
  2. Extract CRC:
    • Get the CRC length from the first 12 characters.
    • Shift the CRC block by its length.
    • Remove the "     MD5" prefix from CRC.
  3. Extract data
    • Get the data length from the first 12 characters
    • Shift the data block by its length
  4. Calculate the MD5 checksum in the binary format of the received data.
  5. 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
Note: Fields ending in "Gateway" contain amounts that can be used in transactions through the gateway. For example, if a sum of $100 was authorized, and then a capture transaction was emulated for $100, the next refund operation will be available in the emulation mode only. The value of the refundedAmountAvailGateway field will be equal to 0.

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


See also

Retrieved from "https://www.x-payments.com/help/?title=X-Payments:API&oldid=721"