Difference between revisions of "X-Payments:API"

From X-Payments Help
Jump to: navigation, search
m (Check cart callback request)
m (See also)
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
<div id="APIversions"></div>
 
== API versions supported ==
 
== API versions supported ==
  
Line 6: Line 7:
 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015)<br />
 
'''API v1.4''': X-Payments 2.1.2 (Nov 2014), 2.1.3 (Feb 2015)<br />
 
'''API v1.5''': X-Payments 2.2 (June 2015)<br />
 
'''API v1.5''': X-Payments 2.2 (June 2015)<br />
'''API v1.6''': X-Payments 3.x (June 2016)
+
'''API v1.6''': X-Payments 3.0.0 (June 2016)<br />
 +
'''API v1.7''': X-Payments 3.0.2 (August 2016)<br />
 +
'''API v1.8''': X-Payments 3.1.0 (July 2017)<br />
 +
'''API v1.9''': X-Payments 3.1.2 (April 2018)<br />
  
==Samples==
+
<div id="APIrequests"></div>
 
 
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==
 
==API requests==
Line 21: Line 20:
 
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.
 
A request is an XML document that is encrypted using RSA method with a key generated by X-Payments.
  
 +
<div id="RequestResponseEncryption"></div>
 
===Request/Response encryption===
 
===Request/Response encryption===
  
Line 42: Line 42:
 
and have them stored on the side of the online store by an appropriate X-Payments connector.
 
and have them stored on the side of the online store by an appropriate X-Payments connector.
  
 +
<div id="EncryptionAndCommunication"></div>
 
===Encryption and communication===
 
===Encryption and communication===
  
Line 66: Line 67:
 
POST the encrypted data to https ://<xpayments_url>/api.php in the following format:
 
POST the encrypted data to https ://<xpayments_url>/api.php in the following format:
  
   cart_id=CART_D&request=REQUEST
+
   cart_id=<CART_D>&request=<REQUEST>
  
Where:
+
where:
  - CART_ID is the Store ID  
+
  - <CART_ID> is the Store ID;
  - REQUEST is the encrypted XML
+
  - <REQUEST> is the encrypted XML
  
  
Line 102: Line 103:
 
# Compare it with CRC.
 
# Compare it with CRC.
  
 
+
<div id="cURLAsAMeansOfSendingRequests"></div>
 
===cURL as a means of sending requests===
 
===cURL as a means of sending requests===
  
Line 109: Line 110:
 
TTL should be specified depending on the performance of the server where X-Payments is installed. The recommended value is 120 seconds.
 
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.
+
Use the latest TLSv1.2, since the previous protocols and implementations contain security vulnerabilities, and thus must not be used according to PCI DSS.
  
 +
<div id="DataTypes"></div>
 
===Data types===
 
===Data types===
  
Line 125: Line 127:
 
ISO 639-1 Alpha-2 in the lower register is always used as the language code.
 
ISO 639-1 Alpha-2 in the lower register is always used as the language code.
  
==Payment configurations list request==
+
<div id="APIRequestsFromStoreToXP"></div>
[[X-Payments:Payment_configurations_list_request|Payment configurations list request]]
+
==API Requests from the store to X-Payments==
 
 
==Test connection request==
 
[[X-Payments:Test_connection_request|Test connection request]]
 
 
 
==Payment initialisation request==
 
 
 
[[X-Payments:Payment_initialisation_request|Payment initialisation request]]
 
 
 
==Redirecting a customer to the cardholder data entering page==
 
 
 
[[X-Payments:Redirecting_a_customer_to_the_cardholder_data_entering_page|Redirecting a customer to the cardholder data entering page]]
 
 
 
==Payment information request==
 
 
 
[[X-Payments:Payment_information_request|Payment information request]]
 
 
 
==Detailed payment and transaction information request==
 
 
 
[[X-Payments:Detailed_payment_and_transaction_information_request|Detailed payment and transaction information request]]
 
 
 
==Capture authorized transaction request==
 
 
 
[[X-Payments:Capture_authorized_transaction_request|Capture authorized transaction request]]
 
 
 
==Void authorized transaction request==
 
  
[[X-Payments:Void_authorized_transaction_request|Void authorized transaction request]]
+
<div id="AdminAreaXPConfiguration"></div>
 +
===Admin area/X-Payments configuration===
 +
* [[X-Payments:Test_connection_request|Test connection request]]
 +
* [[X-Payments:Payment_configurations_list_request|Payment configurations list request]]<br />
  
==Refund captured transaction request==
+
<div id="PaymentCreation"></div>
 +
===Payment creation (Regular payment and tokenization)===
 +
* [[X-Payments:Payment_initialisation_request|Payment initialisation request]]<br />
 +
* [[X-Payments:Charge_again_transaction_request_(Tokenization)|Charge again transaction request (Tokenization)]]
  
[[X-Payments:Refund_captured_transaction_request|Refund captured transaction request]]
+
<div id="PaymentInformation"></div>
 +
===Payment information===
 +
* [[X-Payments:Payment_information_request|Payment information request]]<br />
 +
* [[X-Payments:Detailed_payment_and_transaction_information_request|Detailed payment and transaction information request]]
  
==Blocked by gateway transaction accept request (Accept)==
+
<div id="ActionsOnPayments"></div>
 +
===Actions on payments (secondary actions)===
 +
* [[X-Payments:Capture_authorized_transaction_request|Capture authorized transaction request]]<br />
 +
* [[X-Payments:Void_authorized_transaction_request|Void authorized transaction request]]<br />
 +
* [[X-Payments:Refund_captured_transaction_request|Refund captured transaction request]]<br />
 +
* [[X-Payments:Accept_potentially_fraudulent_transaction_request|Accept potentially fraudulent transaction request]]<br />
 +
* [[X-Payments:Decline_potentially_fraudulent_transaction_request|Decline potentially fraudulent transaction request]]
  
[[X-Payments:Blocked_by_gateway_transaction_accept_request_(Accept)|Blocked by gateway transaction accept request (Accept)]]
+
<div id="CallbackRequests"></div>
  
==Blocked by gateway transaction decline request (Decline)==
+
==Callback requests (web-hooks) from X-Payments to the store==
 +
* [[X-Payments:Callback_request_with_service_payment_information|Callback request with service payment information]]<br />
 +
* [[X-Payments:Check_cart_callback_request|Check cart callback request]]
  
[[X-Payments:Blocked_by_gateway_transaction_decline_request_(Decline)|Blocked by gateway transaction decline request (Decline)]]
+
<div id="BrowserRelated"></div>
 +
==Browser-related==
 +
* [[X-Payments:Redirecting_a_customer_to_the_cardholder_data_entering_page|Redirecting a customer to the cardholder data entering page]]<br />
 +
* [[X-Payments:Communication_between_X-Payments_iframe_and_the_store|Communication between X-Payments iframe and the store]]
  
==Charge again transaction request (Tokenization)==
+
<div id="CodeSamples"></div>
 +
==Code samples==
 +
We have prepared some code samples written in PHP demonstrating communication with X-Payments, request encryption and response decryption. The recommended way to use this code is console PHP (i.e. via command line) on the *nix OS.
  
[[X-Payments:Charge_again_transaction_request_(Tokenization)|Charge again transaction request (Tokenization)]]
+
To use the code samples:
 +
# Download the [http://s.x-cart.com/xp_api_samples archive with code samples].
 +
# Upload it on the server.
 +
# Extract the files and execute the script as follows:
 +
<pre>
 +
[user@host]$ ls -la
 +
total 72
 +
drwxrwxr-x  2 user user  4096 Nov 18 14:26 .
 +
drwxrwxr-x 17 user user  4096 Sep  5 07:24 ..
 +
-rw-r--r--  1 user user 11141 Nov 18 14:24 API.php
 +
-rw-r--r-- 1 user user  656 Nov 16 01:54 connect_test.php
 +
-rw-r--r--  1 user user  500 Nov 16 01:55 payment_accept.php
 +
-rw-r--r--  1 user user  503 Nov 16 01:54 payment_capture.php
 +
-rw-r--r--  1 user user  576 Nov 16 01:54 payment_confs_get.php
 +
-rw-r--r--  1 user user  502 Nov 16 01:54 payment_decline.php
 +
-rw-r--r--  1 user user  528 Nov 16 01:54 payment_get_additional_info.php
 +
-rw-r--r--  1 user user  493 Nov 16 01:56 payment_get_info.php
 +
-rw-r--r--  1 user user  1958 Nov 18 14:26 payment_init.php
 +
-rw-r--r--  1 user user  707 Nov 16 01:54 payment_recharge.php
 +
-rw-r--r--  1 user user  2073 Nov 16 01:54 payment_recharge.with.cart.php
 +
-rw-r--r--  1 user user  498 Nov 16 01:54 payment_refund.php
 +
-rw-r--r--  1 user user  496 Nov 16 01:54 payment_void.php
 +
-rw-r--r--  1 user user  819 Nov 16 01:54 redirect.html
 +
[user@host]$ php connect_test.php
 +
<data>
 +
  <hashCode>202cb962ac59075b964b07152d234b70</hashCode>
 +
  <error></error>
 +
  <error_message></error_message>
 +
  <is_error_message></is_error_message>
 +
  <version>3.0.2</version>
 +
</data>
 +
</pre>
  
==Callback request with service payment information==
+
Notes on using the code samples:
 +
:* The code is provided as is, and is supposed to be used ''for demonstration only''. We will not be held responsible for any damage caused by using this code on production deployments/live installations. Please use it at your own risk.
 +
:* To simplify the code, some sensitive information (like the private key and the private key passphrase) was hard-coded in the script. This way, storing the keys "as is" is ''strongly not recommended''. Instead, the keys should be stored encrypted in some way.
 +
:* For the salt generation, the openssl_random_pseudo_bytes() function is used. However, it has known issues; make sure it generates a cryptographically secure sequence. Please check: https://bugs.php.net/bug.php?id=70014. If necessary, you may use another way to generate a cryptographically secure random string. See: http://stackoverflow.com/questions/31492921/cryptographically-secure-random-string-function.
 +
:* The keys hard-coded in the sample are taken from the X-Payments installation at https://demo.xpayments.com. So some operations work out of the box, e.g. [[X-Payments:Payment_initialisation_request | payment initialization]], [[X-Payments:Payment_information_request | payment information]], [[X-Payments:Test_connection_request | test request]], [[X-Payments:Payment_configurations_list_request | obtaining payment configurations]], etc. But some operations will give an error, since the actual payment information on the demo stand can be changed. This applies to secondary operations: [[X-Payments:Capture_authorized_transaction_request | capture]], [[X-Payments:Void_authorized_transaction_request | void]], [[X-Payments:Refund_captured_transaction_request | refund]], etc. To see the successful result, you should change the '''txnId''' fields hard-coded in the scripts.
  
[[X-Payments:Callback_request_with_service_payment_information|Callback request with service payment information]]
 
  
==Check cart callback request==
+
<div id="AppendixAStatusCodes"></div>
 
 
[[X-Payments:Check_cart_callback_request|Check cart callback request]]
 
 
 
==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'''<br />
 
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:  {}
 
}
 
-----------------------------------------------------------
 
 
 
<br /><br />
 
===Messages sent from X-Payments to the online store===
 
'''Iframe is loaded and ready'''<br />
 
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()
 
:::}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Payment form submitted with an error'''<br />
 
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: {}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Internal error'''<br />
 
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'
 
:::}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Session is expired'''<br />
 
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'
 
:::}
 
}
 
-----------------------------------------------------------
 
<br />
 
'''Payment form in Iframe is submitted''' (supported by API v1.4 and later)<br />
 
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: {}
 
}
 
 
 
-----------------------------------------------------------
 
<br /><br />
 
  
 
==Appendix A. Status codes.==
 
==Appendix A. Status codes.==
  
 +
<div id="PaymentStatusCodes"></div>
 
===Payment status codes===
 
===Payment status codes===
 
: 1 - New
 
: 1 - New
Line 266: Line 221:
 
: 6 - Partially refunded
 
: 6 - Partially refunded
  
 +
<div id="OperationStatusCodes"></div>
 
===Operation status codes===
 
===Operation status codes===
 
: 0 - transaction failed
 
: 0 - transaction failed
Line 272: Line 228:
  
  
 
+
<div id="SeeAlso"></div>
 
==See also==
 
==See also==
  
* [http://lu53.crtdev.local/%7Emixon/google-cache-w.php?q=/index.php?title=X-Cart:X-Payments_Connector X-Cart:X-Payments Connector]
+
* [https://www.x-payments.com/help/Main_Page#X-Payments_connection_manuals X-Payments connection manuals]
  
 
[[Category:X-Payments Developer Guide]]
 
[[Category:X-Payments Developer Guide]]

Latest revision as of 13:52, 3 January 2019

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)
API v1.8: X-Payments 3.1.0 (July 2017)
API v1.9: X-Payments 3.1.2 (April 2018)

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.

Use the latest TLSv1.2, since the previous protocols and implementations contain security vulnerabilities, and thus must not be used according to PCI DSS.

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)

Callback requests (web-hooks) from X-Payments to the store

Browser-related

Code samples

We have prepared some code samples written in PHP demonstrating communication with X-Payments, request encryption and response decryption. The recommended way to use this code is console PHP (i.e. via command line) on the *nix OS.

To use the code samples:

  1. Download the archive with code samples.
  2. Upload it on the server.
  3. Extract the files and execute the script as follows:
[user@host]$ ls -la
total 72
drwxrwxr-x  2 user user  4096 Nov 18 14:26 .
drwxrwxr-x 17 user user  4096 Sep  5 07:24 ..
-rw-r--r--  1 user user 11141 Nov 18 14:24 API.php
-rw-r--r--  1 user user   656 Nov 16 01:54 connect_test.php
-rw-r--r--  1 user user   500 Nov 16 01:55 payment_accept.php
-rw-r--r--  1 user user   503 Nov 16 01:54 payment_capture.php
-rw-r--r--  1 user user   576 Nov 16 01:54 payment_confs_get.php
-rw-r--r--  1 user user   502 Nov 16 01:54 payment_decline.php
-rw-r--r--  1 user user   528 Nov 16 01:54 payment_get_additional_info.php
-rw-r--r--  1 user user   493 Nov 16 01:56 payment_get_info.php
-rw-r--r--  1 user user  1958 Nov 18 14:26 payment_init.php
-rw-r--r--  1 user user   707 Nov 16 01:54 payment_recharge.php
-rw-r--r--  1 user user  2073 Nov 16 01:54 payment_recharge.with.cart.php
-rw-r--r--  1 user user   498 Nov 16 01:54 payment_refund.php
-rw-r--r--  1 user user   496 Nov 16 01:54 payment_void.php
-rw-r--r--  1 user user   819 Nov 16 01:54 redirect.html
[user@host]$ php connect_test.php
<data>
  <hashCode>202cb962ac59075b964b07152d234b70</hashCode>
  <error></error>
  <error_message></error_message>
  <is_error_message></is_error_message>
  <version>3.0.2</version>
</data>

Notes on using the code samples:

  • The code is provided as is, and is supposed to be used for demonstration only. We will not be held responsible for any damage caused by using this code on production deployments/live installations. Please use it at your own risk.
  • To simplify the code, some sensitive information (like the private key and the private key passphrase) was hard-coded in the script. This way, storing the keys "as is" is strongly not recommended. Instead, the keys should be stored encrypted in some way.
  • For the salt generation, the openssl_random_pseudo_bytes() function is used. However, it has known issues; make sure it generates a cryptographically secure sequence. Please check: https://bugs.php.net/bug.php?id=70014. If necessary, you may use another way to generate a cryptographically secure random string. See: http://stackoverflow.com/questions/31492921/cryptographically-secure-random-string-function.
  • The keys hard-coded in the sample are taken from the X-Payments installation at https://demo.xpayments.com. So some operations work out of the box, e.g. payment initialization, payment information, test request, obtaining payment configurations, etc. But some operations will give an error, since the actual payment information on the demo stand can be changed. This applies to secondary operations: capture, void, refund, etc. To see the successful result, you should change the txnId fields hard-coded in the scripts.


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