X-Payments:API

API versions supported

API v1.1: X-Payments 1.0.2-1.0.5
API v1.2: X-Payments 1.0.6, 2.0.0, 2.0.1
API v1.3: X-Payments 2.1.0, 2.1.1
API v1.4: X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015)
API v1.5: X-Payments 2.2 (June 2015)
API v1.6: X-Payments 3.x (June 2016)

Samples

While we are doing an addition to our API docs I suggest to use function xpc_api_request from X-Cart 4 file modules/XPayments_Connector/xpc_func.php as a sample.

Especially function xpc_request_test() to make a test call.

API requests

All API requests are made to the https ://<xpayments_url>/api.php URL. Only HTTPS protocol is used. A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.

Request/Response encryption

• Encryption method used: RSA;
• Key length: 2048 bit;
• A private key is created with a 32 character password;
• The password is generated randomly;
• The number of password characters varies from 33 to 127.

For each online store X-Payments generates 2 pairs of keys:

1. a public and a private key to encrypt requests/responses from the online store to X-Payments;
2. a public and a private key to encrypt requests/responses from X-Payments to the online store.

So when the online store sends a request to X-Payments, this request is encrypted using the public key from the first pair, X-Payments decrypts it using the private key of the first pair. Then X-Payments response is encrypted using the public key of the second pair, and the online store decrypts this response using the private key of the second pair.

To ensure full-featured two-way communication between X-Payments and an online store, you need to copy tree values from the X-Payments interface:

• Public key from the first pair (Online store -> X-Payments),
• Private key from the second pair (X-Payments -> Online store),
• Private key password,

and have them stored on the side of the online store by an appropriate X-Payments connector.

Encryption and communication

I. Encryption
Data is passed as an XML string.

1. Get the Salt block.
   • Generate a 32-character string formed of random characters from 33 to 255.
2. Get the CRC block.
   • Generate MD5 in the binary format of the passed data.
   • Prepend it with the "     MD5" prefix (the five preceding spaces are mandatory!)
3. Get the Data block.
   • For each Salt, CRC and Data calculate the length: it is formatted as a 12-digit number, e.g. 000000000032.
   • Compose the data block. Write consecutively: length of Salt, Salt, length of CRC, CRC, length of Data, Data.
4. Split the data into chunks of 128 characters.
5. Encrypt each chunk consecutively using the public key.
6. Encode each chunk with base64.
7. Compose the encrypted data.
   • Start with the "API" prefix.
   • Write the encrypted and encoded chunks separated with line-breaks.

II. Send the request

POST the encrypted data to https ://<xpayments_url>/api.php in the following format:

 cart_id=CART_D&request=REQUEST

Where:

- CART_ID is the Store ID 
- REQUEST is the encrypted XML

III. Decrypt the response
The response is a string starting with "API".

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

IV. CRC Validation.
A response is received in a single line. It contains the following data, consecutively: length of Salt, Salt, length of CRC, CRC, length of Data, Data.

1. Extract Salt
   • Get the salt length from the first 12 characters.
   • Shift the salt block by its length.
2. Extract CRC:
   • Get the CRC length from the first 12 characters.
   • Shift the CRC block by its length.
   • Remove the "     MD5" prefix from CRC.
3. Extract data
   • Get the data length from the first 12 characters
   • Shift the data block by its length
4. Calculate the MD5 checksum in the binary format of the received data.
5. Compare it with CRC.

cURL as a means of sending requests

Using libcurl v.7.10 and above is recommended.

TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.

It is recommended to use SSL v.3 and above.

Data types

Data types used:

• string - a UTF-8 string;
• email - an email address no longer than 255 characters;
• URL - a URL address no longer than 255 characters;
• currency - a floating point number denoting a certain sum of money. The mantissa size is the same as the payment currency mantissa size, but not longer than 3. All the exceeding characters will be truncated.
• integer - an integer number.

ISO 4217 Alpha-3 in the upper register is always used as the payment currency code.

ISO 639-1 Alpha-2 in the lower register is always used as the language code.

Payment configurations list request

Payment configurations list request

Test connection request

Test connection request

Payment initialisation request

Payment initialisation request

Redirecting a customer to the cardholder data entering page

Redirecting a customer to the cardholder data entering page

Payment information request

Payment information request

Detailed payment and transaction information request

Detailed payment and transaction information request

Capture authorized transaction request

Capture authorized transaction request

Void authorized transaction request

Void authorized transaction request

Refund captured transaction request

Refund captured transaction request

Blocked by gateway transaction accept request (Accept)

Request specification

Field	Required	Type	Description
target	Y	string, 128	Must equal payment
action	Y	string, 128	Must equal accept
txnId	Y	string, 32	Unique payment ID
api_version	Y	string	Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>accept</action>

Response example

Field	Type	Description
status	integer, 1	Operation status code
message	string, 65536	Gateway transaction message

Response example

<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>

Blocked by gateway transaction decline request (Decline)

Request specification

Field	Required	Type	Description
target	Y	string, 128	Must equal payment
action	Y	string, 128	Must equal decline
txnId	Y	string, 32	Unique payment ID
api_version	Y	string	Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<target>payment</target>
<action>decline</action>

Response specification

Field	Type	Description
status	integer, 1	Operation status code
message	string, 65536	Gateway transaction message

Response example

<data>
<status>1</status>
<message>Success</message>
<error></error>
<error_message></error_message>
</data>

Charge again transaction request (Tokenization)

Request specification

Field	Required	Type	Description
target	Y	string, 128	Must equal payment
action	Y	string, 128	Must equal recharge
txnId	Y	string, 32	Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway
amount	Y	currency	The amount for which the "saved" card is to be charged using the token from the previous successful transaction
description	Y	string	Description of the transaction
api_version	Y	string	Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
refId (supported by API 1.4 and later)	N	string, 128	Order ID in the online store

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<description>Recurring payment for the new issue of Playboy</description>
<target>payment</target>
<action>recharge</action>
<api_version>1.2</api_version>

Response specification

Field	Type	Description
status	integer, 1	Operation status code
data	array
data[status]	integer	Status of the new payment (See Payment status codes)
data[transaction_id]	string	ID of the created payment for further references (capture/void/refund etc)
data[error]	string
data[error_message]	string
data[is_error_message]	string

Callback request with service payment information

This is a background request that X-Payments sends to the store after a payment has been completed and its result (accepted, declined, etc) has been received from the payment gateway. The request is sent via HTTP POST to the callbackURL defined in the Payment initialisation request. Once this request has been sent, the customer is redirected back to the store.

POSTed data

Field	Value	Type	Description
action	callback	fixed string	Identifies the callback request
txnId	(mixed)	string (MD5 hash)	A unique ID of the payment on the side of X-Payments
updateData	(mixed)	string	Encrypted response from X-Payments

X-Payments does not expect a response from the store for this request; however, if the HTTP status of the response is not 200 OK, the request is considered failed, and a special notification is sent to the X-Payments admin. The store needs to decrypt the encrypted part of the response and update the order on its side accordingly. Once the updateData value has been decrypted, it is an XML document with the same structure as the response for Payment information request.

Check cart callback request

After the customer has submitted credit card data, right before sending this data to the payment gateway, X-Payments connects to the store to verify the cart total and contents.

The HTTP POST request is sent to the callbackURL defined in the Payment initialisation request.

POSTed data

Field	Value	Type	Description
action	check_cart	fixed string	Identifies the check-cart callback request
txnId	(mixed)	string (MD5 hash)	A unique ID of the payment on the side of X-Payments
refId	(mixed)	string	Order ID (or any other reference) in the online store

As of API v1.3, the store must respond to this callback request. The response must be an encrypted XML document (i.e. the same way as for other communication between the store and X-Payments).

Encrypted response for check-cart callback request

Field	Required	Type	Description
status	Y	fixed string	Should be "cart-changed" or "cart-not-changed"
cart	Y	container	A container with cart/order description. See Payment initialisation request specification for details. This container must be included for "status = cart-changed" and is not necessary for "status = cart-not-changed"
saveCard	N	string	Whether the customer has chosen to save their card for future use ("Y" if the customer would like to save the card)

Communication between X-Payments iframe and the store

Communication structure

Communication between the online store (parent frame) and X-Payments (iframe) is implemented with the help of the javascript Window.postMessage method. Notifictions to both the sides represent stringified JSON formatted texts that consist of a service message (string) and an optional list of parameters:

• height: height of the iframe
• error: human readable message
• type: message type. X-Payments sends it as 2, which indicates that the online store should re-initialize the payment. In API v1.3 no other values are supported.

Messages sent from the online store to X-Payments

Submit payment form
X-Payments' iframe does not have a Submit button, so instead of it the payment form should be submitted from the parent window by any kind of "Submit order" or "Place order" button at checkout. At the same time, the special message submitPaymentForm with no parameters should be sent.

---

{

message: 'submitPaymentForm',

params: {}

}

---

Messages sent from X-Payments to the online store

Iframe is loaded and ready
The message ready notifies the parent window that the payment form is ready. The actual height of the iframe is included in the parameters, so the parent window (checkout page) can perform the necessary adjustments.

---

{

message: 'ready',

params: {

height: $(document).height()

}

}

---

Payment form submitted with an error
The message paymentFormSubmitError with no parameters is sent in the case of any validation error. This may be the case, for example, if the customer's credit card expiration date is in the past, or the credit card number does not match the card type (e.g. VISA, MasterCard), or when a required field has not been submitted (e.g. CVV2). Once the message paymentFormSubmitError with no parameters has been received, the store should not proceed to the next step of the checkout process, but should expect the payment form to be submitted again.

---

{

message: 'paymentFormSubmitError',

params: {}

}

---

Internal error
The paymentFormSubmitError message with a special set of parameters is used to notify the store if something is wrong outside X-Payments, and X-Payments cannot do anything about it (for example, if the payment gateway has sent an unknown/unexpected piece of data).

---

{

message: 'paymentFormSubmitError',

params: {

height: $(document).height(),

error: 'Internal error',

type: '2'

}

}

---

Session is expired
For security reasons the length of the session is limited to 15 minutes. After this period the store has to re-initialize the payment. In this case X-Payments sends the paymentFormSubmitError message with the "Payment session expired" error.

---

{

message: 'paymentFormSubmitError',

params: {

height: $(document).height(),

error: 'Payment session expired',

type: '2'

}

}

---

Payment form in Iframe is submitted (supported by API v1.4 and later)
The message paymentFormSubmit notifies the parent window that the payment form has been submitted from the X-Payments side; for example, if a customer clicks the Enter key inside the iframe. Once the store receives this message, it should operate in the same way as though the customer has clicked the Place order button at checkout.

---

{

message: 'paymentFormSubmit',

params: {}

}

---

Appendix A. Status codes.

Payment status codes

1 - New

2 - Authorized

3 - Declined

4 - Charged

5 - Refunded

6 - Partially refunded

Operation status codes

0 - transaction failed

1 - transaction is successful

2 - transaction is successful and is duplicate

See also

• X-Cart:X-Payments Connector