X-Payments:API
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.0.0 (June 2016)
API v1.7: X-Payments 3.0.2 (August 2016)
Samples
While we are doing an addition to our API docs I suggest to use function xpc_api_request from X-Cart 4 file modules/XPayments_Connector/xpc_func.php as a sample.
Especially function xpc_request_test() to make a test call.
API requests
All API requests are made to the https ://<xpayments_url>/api.php URL. Only HTTPS protocol is used. A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.
Request/Response encryption
- Encryption method used: RSA;
- Key length: 2048 bit;
- A private key is created with a 32 character password;
- The password is generated randomly;
- The number of password characters varies from 33 to 127.
For each online store X-Payments generates 2 pairs of keys:
- a public and a private key to encrypt requests/responses from the online store to X-Payments;
- a public and a private key to encrypt requests/responses from X-Payments to the online store.
So when the online store sends a request to X-Payments, this request is encrypted using the public key from the first pair, X-Payments decrypts it using the private key of the first pair. Then X-Payments response is encrypted using the public key of the second pair, and the online store decrypts this response using the private key of the second pair.
To ensure full-featured two-way communication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:
- Public key from the first pair (Online store -> X-Payments),
- Private key from the second pair (X-Payments -> Online store),
- Private key password,
and have them stored on the side of the online store by an appropriate X-Payments connector.
Encryption and communication
I. Encryption
Data is passed as an XML string.
- Get the Salt block.
- Generate a 32-character string formed of random characters from 33 to 255.
- Get the CRC block.
- Generate MD5 in the binary format of the passed data.
- Prepend it with the " MD5" prefix (the 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
POST the encrypted data to https ://<xpayments_url>/api.php in the following format:
cart_id=CART_D&request=REQUEST
Where:
- CART_ID is the Store ID - REQUEST is the encrypted XML
III. Decrypt the response
The response is a string starting with "API".
- Remove the leading "API" word. If the response does not start with "API", it means that it is incorrect.
- Split and decode the encrypted chunks.
- Chunks are separated by line-breaks.
- Each chunk is 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.
IV. CRC Validation.
A response is received in a single line. It contains the following data, consecutively:
length of Salt, Salt, length of CRC, CRC, length of Data, Data.
- Extract Salt
- Get the salt length from the first 12 characters.
- Shift the salt block by its length.
- Extract CRC:
- Get the CRC length from the first 12 characters.
- Shift the CRC block by its length.
- Remove the " MD5" prefix from CRC.
- Extract data
- Get the data length from the first 12 characters
- Shift the data block by its length
- Calculate the MD5 checksum in the binary format of the received data.
- Compare it with CRC.
cURL as a means of sending requests
Using libcurl v.7.10 and above is recommended.
TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.
It is recommended to use SSL v.3 and above.
Data types
Data types used:
- string - a UTF-8 string;
- email - an email address no longer than 255 characters;
- URL - a URL address no longer than 255 characters;
- currency - a floating point number denoting a certain sum of money. The mantissa size is the same as the payment currency mantissa size, but not longer than 3. All the exceeding characters will be truncated.
- integer - an integer number.
ISO 4217 Alpha-3 in the upper register is always used as the payment currency code.
ISO 639-1 Alpha-2 in the lower register is always used as the language code.
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)
- Capture authorized transaction request
- Void authorized transaction request
- Refund captured transaction request
- Blocked by gateway transaction accept request (Accept)
- Blocked by gateway transaction decline request (Decline)
Callback requests (web-hooks) from X-Payments to the store
- Redirecting a customer to the cardholder data entering page
- Communication between X-Payments iframe and the store
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