X-Payments:API

From Qualiteam Help

API requests

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

Request/Response encryption

• Used encryption method: RSA;
• Key length: 2048 bit;
• A public 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. public and private to encrypt requests/responses from the online store to X-Payments
2. public and private 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.

X-Payments interface shows and X-Payments connector module store the public key from the first pair, and the private key from the second pair.

Encryption algorithm:

1. an empty string is created for pre-prepared data
2. a 32-character salt-block is formed of random characters from 33 to 255
3. the length of the salt-block in bites is taken and transformed into a 12-character string by adding zeros before it
4. the salt-block length string and the salt-block are added to the pre-prepared data
5. MD5 digital signature is taken from the data. The signature is formed as a HEX (32-character string)
6. the length of the digital signature in bites is taken and transformed into a 12-character string by adding zeros before it
7. the digital signature length string and the digital signature are added to the pre-prepared data
8. the length of the data string in bites is taken and transformed into a 12-character string by adding zeros before it
9. the data string length string and the data string are added to the pre-prepared data
10. the string of pre-prepared data is divided into 128 bite chunks
11. each chunk is encrypted using a public key
12. each chunk is encoded with base64
13. chunks are glued together using a line feed character (0x0a)
14. API prefix is added to the glued chunks

cURL as a means of sending requests

Using libcurl v.7.10 and above is recommended.

TTL should be specified depending on the productivity of the server, where X-Payments is installed.

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

Data types

Used data types:

• string - a UTF-8 string
• email - an email address not longer than 255 characters
• URL - a URL address not 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 initialisation request

Request specification

Request example

<confId>8</confId>
<refId>1120</refId>
<cart>
<login>customer</login>
<billingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</billingAddress>
<shippingAddress>
<firstname>John</firstname>
<lastname>Smith</lastname>
<address>10 Main street</address>
<city>Fillmore</city>
<state>UT</state>
<country>US</country>
<zipcode>84631</zipcode>
<company>IQ testing</company>
<email>bit-bucket@x-cart.com</email>
<phone>927348572</phone>
<fax></fax>
</shippingAddress>
<items type="cell">
<sku>SKU17513</sku>
<name>Three Stone Princess Cut Diamond Ring</name>
<price>399.99</price>
<quantity>1</quantity>
</items>
<currency>USD</currency>
<shippingCost>15</shippingCost>
<taxCost>0</taxCost>
<discount>0</discount>
<totalCost>414.99</totalCost>
<description>Order(s) #1120</description>
<merchantEmail>bit-bucket@x-cart.com</merchantEmail>
<forceTransactionType></forceTransactionType>
</cart>
<returnUrl>https://example.com/xcart/payment/cc_xpc.php</returnUrl>
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>
<language>ru</language>
<target>payment</target>
<action>init</action>

Response specification

Response example

<data>
<token>41b2ef3b34698d4f6ed73151ae7307d2</token>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<error></error>
<error_message></error_message>
</data>

Redirecting a customer to the cardholder data entering page

A POST form is created, which sends data to the URL <XPayments_web_root>/payment.php containing the following fields:

• target - has value main
• action - has value start
• token - has value from the payment initialisation request (token field)

Request protocol - HTTPS The form must be sent by the POST method. All data must also be sent as POST variables.

Payment information request

Request specification

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<refresh>0</target>
<target>payment</target>
<action>get_info</action>

Response specification

Response example

<data>
<status>2</status>
<message>Payment is authorized</message>
<isFraudStatus></isFraudStatus>
<currency>USD</currency>
<amount>414.99</amount>
<authorized>414.99</authorized>
<chargedAmount>0.00</chargedAmount>
<capturedAmount>0.00</capturedAmount>
<capturedAmountAvail>414.99</capturedAmountAvail>
<voidedAmount>0.00</voidedAmount>
<voidedAmountAvail>414.99</voidedAmountAvail>
<refundedAmount>0.00</refundedAmount>
<refundedAmountAvail>0.00</refundedAmountAvail>
<fraudAuthorized>0.00</fraudAuthorized>
<fraudCharged>0.00</fraudCharged>
<authorizeInProgress>0.00</authorizeInProgress>
<chargeInProgress>0.00</chargeInProgress>
<transactionInProgress></transactionInProgress>
<capturedAmountAvailMin>0.00</capturedAmountAvailMin>
<capturedAmountAvailGateway>414.99</capturedAmountAvailGateway>
<capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
<voidedAmountAvailGateway>414.99</voidedAmountAvailGateway>
<refundedAmountAvailGateway>0.00</refundedAmountAvailGateway>
<txnId>8e67e0da23ce7ed451b2c1adbbd7373c</txnId>
<lastMessage>Success</lastMessage>
<error></error>
<error_message></error_message>
</data>

Detailed payment and transaction information request

Request specification

Request example

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

Response specification

Response example

<data>
<payment>
<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>
</payment>
<transactions type="cell">
<date>1264597135</date>
<action>Authorize</action>
<status>Success</status>
<message>Success</message>
<total>414.99 USD</total>
<txnid>48405381W4268581P</txnid>
<fields type="cell">
<name>AVS</name>
<value>Exact match. Address and five-digit ZIP code</value>
</fields>
<fields type="cell">
<name>CVV</name>
<value>Match</value>
</fields>
<payment_status>Charged</payment_status>
</transactions>
<error></error>
<error_message></error_message>
</data>

Capture authorized transaction request

Request specification

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>capture</action>

Response example

Note:

• Values of "status" field:

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

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

Void authorized transaction request

Request specification

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>void</action>

Response specification

Note:

• Values of "status" field:

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

Response example

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

Refund captured transaction request

Request specification

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>refund</action>

Response specification

Note:

• Values of "status" field:

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

Response example

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

Blocked by gateway transaction accept request (Accept)

Request specification

Request example

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

Response example

Note:

• Values of "status" field:

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

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

Blocked by gateway transaction decline request (Decline)

Request specification

Request example

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

Response specification

Note:

• Values of "status" field:

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

Response example

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

See also

• X-Cart:X-Payments Connector