X-Payments:API

From X-Payments Help
Revision as of 13:20, 14 July 2015 by Dohtur (talk | contribs) (Created page with "== API versions supported == '''API v1.1''': X-Payments 1.0.2-1.0.5 <br /> '''API v1.2''': X-Payments 1.0.6, 2.0.0, 2.0.1 <br /> '''API v1.3''': X-Payments 2.1.0, 2.1.1 <br /...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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 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 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 commumication 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 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 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 initialisation request

Request specification

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal init
confId Y integer Payment module configuration ID
refId Y string, 128 Order ID in the online store
returnUrl Y URL, 255 URL of the page to redirect the customer after payment
callbackUrl Y URL, 255 URL to which X-Payments sends background requests with service information
language N code of ISO 639-1 (Alpha-2) Language code. If not specified - en
cart Y container A container with addresses description
cart/billingAddress Y container A container with the billing address description
cart/billingAddress/firstname Y string, 255
cart/billingAddress/lastname N string, 255
cart/billingAddress/company N string, 255
cart/billingAddress/address Y string, 255
cart/billingAddress/city Y string, 255
cart/billingAddress/state Y string, 255
cart/billingAddress/country Y string, 255
cart/billingAddress/zipcode Y string, 32
cart/billingAddress/email Y emai, 255l
cart/billingAddress/phone Y string, 255
cart/billingAddress/fax N string, 255
cart/shippingAddress Y container A container with the shipping address description
cart/shippingAddress/firstname Y string, 255
cart/shippingAddress/lastname N string, 255
cart/shippingAddress/company N string, 255
cart/shippingAddress/address Y string, 255
cart/shippingAddress/city Y string, 255
cart/shippingAddress/state Y string, 255
cart/shippingAddress/country Y string, 255
cart/shippingAddress/zipcode Y string, 32
cart/shippingAddress/email Y email, 255
cart/shippingAddress/phone Y string, 255
cart/shippingAddress/fax N string, 255
cart/items Y container A container with product description
cart/items/sku Y string, 64 SKU (product code)
cart/items/name Y string, 255 Product name
cart/items/price Y currency Product item price
cart/items/quantity N integer Ordered number of products. If not specified - 1
cart/login Y string, 255 Unique customer ID in the online store (login, username, userid, etc.)
cart/currency N string, 3 Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used
cart/shippingCost - currency Shipping cost. By default - 0
cart/taxCost - currency Tax amount. By default - 0
cart/discount - currency Discount amount. By default - 0
cart/totalCost Y currency Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount
cart/description - string, 65536
cart/merchantEmail Y email, 255
cart/forceTransactionType - one of values: A or S or empty
A - authorize
S - sale
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.
api_version Y string 1.2 for API 1.2, 1.3 for API 1.3
template
(supported by API 1.3 and later)
N string 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.
saveCard
(supported by API 1.3 and later)
N string Customer's choice at checkout (“Y” if customer would like to save the card)


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

<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

Field Type Description
token string,32 Temporary payment token, expires immediately after the customer has submitted the cardholder data form
txnId string,32 A unique payment ID. Is used for all further requests to this payment through the API.

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 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
The form must be sent by the POST method. All data must also be sent as POST variables.

Payment information request

Request specification

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal get_info
txnId Y string, 32 Unique payment ID
refresh N 0 или 1 A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0
api_version Y string Should be 1.2

Request example

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

Response specification

Field Type Description
status integer, 1 Payment status code
message string, 65536 Human readable message containing the payment status
isFraudStatus 0 or 1 Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check
currency string, 3 Payment currency code
amount currency Payment total
authorized currency Authorized payment total
chargedAmount currency Charged payment total
capturedAmount currency Captured amount of the authorized amount
capturedAmountAvail currency Amount that is authorized and can be captured
voidedAmount currency Amount that is authorized but voided
voidedAmountAvail currency Amount that is authorized and can be voided
refundedAmount currency Amount that can be refunded
refundedAmountAvail currency Amount that can be refunded
fraudAuthorized currency A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check
fraudCharged currency A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check
authorizeInProgress currency A part of the authorized amount that is being handled by the gateway
chargeInProgress currency A part of the charged amount that is being handled by the gateway
transactionInProgress 0 или 1 Are there any payment transactions handled by the gateway?
capturedAmountAvailMin currency Minimum amount that can be captured from the authorized amount
capturedAmountAvailGateway currency Amount that can be captured from the authorized amount through the gateway
capturedAmountAvailMinGateway currency Minimum amount that can be captured from the authorized amount through the gateway
voidedAmountAvailGateway currency Amount that can be voided from the authorized amount through the gateway
refundedAmountAvailGateway currency Amount that can be refunded from the authorized amount through the gateway
txnId string, 32 Unique payment ID
lastMessage string, 65536 Last gateway message
error string, 128 Error code
error_message string, 65536 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

<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

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal get_additional_info
txnId Y string, 32 A unique payment ID received in the payment initialisation request response
api_version Y string Should be 1.2

Request example

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

Response specification

Field Type Description
payment container Payment information request response
transactions container Transaction list
transactions/date integer, 11 Transaction date (Unix timestamp)
transactions/action string, 255 Transaction name
transactions/status string, 255 Transaction status
transactions/message string, 65536 Gateway transaction message
transactions/total string, 32 Transaction amount and currency
transactions/txnid string, 255 Gateway transaction unique ID
transactions/payment_status string, 255 The payment status after the transaction
transactions/fields container Transaction additional fields list
transactions/fields/name string, 255 Field name
transactions/fields/name string, 255 Field value

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

Field Required Type Description
target Y string,128 Must equal payment
action Y string, 128 Must equal capture
txnId Y string, 32 Unique payment ID
amount N currency The amount to capture from the previously authorized transaction. By default equals the amount of the authorized transaction
api_version Y string Should be 1.2


Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>capture</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>

Void authorized transaction request

Request specification

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal void
txnId Y string, 32 Unique payment ID
amount N currency Amount to void of the authorized transaction. By default equals to the amount of the authorized transaction
api_version Y string Should be 1.2

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>void</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>

Refund captured transaction request

Request specification

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal capture
txnId Y string, 32 Unique payment ID
amount N currency Amount to be refunded to the customer of the previously captured transactions. By default equals to the amount of captured transactions
api_version Y string Should be 1.2

Request example

<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
<amount>50.00</amount>
<target>payment</target>
<action>refund</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>

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 Should be 1.2

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 Should be 1.2

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 Should be 1.2

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 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

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”
cart Y container A container with cart/order description. See Payment initialisation request specification for details.
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