Difference between revisions of "X-Payments:API"

From X-Payments Help
Jump to: navigation, search
(API versions supported)
m (See also)
 
(42 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
<div id="APIversions"></div>
 
== API versions supported ==
 
== API versions supported ==
  
Line 6: Line 7:
 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015)<br />
 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015)<br />
 
'''API v1.5''': X-Payments 2.2 (June 2015)<br />
 
'''API v1.5''': X-Payments 2.2 (June 2015)<br />
'''API v1.6''': X-Payments 3.x (June 2016)<br /><br />
+
'''API v1.6''': X-Payments 3.0.0 (June 2016)<br />
 +
'''API v1.7''': X-Payments 3.0.2 (August 2016)<br />
 +
'''API v1.8''': X-Payments 3.1.0 (July 2017)<br />
 +
'''API v1.9''': X-Payments 3.1.2 (April 2018)<br />
  
==Samples==
+
<div id="APIrequests"></div>
 
 
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==
 
==API requests==
  
All API requests are made to the '''httрs://<xpayments_url>/api.php''' URL.
+
All API requests are made to the '''https ://<xpayments_url>/api.php''' URL.
 
Only HTTPS protocol is used.
 
Only HTTPS protocol is used.
 
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.
 
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.
  
'''Request/Response encryption'''
+
<div id="RequestResponseEncryption"></div>
 +
===Request/Response encryption===
  
 
* Encryption method used: RSA;
 
* Encryption method used: RSA;
Line 36: Line 36:
 
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.
 
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 commumication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:
+
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),
+
:* Public key from the first pair (Online store -> X-Payments),
:* Private key from the second pair (X-Payments Online store),
+
:* Private key from the second pair (X-Payments -> Online store),
 
:* Private key password,
 
:* Private key password,
 
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.
  
 +
<div id="EncryptionAndCommunication"></div>
 +
===Encryption and communication===
 +
 +
'''I. Encryption'''<br />
 +
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 "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MD5" prefix (the five preceding 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'''<br />
 +
 +
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'''<br />
 +
The response is a string starting with "API".
  
'''Encryption algorithm:'''
+
# 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 encoded 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.
  
# An empty string is created for pre-prepared data.
 
# A 32-character salt-block is formed of random characters from 33 to 255.
 
# The length of the salt-block in bites is taken and transformed into a 12-character string by adding zeros before it.
 
# The salt-block length string and the salt-block are added to the pre-prepared data.
 
# MD5 digital signature is taken from the data. The signature is formed as a HEX (32-character string).
 
# The length of the digital signature in bites is taken and transformed into a 12-character string by adding zeros before it.
 
# The digital signature length string and the digital signature are added to the pre-prepared data.
 
# The length of the data string in bites is taken and transformed into a 12-character string by adding zeros before it.
 
# The data string length string and the data string are added to the pre-prepared data.
 
# The string of pre-prepared data is divided into 128 bite chunks.
 
# Each chunk is encrypted using a public key.
 
# Each chunk is encoded with base64.
 
# Chunks are glued together using a line feed character (0x0a).
 
# API prefix is added to the glued chunks.
 
  
 +
'''IV. CRC Validation.'''<br />
 +
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 "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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.
 +
 +
<div id="cURLAsAMeansOfSendingRequests"></div>
 
===cURL as a means of sending requests===
 
===cURL as a means of sending requests===
  
Line 66: Line 110:
 
TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.
 
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.
+
Use the latest TLSv1.2, since the previous protocols and implementations contain security vulnerabilities, and thus must not be used according to PCI DSS.
  
 +
<div id="DataTypes"></div>
 
===Data types===
 
===Data types===
  
Line 82: Line 127:
 
ISO 639-1 Alpha-2 in the lower register is always used as the language code.
 
ISO 639-1 Alpha-2 in the lower register is always used as the language code.
  
==Payment configurations list request==
+
<div id="APIRequestsFromStoreToXP"></div>
 +
==API Requests from the store to X-Payments==
  
Returns a list of payment configurations that are configured, enabled, and assigned to this online store/shopping cart.
+
<div id="AdminAreaXPConfiguration"></div>
 +
===Admin area/X-Payments configuration===
 +
* [[X-Payments:Test_connection_request|Test connection request]]
 +
* [[X-Payments:Payment_configurations_list_request|Payment configurations list request]]<br />
  
===Request specification===
+
<div id="PaymentCreation"></div>
 +
===Payment creation (Regular payment and tokenization)===
 +
* [[X-Payments:Payment_initialisation_request|Payment initialisation request]]<br />
 +
* [[X-Payments:Charge_again_transaction_request_(Tokenization)|Charge again transaction request (Tokenization)]]
  
{| cellspacing="0" cellpadding="2" border="1"
+
<div id="PaymentInformation"></div>
| colspan="1" | '''Field'''
+
===Payment information===
| colspan="1" | '''Required'''
+
* [[X-Payments:Payment_information_request|Payment information request]]<br />
| colspan="1" | '''Type'''
+
* [[X-Payments:Detailed_payment_and_transaction_information_request|Detailed payment and transaction information request]]
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment_confs
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal get
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
<br />
 
  
===Request example===
+
<div id="ActionsOnPayments"></div>
 +
===Actions on payments (secondary actions)===
 +
* [[X-Payments:Capture_authorized_transaction_request|Capture authorized transaction request]]<br />
 +
* [[X-Payments:Void_authorized_transaction_request|Void authorized transaction request]]<br />
 +
* [[X-Payments:Refund_captured_transaction_request|Refund captured transaction request]]<br />
 +
* [[X-Payments:Accept_potentially_fraudulent_transaction_request|Accept potentially fraudulent transaction request]]<br />
 +
* [[X-Payments:Decline_potentially_fraudulent_transaction_request|Decline potentially fraudulent transaction request]]
  
<pre>
+
<div id="CallbackRequests"></div>
<api_version>1.5</api_version>
 
<target>payment_confs</target>
 
<action>get</action>
 
</pre>
 
<br />
 
  
===Response specification===
+
==Callback requests (web-hooks) from X-Payments to the store==
 +
* [[X-Payments:Callback_request_with_service_payment_information|Callback request with service payment information]]<br />
 +
* [[X-Payments:Check_cart_callback_request|Check cart callback request]]
  
{| cellspacing="0" cellpadding="2" border="1"
+
<div id="BrowserRelated"></div>
| colspan="1" | '''Field'''
+
==Browser-related==
| colspan="1" | '''Type'''
+
* [[X-Payments:Redirecting_a_customer_to_the_cardholder_data_entering_page|Redirecting a customer to the cardholder data entering page]]<br />
| colspan="1" | '''Description'''
+
* [[X-Payments:Communication_between_X-Payments_iframe_and_the_store|Communication between X-Payments iframe and the store]]
|-
 
| colspan="1" | payment_module
 
| colspan="1" | container
 
| colspan="1" |
 
|-
 
| colspan="1" | payment_module/name
 
| colspan="1" | string
 
| colspan="1" | Name of the payment configuration, as set by the X-Payments admin
 
|-
 
| colspan="1" | payment_module/id
 
| colspan="1" | integer
 
| colspan="1" | Identifier of the payment configuration (autoincrement)
 
|-
 
| colspan="1" | payment_module/transactionTypes
 
| colspan="1" | container
 
| colspan="1" |
 
|-
 
| colspan="1" | payment_module/transactionTypes/sale
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Sale" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/auth
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Authorize only" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/capture
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Capture" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/capturePart
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows partial "Capture" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/captureMulti
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows multiple "Capture" operations ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/void
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Void" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/voidPart
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows partial "Void" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/voidMulti
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows multiple "Void" operations ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/refund
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Refund" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/refundPart
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows partial "Refund" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/refundMulti
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows multiple "Refund" operations ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/getInfo
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows to receive information from the payment gateway ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/accept
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Accept" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/decline
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Decline" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/transactionTypes/test
 
| colspan="1" | string
 
| colspan="1" | Whether the payment configuration allows "Test" operation ("1" - allows, "" empty - doesn't allow)
 
|-
 
| colspan="1" | payment_module/authCaptureInfo
 
| colspan="1" | container
 
| colspan="1" |
 
|-
 
| colspan="1" | payment_module/authCaptureInfo/authExp
 
| colspan="1" | integer
 
| colspan="1" | How many days the transaction can stay in the Authorized status before being declined automatically
 
|-
 
| colspan="1" | payment_module/authCaptureInfo/captMinLimit
 
| colspan="1" | float
 
| colspan="1" | 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.)
 
|-
 
| colspan="1" | payment_module/authCaptureInfo/captMaxLimit
 
| colspan="1" |
 
| colspan="1" | 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.)
 
|-
 
| colspan="1" | payment_module/moduleName
 
| colspan="1" | string
 
| colspan="1" | Default X-Payments name of the payment configuration
 
|-
 
| colspan="1" | payment_module/settingsHash
 
| colspan="1" | string
 
| colspan="1" | MD5 hash of the payment configuration settings
 
|-
 
| colspan="1" | payment_module/currency
 
| colspan="1" | string
 
| colspan="1" | 3-characters code of currency (ISO 4217). API v1.3 and later.
 
|-
 
| colspan="1" | payment_module/canSaveCards
 
| colspan="1" | string
 
| colspan="1" | 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.
 
|-
 
| colspan="1" | payment_module/class
 
| colspan="1" | string
 
| colspan="1" | 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.
 
|-
 
| colspan="1" | payment_module/isTestMode
 
| colspan="1" | string
 
| colspan="1" | Indicates if the payment configuration is configured in test mode ("Y" - test mode, "N" - live mode). API v1.4 and later.
 
|}
 
<br />
 
  
===Response example===
+
<div id="CodeSamples"></div>
 +
==Code samples==
 +
We have prepared some code samples written in PHP demonstrating communication with X-Payments, request encryption and response decryption. The recommended way to use this code is console PHP (i.e. via command line) on the *nix OS.
  
 +
To use the code samples:
 +
# Download the [http://s.x-cart.com/xp_api_samples archive with code samples].
 +
# Upload it on the server.
 +
# Extract the files and execute the script as follows:
 
<pre>
 
<pre>
<data>
+
[user@host]$ ls -la
  <payment_module type="cell">
+
total 72
    <name>First Data Global Gateway e4(SM) Web Service API</name>
+
drwxrwxr-2 user user  4096 Nov 18 14:26 .
    <id>1</id>
+
drwxrwxr-x 17 user user  4096 Sep  5 07:24 ..
    <transactionTypes>
+
-rw-r--r--  1 user user 11141 Nov 18 14:24 API.php
      <sale>1</sale>
+
-rw-r--r--  1 user user  656 Nov 16 01:54 connect_test.php
      <auth>1</auth>
+
-rw-r--r--  1 user user  500 Nov 16 01:55 payment_accept.php
      <capture>1</capture>
+
-rw-r--r--  1 user user  503 Nov 16 01:54 payment_capture.php
      <capturePart>1</capturePart>
+
-rw-r--r--  1 user user  576 Nov 16 01:54 payment_confs_get.php
      <captureMulti></captureMulti>
+
-rw-r--r--  1 user user  502 Nov 16 01:54 payment_decline.php
      <void>1</void>
+
-rw-r--r--  1 user user  528 Nov 16 01:54 payment_get_additional_info.php
      <voidPart></voidPart>
+
-rw-r--r--  1 user user   493 Nov 16 01:56 payment_get_info.php
      <voidMulti></voidMulti>
+
-rw-r--r-- 1 user user  1958 Nov 18 14:26 payment_init.php
      <refund>1</refund>
+
-rw-r--r--  1 user user  707 Nov 16 01:54 payment_recharge.php
      <refundPart>1</refundPart>
+
-rw-r--r-- 1 user user  2073 Nov 16 01:54 payment_recharge.with.cart.php
      <refundMulti>1</refundMulti>
+
-rw-r--r--  1 user user  498 Nov 16 01:54 payment_refund.php
      <getInfo></getInfo>
+
-rw-r--r--  1 user user  496 Nov 16 01:54 payment_void.php
      <accept></accept>
+
-rw-r--r-- 1 user user  819 Nov 16 01:54 redirect.html
      <decline></decline>
+
[user@host]$ php connect_test.php
      <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>
 
</pre>
 
<br />
 
 
 
==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===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal connect
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal test
 
|-
 
| colspan="1" | testCode
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Any string
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
<br />
 
 
 
===Request example===
 
 
 
<pre>
 
<testCode>123</testCode>
 
<api_version>1.5</api_version>
 
<target>connect</target>
 
<action>test</action>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | hashCode
 
| colspan="1" | string
 
| colspan="1" | MD5 hash of the sent code
 
|-
 
| colspan="1" | error
 
| colspan="1" | string
 
| colspan="1" | Error code (if any)
 
|-
 
| colspan="1" | error_message
 
| colspan="1" | string
 
| colspan="1" | Error message
 
|-
 
| colspan="1" | is_error_message
 
| colspan="1" | string
 
| colspan="1" | Flag indicating the error message presence
 
|-
 
| colspan="1" | version
 
| colspan="1" | string
 
| colspan="1" | X-Payments version
 
|}
 
<br />
 
 
 
===Response example===
 
 
 
Example of a good response:
 
<pre>
 
 
<data>
 
<data>
 
   <hashCode>202cb962ac59075b964b07152d234b70</hashCode>
 
   <hashCode>202cb962ac59075b964b07152d234b70</hashCode>
Line 397: Line 197:
 
   <error_message></error_message>
 
   <error_message></error_message>
 
   <is_error_message></is_error_message>
 
   <is_error_message></is_error_message>
   <version>2.2.0</version>
+
   <version>3.0.2</version>
</data>
 
</pre>
 
 
 
Example of a response with an error:
 
<pre>
 
<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>
 
</pre>
 
<br />
 
 
 
==Payment initialisation request==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal init
 
|-
 
| colspan="1" | confId
 
| colspan="1" | Y
 
| colspan="1" | integer
 
| colspan="1" | Payment module configuration ID
 
|-
 
| colspan="1" | refId
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Order ID in the online store
 
|-
 
| colspan="1" | returnUrl
 
| colspan="1" | Y
 
| colspan="1" | URL, 255
 
| colspan="1" | URL of the page to redirect the customer after payment
 
|-
 
| colspan="1" | callbackUrl
 
| colspan="1" | Y
 
| colspan="1" | URL, 255
 
| colspan="1" | URL to which X-Payments sends background requests with service information
 
|-
 
| colspan="1" | language
 
| colspan="1" | N
 
| colspan="1" | code of ISO 639-1 (Alpha-2)
 
| colspan="1" | Language code. If not specified - en
 
|-
 
| colspan="1" | cart
 
| colspan="1" | Y
 
| colspan="1" | container
 
| colspan="1" | A container with addresses description
 
|-
 
| colspan="1" | cart/billingAddress
 
| colspan="1" | Y
 
| colspan="1" | container
 
| colspan="1" | A container with the billing address description
 
|-
 
| colspan="1" | cart/billingAddress/firstname
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/lastname
 
| colspan="1" | N
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/company
 
| colspan="1" | N
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/address
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/city
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/state
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/country
 
| colspan="1" | Y
 
| colspan="1" | string, 2
 
| colspan="1" | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 
|-
 
| colspan="1" | cart/billingAddress/zipcode
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/email
 
| colspan="1" | Y
 
| colspan="1" | emai, 255l
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/phone
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/billingAddress/fax
 
| colspan="1" | N
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress
 
| colspan="1" | Y
 
| colspan="1" | container
 
| colspan="1" | A container with the shipping address description
 
|-
 
| colspan="1" | cart/shippingAddress/firstname
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/lastname
 
| colspan="1" | N
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/company
 
| colspan="1" | N
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/address
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/city
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/state
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/country
 
| colspan="1" | Y
 
| colspan="1" | string, 2
 
| colspan="1" | ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 
|-
 
| colspan="1" | cart/shippingAddress/zipcode
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/email
 
| colspan="1" | Y
 
| colspan="1" | email, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/phone
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/shippingAddress/fax
 
| colspan="1" | N
 
| colspan="1" | string, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/items
 
| colspan="1" | Y
 
| colspan="1" | container
 
| colspan="1" | A container with product description
 
|-
 
| colspan="1" | cart/items/sku
 
| colspan="1" | Y
 
| colspan="1" | string, 64
 
| colspan="1" | SKU (product code)
 
|-
 
| colspan="1" | cart/items/name
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" | Product name
 
|-
 
| colspan="1" | cart/items/price
 
| colspan="1" | Y
 
| colspan="1" | currency
 
| colspan="1" | Product item price
 
|-
 
| colspan="1" | cart/items/quantity
 
| colspan="1" | N
 
| colspan="1" | integer
 
| colspan="1" | Ordered number of products. If not specified - 1
 
|-
 
| colspan="1" | cart/login
 
| colspan="1" | Y
 
| colspan="1" | string, 255
 
| colspan="1" | Unique customer ID in the online store (login, username, userid, etc.)
 
|-
 
| colspan="1" | cart/currency
 
| colspan="1" | N
 
| colspan="1" | string, 3
 
| colspan="1" | Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used
 
|-
 
| colspan="1" | cart/shippingCost
 
| colspan="1" | -
 
| colspan="1" | currency
 
| colspan="1" | Shipping cost. By default - 0
 
|-
 
| colspan="1" | cart/taxCost
 
| colspan="1" | -
 
| colspan="1" | currency
 
| colspan="1" | Tax amount. By default - 0
 
|-
 
| colspan="1" | cart/discount
 
| colspan="1" | -
 
| colspan="1" | currency
 
| colspan="1" | Discount amount. By default - 0
 
|-
 
| colspan="1" | cart/totalCost
 
| colspan="1" | Y
 
| colspan="1" | currency
 
| colspan="1" | Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount
 
|-
 
| colspan="1" | cart/description
 
| colspan="1" | -
 
| colspan="1" | string, 65536
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/merchantEmail
 
| colspan="1" | Y
 
| colspan="1" | email, 255
 
| colspan="1" |
 
|-
 
| colspan="1" | cart/forceTransactionType
 
| colspan="1" | -
 
| colspan="1" | one of values: A or S or empty <br />A - authorize <br />S - sale
 
| colspan="1" | 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.
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|-
 
| colspan="1" | template <br />(''supported by API 1.3 and later'')
 
| colspan="1" | N
 
| colspan="1" | string
 
| colspan="1" | 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.
 
|-
 
| colspan="1" | saveCard <br />(''supported by API 1.3 and later'')
 
| colspan="1" | N
 
| colspan="1" | string
 
| colspan="1" | Customer's choice at checkout (“Y” if customer would like to save the card)
 
|-
 
| colspan="1"  | cart/kountCustomerUniq <br />(''supported by API 1.6 and later'')
 
| colspan="1"  | N
 
| colspan="1"  | string, 32
 
| colspan="1"  | This field is a unique customer identifier in the Kount system, which is send as a UNIQ field.
 
|}
 
<br />
 
'''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===
 
 
 
<pre>
 
<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>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | token
 
| colspan="1" | string,32
 
| colspan="1" | Temporary payment token, expires immediately after the customer has submitted the cardholder data form
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | string,32
 
| colspan="1" | A unique payment ID. Is used for all further requests to this payment through the API.
 
|}
 
 
 
===Response example===
 
 
 
<pre>
 
<data>
 
<token>41b2ef3b34698d4f6ed73151ae7307d2</token>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<error></error>
 
<error_message></error_message>
 
</data>
 
</pre>
 
 
 
==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 <br />
 
The form must be sent by the POST method. All data must also be sent as POST variables.
 
 
 
==Payment information request==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal get_info
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | refresh
 
| colspan="1" | N
 
| colspan="1" | 0 или 1
 
| colspan="1" | A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
 
 
===Request example===
 
 
 
<pre>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<refresh>0</target>
 
<target>payment</target>
 
<action>get_info</action>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Payment status codes|Payment status code]]
 
|-
 
| colspan="1" | message
 
| colspan="1" | string, 65536
 
| colspan="1" | Human readable message containing the payment status
 
|-
 
| colspan="1" | isFraudStatus
 
| colspan="1" | 0 or 1
 
| colspan="1" | Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check
 
|-
 
| colspan="1" | currency
 
| colspan="1" | string, 3
 
| colspan="1" | Payment currency code
 
|-
 
| colspan="1" | amount
 
| colspan="1" | currency
 
| colspan="1" | Payment total
 
|-
 
| colspan="1" | authorized
 
| colspan="1" | currency
 
| colspan="1" | Authorized payment total
 
|-
 
| colspan="1" | chargedAmount
 
| colspan="1" | currency
 
| colspan="1" | Charged payment total
 
|-
 
| colspan="1" | capturedAmount
 
| colspan="1" | currency
 
| colspan="1" | Captured amount of the authorized amount
 
|-
 
| colspan="1" | capturedAmountAvail
 
| colspan="1" | currency
 
| colspan="1" | Amount that is authorized and can be captured
 
|-
 
| colspan="1" | voidedAmount
 
| colspan="1" | currency
 
| colspan="1" | Amount that is authorized but voided
 
|-
 
| colspan="1" | voidedAmountAvail
 
| colspan="1" | currency
 
| colspan="1" | Amount that is authorized and can be voided
 
|-
 
| colspan="1" | refundedAmount
 
| colspan="1" | currency
 
| colspan="1" | Amount that can be refunded
 
|-
 
| colspan="1" | refundedAmountAvail
 
| colspan="1" | currency
 
| colspan="1" | Amount that can be refunded
 
|-
 
| colspan="1" | fraudAuthorized
 
| colspan="1" | currency
 
| colspan="1" | A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check
 
|-
 
| colspan="1" | fraudCharged
 
| colspan="1" | currency
 
| colspan="1" | A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check
 
|-
 
| colspan="1" | authorizeInProgress
 
| colspan="1" | currency
 
| colspan="1" | A part of the authorized amount that is being handled by the gateway
 
|-
 
| colspan="1" | chargeInProgress
 
| colspan="1" | currency
 
| colspan="1" | A part of the charged amount that is being handled by the gateway
 
|-
 
| colspan="1" | transactionInProgress
 
| colspan="1" | 0 или 1
 
| colspan="1" | Are there any payment transactions handled by the gateway?
 
|-
 
| colspan="1" | capturedAmountAvailMin
 
| colspan="1" | currency
 
| colspan="1" | Minimum amount that can be captured from the authorized amount
 
|-
 
| colspan="1" | capturedAmountAvailGateway
 
| colspan="1" | currency
 
| colspan="1" | Amount that can be captured from the authorized amount through the gateway
 
|-
 
| colspan="1" | capturedAmountAvailMinGateway
 
| colspan="1" | currency
 
| colspan="1" | Minimum amount that can be captured from the authorized amount through the gateway
 
|-
 
| colspan="1" | voidedAmountAvailGateway
 
| colspan="1" | currency
 
| colspan="1" | Amount that can be voided from the authorized amount through the gateway
 
|-
 
| colspan="1" | refundedAmountAvailGateway
 
| colspan="1" | currency
 
| colspan="1" | Amount that can be refunded from the authorized amount through the gateway
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | lastMessage
 
| colspan="1" | string, 65536
 
| colspan="1" | Last gateway message
 
|-
 
| colspan="1" | error
 
| colspan="1" | string, 128
 
| colspan="1" | Error code
 
|-
 
| colspan="1" | error_message
 
| colspan="1" | string, 65536
 
| colspan="1" | 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===
 
 
 
<pre>
 
<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>
 
</pre>
 
 
 
==Detailed payment and transaction information request==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal get_additional_info
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | A unique payment ID received in the payment initialisation request response
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
 
 
===Request example===
 
 
 
<pre>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<target>payment</target>
 
<action>get_additional_info</action>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | payment
 
| colspan="1" | container
 
| colspan="1" | Payment information request response
 
|-
 
| colspan="1" | transactions
 
| colspan="1" | container
 
| colspan="1" | Transaction list
 
|-
 
| colspan="1" | transactions/date
 
| colspan="1" | integer, 11
 
| colspan="1" | Transaction date (Unix timestamp)
 
|-
 
| colspan="1" | transactions/action
 
| colspan="1" | string, 255
 
| colspan="1" | Transaction name
 
|-
 
| colspan="1" | transactions/status
 
| colspan="1" | string, 255
 
| colspan="1" | Transaction status
 
|-
 
| colspan="1" | transactions/message
 
| colspan="1" | string, 65536
 
| colspan="1" | Gateway transaction message
 
|-
 
| colspan="1" | transactions/total
 
| colspan="1" | string, 32
 
| colspan="1" | Transaction amount and currency
 
|-
 
| colspan="1" | transactions/txnid
 
| colspan="1" | string, 255
 
| colspan="1" | Gateway transaction unique ID
 
|-
 
| colspan="1" | transactions/payment_status
 
| colspan="1" | string, 255
 
| colspan="1" | The payment status after the transaction
 
|-
 
| colspan="1" | transactions/fields
 
| colspan="1" | container
 
| colspan="1" | Transaction additional fields list
 
|-
 
| colspan="1" | transactions/fields/name
 
| colspan="1" | string, 255
 
| colspan="1" | Field name
 
|-
 
| colspan="1" | transactions/fields/name
 
| colspan="1" | string, 255
 
| colspan="1" | Field value
 
|-
 
| colspan="1" | payment/cardValidation <br />(API 1.5 and later)
 
| colspan="1" | container
 
| colspan="1" | container for Address validation system (AVS)
 
|-
 
| colspan="1" | payment/cardValidation/avs_z <br />(API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Flag for AVS ZIP-code ("0" - unknown, "1" - matches, "2" - does not match)
 
|-
 
| colspan="1" | payment/cardValidation/avs_c (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Flag for AVS cardholder name ("0" - unknown, "1" - matches, "2" - does not match)
 
|-
 
| colspan="1" | payment/cardValidation/avs_a (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Flag for AVS street address ("0" - unknown, "1" - matches, "2" - does not match)
 
|-
 
| colspan="1" | payment/cardValidation/cvv (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Flag for CVV/CVV2/CVD ("0" - unknown, "1" - matches, "2" - does not match)
 
|-
 
| colspan="1" | payment/maskedCardData (API 1.5 and later)
 
| colspan="1" | container
 
| colspan="1" | container for Credit Card details (which are allowed to store and display by PA-DSS)
 
|-
 
| colspan="1" | payment/maskedCardData/first6 (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | First six digits of the credit card number
 
|-
 
| colspan="1" | payment/maskedCardData/last4 (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Last four digits of the credit card number
 
|-
 
| colspan="1" | payment/maskedCardData/type (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Credit card type: VISA, MC, AMEX, etc
 
|-
 
| colspan="1" | payment/maskedCardData/expire_month (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Credit card expiration month
 
|-
 
| colspan="1" | payment/maskedCardData/expire_year (API 1.5 and later)
 
| colspan="1" | string
 
| colspan="1" | Credit card expiration year
 
|}
 
 
 
===Response example===
 
 
 
<pre>
 
<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 &gt; 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 &gt; 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>
 
</pre>
 
 
 
<br />
 
''The following pertains to API 1.5 and later:''<br />
 
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:
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1"| [Kount] %%%%%, where %%%%% is some number
 
| colspan="1"| triggered rule, the number is the number of this rule
 
|-
 
| colspan="1"| [Kount] Auto
 
| colspan="1"| The status of the transaction in Kount ("R" - review, "D" - declined, "A" - approved)
 
|-
 
| colspan="1"| [Kount] Errors
 
| colspan="1"| list of errors (if any)
 
|-
 
| colspan="1"| [Kount] Warnings:
 
| colspan="1"| list of warnings (if any)
 
|-
 
| colspan="1"| [Kount] Score
 
| colspan="1"|  Risk score
 
|-
 
| colspan="1"| [Kount] Transaction ID
 
| colspan="1"| 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
 
|}
 
<br />
 
 
 
==Capture authorized transaction request==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string,128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal capture
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | amount
 
| colspan="1" | N
 
| colspan="1" | currency
 
| colspan="1" | The amount to capture from the previously authorized transaction. By default equals the amount of the authorized transaction
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
 
 
 
 
=== Request example ===
 
 
 
 
 
<pre>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<amount>50.00</amount>
 
<target>payment</target>
 
<action>capture</action>
 
</pre>
 
 
 
===Response example===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Operation status codes|Operation status code]]
 
|-
 
| colspan="1" | message
 
| colspan="1" | string, 65536
 
| colspan="1" | Gateway transaction message
 
|}
 
 
 
Response example  <pre><data>
 
<status>1</status>
 
<message>Success</message>
 
<error></error>
 
<error_message></error_message>
 
</data>
 
</pre>
 
 
 
==Void authorized transaction request==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal void
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | amount
 
| colspan="1" | N
 
| colspan="1" | currency
 
| colspan="1" | Amount to void of the authorized transaction. By default equals to the amount of the authorized transaction
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
 
 
===Request example===
 
 
 
<pre>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<amount>50.00</amount>
 
<target>payment</target>
 
<action>void</action>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Operation status codes|Operation status code]]
 
|-
 
| colspan="1" | message
 
| colspan="1" | string, 65536
 
| colspan="1" | Gateway transaction message
 
|}
 
 
 
===Response example===
 
 
 
<pre>
 
<data>
 
<status>1</status>
 
<message>Success</message>
 
<error></error>
 
<error_message></error_message>
 
</data>
 
</pre>
 
 
 
==Refund captured transaction request==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal capture
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | amount
 
| colspan="1" | N
 
| colspan="1" | currency
 
| colspan="1" | Amount to be refunded to the customer of the previously captured transactions. By default equals to the amount of captured transactions
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
 
 
===Request example===
 
 
 
<pre><txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<amount>50.00</amount>
 
<target>payment</target>
 
<action>refund</action>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Operation status codes|Operation status code]]
 
|-
 
| colspan="1" | message
 
| colspan="1" | string, 65536
 
| colspan="1" | Gateway transaction message
 
|}
 
 
 
===Response example===
 
 
 
<pre><data>
 
<status>1</status>
 
<message>Success</message>
 
<error></error>
 
<error_message></error_message>
 
</data>
 
</pre>
 
 
 
==Blocked by gateway transaction accept request (Accept)==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal accept
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
 
 
===Request example===
 
 
 
<pre>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<target>payment</target>
 
<action>accept</action>
 
</pre>
 
 
 
===Response example===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Operation status codes|Operation status code]]
 
|-
 
| colspan="1" | message
 
| colspan="1" | string, 65536
 
| colspan="1" | Gateway transaction message
 
|}
 
 
 
Response example  <pre><data>
 
<status>1</status>
 
<message>Success</message>
 
<error></error>
 
<error_message></error_message>
 
 
</data>
 
</data>
 
</pre>
 
</pre>
  
==Blocked by gateway transaction decline request (Decline)==
+
Notes on using the code samples:
 
+
:* The code is provided as is, and is supposed to be used ''for demonstration only''. We will not be held responsible for any damage caused by using this code on production deployments/live installations. Please use it at your own risk.
===Request specification===
+
:* To simplify the code, some sensitive information (like the private key and the private key passphrase) was hard-coded in the script. This way, storing the keys "as is" is ''strongly not recommended''. Instead, the keys should be stored encrypted in some way.
 +
:* For the salt generation, the openssl_random_pseudo_bytes() function is used. However, it has known issues; make sure it generates a cryptographically secure sequence. Please check: https://bugs.php.net/bug.php?id=70014. If necessary, you may use another way to generate a cryptographically secure random string. See: http://stackoverflow.com/questions/31492921/cryptographically-secure-random-string-function.
 +
:* The keys hard-coded in the sample are taken from the X-Payments installation at https://demo.xpayments.com. So some operations work out of the box, e.g. [[X-Payments:Payment_initialisation_request | payment initialization]], [[X-Payments:Payment_information_request | payment information]], [[X-Payments:Test_connection_request | test request]], [[X-Payments:Payment_configurations_list_request | obtaining payment configurations]], etc. But some operations will give an error, since the actual payment information on the demo stand can be changed. This applies to secondary operations: [[X-Payments:Capture_authorized_transaction_request | capture]], [[X-Payments:Void_authorized_transaction_request | void]], [[X-Payments:Refund_captured_transaction_request | refund]], etc. To see the successful result, you should change the '''txnId''' fields hard-coded in the scripts.
  
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal decline
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|}
 
  
===Request example===
+
<div id="AppendixAStatusCodes"></div>
 
 
<pre>
 
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
 
<target>payment</target>
 
<action>decline</action>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Operation status codes|Operation status code]]
 
|-
 
| colspan="1" | message
 
| colspan="1" | string, 65536
 
| colspan="1" | Gateway transaction message
 
|}
 
 
 
===Response example===
 
 
 
<pre>
 
<data>
 
<status>1</status>
 
<message>Success</message>
 
<error></error>
 
<error_message></error_message>
 
</data>
 
</pre>
 
 
 
 
 
==Charge again transaction request (Tokenization)==
 
 
 
===Request specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | target
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal payment
 
|-
 
| colspan="1" | action
 
| colspan="1" | Y
 
| colspan="1" | string, 128
 
| colspan="1" | Must equal recharge
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | Y
 
| colspan="1" | string, 32
 
| colspan="1" | Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway
 
|-
 
| colspan="1" | amount
 
| colspan="1" | Y
 
| colspan="1" | currency
 
| colspan="1" | The amount for which the "saved" card is to be charged using the token from the previous successful transaction
 
|-
 
| colspan="1" | description
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Description of the transaction
 
|-
 
| colspan="1" | api_version
 
| colspan="1" | Y
 
| colspan="1" | string
 
| colspan="1" | Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
 
|-
 
| colspan="1" | refId (supported by API 1.4 and later)
 
| colspan="1" | N
 
| colspan="1" | string, 128
 
| colspan="1" | Order ID in the online store
 
|}
 
 
 
===Request example===
 
 
 
<pre>
 
<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>
 
</pre>
 
 
 
===Response specification===
 
 
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | integer, 1
 
| colspan="1" | [[#Operation status codes|Operation status code]]
 
|-
 
| colspan="1" | data
 
| colspan="1" | array
 
| colspan="1" |
 
|-
 
| colspan="1" | data[status]
 
| colspan="1" | integer
 
| colspan="1" | Status of the new payment (See [[#Payment status codes|Payment status codes]])
 
|-
 
| colspan="1" | data[transaction_id]
 
| colspan="1" | string
 
| colspan="1" | ID of the created payment for further references (capture/void/refund etc)
 
|-
 
| colspan="1" | data[error]
 
| colspan="1" | string
 
| colspan="1" |
 
|-
 
| colspan="1" | data[error_message]
 
| colspan="1" | string
 
| colspan="1" |
 
|-
 
| colspan="1" | data[is_error_message]
 
| colspan="1" | string
 
| colspan="1" |
 
|}
 
<br /><br />
 
 
 
==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 it’s 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===
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Value'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | action
 
| colspan="1" | callback
 
| colspan="1" | fixed string
 
| colspan="1" | Identifies the callback request
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | (mixed)
 
| colspan="1" | string (MD5 hash)
 
| colspan="1" | A unique ID of the payment on the side of X-Payments
 
|-
 
| colspan="1" | updateData
 
| colspan="1" | (mixed)
 
| colspan="1" | string
 
| colspan="1" | 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 [[X-Payments:API#Response_specification_2|response for Payment information request]].
 
<br /><br />
 
 
 
==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===
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Value'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | action
 
| colspan="1" | check_cart
 
| colspan="1" | fixed string
 
| colspan="1" | Identifies the check-cart callback request
 
|-
 
| colspan="1" | txnId
 
| colspan="1" | (mixed)
 
| colspan="1" | string (MD5 hash)
 
| colspan="1" | A unique ID of the payment on the side of X-Payments
 
|-
 
| colspan="1" | refId
 
| colspan="1" | (mixed)
 
| colspan="1" | string
 
| colspan="1" | Order ID (or any other reference) in the online store
 
|}
 
<br />
 
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===
 
{| cellspacing="0" cellpadding="2" border="1"
 
| colspan="1" | '''Field'''
 
| colspan="1" | '''Required'''
 
| colspan="1" | '''Type'''
 
| colspan="1" | '''Description'''
 
|-
 
| colspan="1" | status
 
| colspan="1" | Y
 
| colspan="1" | fixed string
 
| colspan="1" | Should be “cart-changed” or "cart-not-changed"
 
|-
 
| colspan="1" | cart
 
| colspan="1" | Y
 
| colspan="1" | container
 
| colspan="1" | A container with cart/order description. See [[X-Payments:API#Request_specification|Payment initialisation request specification]] for details. This container must be included for "status = cart-changed" and is not necessary for "status = cart-not-changed"
 
|-
 
| colspan="1" | saveCard
 
| colspan="1" | N
 
| colspan="1" | string
 
| colspan="1" | Whether the customer has chosen to save their card for future use (“Y” if the customer would like to save the card)
 
|}
 
<br /><br />
 
 
 
==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'''<br />
 
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:  {}
 
}
 
-----------------------------------------------------------
 
 
 
<br /><br />
 
===Messages sent from X-Payments to the online store===
 
'''Iframe is loaded and ready'''<br />
 
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()
 
:::}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Payment form submitted with an error'''<br />
 
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: {}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Internal error'''<br />
 
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'
 
:::}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Session is expired'''<br />
 
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'
 
:::}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Payment form in Iframe is submitted''' (supported by API v1.4 and later)<br />
 
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: {}
 
}
 
 
 
-----------------------------------------------------------
 
<br /><br />
 
  
 
==Appendix A. Status codes.==
 
==Appendix A. Status codes.==
  
 +
<div id="PaymentStatusCodes"></div>
 
===Payment status codes===
 
===Payment status codes===
 
: 1 - New
 
: 1 - New
Line 1,875: Line 221:
 
: 6 - Partially refunded
 
: 6 - Partially refunded
  
 +
<div id="OperationStatusCodes"></div>
 
===Operation status codes===
 
===Operation status codes===
 
: 0 - transaction failed
 
: 0 - transaction failed
Line 1,881: Line 228:
  
  
 
+
<div id="SeeAlso"></div>
 
==See also==
 
==See also==
  
* [http://lu53.crtdev.local/%7Emixon/google-cache-w.php?q=/index.php?title=X-Cart:X-Payments_Connector X-Cart:X-Payments Connector]
+
* [https://www.x-payments.com/help/Main_Page#X-Payments_connection_manuals X-Payments connection manuals]
  
 
[[Category:X-Payments Developer Guide]]
 
[[Category:X-Payments Developer Guide]]

Latest revision as of 13:52, 3 January 2019

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.0.0 (June 2016)
API v1.7: X-Payments 3.0.2 (August 2016)
API v1.8: X-Payments 3.1.0 (July 2017)
API v1.9: X-Payments 3.1.2 (April 2018)

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.

Use the latest TLSv1.2, since the previous protocols and implementations contain security vulnerabilities, and thus must not be used according to PCI DSS.

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.

API Requests from the store to X-Payments

Admin area/X-Payments configuration

Payment creation (Regular payment and tokenization)

Payment information

Actions on payments (secondary actions)

Callback requests (web-hooks) from X-Payments to the store

Browser-related

Code samples

We have prepared some code samples written in PHP demonstrating communication with X-Payments, request encryption and response decryption. The recommended way to use this code is console PHP (i.e. via command line) on the *nix OS.

To use the code samples:

  1. Download the archive with code samples.
  2. Upload it on the server.
  3. Extract the files and execute the script as follows:
[user@host]$ ls -la
total 72
drwxrwxr-x  2 user user  4096 Nov 18 14:26 .
drwxrwxr-x 17 user user  4096 Sep  5 07:24 ..
-rw-r--r--  1 user user 11141 Nov 18 14:24 API.php
-rw-r--r--  1 user user   656 Nov 16 01:54 connect_test.php
-rw-r--r--  1 user user   500 Nov 16 01:55 payment_accept.php
-rw-r--r--  1 user user   503 Nov 16 01:54 payment_capture.php
-rw-r--r--  1 user user   576 Nov 16 01:54 payment_confs_get.php
-rw-r--r--  1 user user   502 Nov 16 01:54 payment_decline.php
-rw-r--r--  1 user user   528 Nov 16 01:54 payment_get_additional_info.php
-rw-r--r--  1 user user   493 Nov 16 01:56 payment_get_info.php
-rw-r--r--  1 user user  1958 Nov 18 14:26 payment_init.php
-rw-r--r--  1 user user   707 Nov 16 01:54 payment_recharge.php
-rw-r--r--  1 user user  2073 Nov 16 01:54 payment_recharge.with.cart.php
-rw-r--r--  1 user user   498 Nov 16 01:54 payment_refund.php
-rw-r--r--  1 user user   496 Nov 16 01:54 payment_void.php
-rw-r--r--  1 user user   819 Nov 16 01:54 redirect.html
[user@host]$ php connect_test.php
<data>
  <hashCode>202cb962ac59075b964b07152d234b70</hashCode>
  <error></error>
  <error_message></error_message>
  <is_error_message></is_error_message>
  <version>3.0.2</version>
</data>

Notes on using the code samples:

  • The code is provided as is, and is supposed to be used for demonstration only. We will not be held responsible for any damage caused by using this code on production deployments/live installations. Please use it at your own risk.
  • To simplify the code, some sensitive information (like the private key and the private key passphrase) was hard-coded in the script. This way, storing the keys "as is" is strongly not recommended. Instead, the keys should be stored encrypted in some way.
  • For the salt generation, the openssl_random_pseudo_bytes() function is used. However, it has known issues; make sure it generates a cryptographically secure sequence. Please check: https://bugs.php.net/bug.php?id=70014. If necessary, you may use another way to generate a cryptographically secure random string. See: http://stackoverflow.com/questions/31492921/cryptographically-secure-random-string-function.
  • The keys hard-coded in the sample are taken from the X-Payments installation at https://demo.xpayments.com. So some operations work out of the box, e.g. payment initialization, payment information, test request, obtaining payment configurations, etc. But some operations will give an error, since the actual payment information on the demo stand can be changed. This applies to secondary operations: capture, void, refund, etc. To see the successful result, you should change the txnId fields hard-coded in the scripts.


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