X-Payments:API

Contents
1 API versions supported
2 Samples
3 API requests
3.1 Request/Response encryption
3.2 Encryption and communication
3.3 cURL as a means of sending requests
3.4 Data types
4 API Requests from the store to X-Payments
4.1 Admin area/X-Payments configuration
4.2 Payment creation (Regular payment and tokenization)
4.3 Payment information
4.4 Actions on payments (secondary actions)
5 Callback requests (web-hooks) from X-Payments to the store
6 Browser-related
7 Appendix A. Status codes.
7.1 Payment status codes
7.2 Operation status codes
8 See also
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)
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.
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.
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.
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.
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 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.

Test connection request

Payment configurations list request
Payment initialisation request
Charge again transaction request (Tokenization)
Payment information request
Detailed payment and transaction information request
Capture authorized transaction request
Void authorized transaction request
Refund captured transaction request
Accept potentially fraudulent transaction request
Decline potentially fraudulent transaction request
Callback request with service payment information
Check cart callback request
Redirecting a customer to the cardholder data entering page
Communication between X-Payments iframe and the store

1 - New
2 - Authorized
3 - Declined
4 - Charged
5 - Refunded
6 - Partially refunded

0 - transaction failed
1 - transaction is successful
2 - transaction is successful and is duplicate

X-Cart:X-Payments Connector