Click-API – Request
Description of interaction
Interaction is via the API-interface on the provider’s server. API-interface shall fully comply with this document. Payment created in CLICK system is transmitted over HTTP (HTTPS) by the POST API-interface of the supplier. Supplier provides CLICK URL-addresses to a system in order to communicate with the API-interface. Interaction is divided into two stages:
1. Prepare
2. Complete
Description of the stages of payment:
Preparation and verification of payment (Prepare). Action = 0.
Request parameters:
| # | Parameter name | Data type | Description |
|---|---|---|---|
| 1 | click_trans_id | bigint | ID of transaction (iteration) in CLICK system, i.e. attempt to make a payment. |
| 2 | service_id | int | ID of the service |
| 3 | click_paydoc_id | bigint | Payment ID in CLICK system. Displayed to the customer in SMS when paying. |
| 4 | merchant_trans_id | varchar | Order ID (for online shopping) / personal account / login in the billing of the supplier |
| 5 | amount | float | Payment Amount (in soums) |
| 6 | action | int | An action to perform. 0 – for Prepare |
| 7 | error | int | Status code about completion of payment. 0 – successfully. In case of an error returns an error code. |
| 8 | error_note | varchar | Identification of the code to complete the payment. |
| 9 | sign_time | varchar | Payment date. Format is «YYYY-MM-DD HH:mm:ss» |
| 10 | sign_string | varchar | TestString confirming the authenticity of the submitted query. MD5 hash from the following options:
md5 (click_trans_id + service_id + SECRET_KEY * + merchant_trans_id + amount + action + sign_time) SECRET_KEY – a unique string issued to a supplier when connecting. |
Options of the reply:
| # | Parameter name | Data type | Description |
|---|---|---|---|
| 1 | click_trans_id | bigint | Payment ID in CLICK system |
| 2 | merchant_trans_id | varchar | Order ID (for online shopping) / personal account / login in the billing of the supplier |
| 3 | merchant_prepare_id | int | Payment ID in the billing system of the supplier |
| 4 | error | int | Status code about completion of payment. 0 – successfully. In case of an error returns an error code. |
| 5 | error_note | varchar | Identification of the code to complete the payment. |
CLICK system checks the payment options (merchant_trans_id, amount) with this request:
a. Presence of the formed order / login / personal account number in the billing system of the supplier, its actuality, and the ability of the Supplier to supply a product or service specified in the order.
Note. For online shopping, when receiving a request for supplying an order with the indicated number, the supplier should reserve the appropriate product to prevent “interception” by other customers and purchase of the same product by several customers.
b. The actuality of the order sum or payment.
The supplier must return the order status / login / personal account number at this the request of:
a. Order / login / personal account number and amount is relevant. Payment is pending.
Upon receiving this status Complete request will be sent by the CLICK system.
b. Order / login / personal account number and amount is irrelevant (canceled). Upon receiving this status Complete request with indication of cancellation of payment will be sent by the CLICK system.
Note. Upon receiving a negative response from the Supplier in case the funds have already been written off from the User’s account (a request was given repetitively, if CLICK system does not wait for an reply to the previous Complete request and does not know the status of the order.), then CLICK system will give a Complete request with confirmation sign of the payment. If the funds are not charged, then CLICK also cancels the payment.
c. The order was previously confirmed. Upon receiving this response from the CLICK system, the payment will be completed. Complete request will not be sent repetitively.
Note. The Supplier should put protection from the repetitive payment in its billing system. For a payment which has been previously confirmed, with the same click_trans_id.
Completion of the Payment (Complete). Action = 1.
Request parameters:
| # | Parameter name | Data type | Description |
|---|---|---|---|
| 1 | click_trans_id | bigint | Payment ID in CLICK system |
| 2 | service_id | int | ID of the service |
| 3 | click_paydoc_id | bigint | Payment Number in CLICK system. Displayed to the customer in SMS when paying. |
| 4 | merchant_trans_id | varchar | Order ID (for online shopping) / personal account / login in the billing of the supplier |
| 5 | merchant_prepare_id | int | Payment ID in the billing system of the supplier for confirmation, received in “Prepare” request |
| 6 | amount | float | Payment Amount (in soums) |
| 7 | action | int | An action to perform. 1 – for Comlete |
| 8 | error | int | Status code about completion of payment. 0 – successfully. In case of an error returns an error code. |
| 9 | error_note | varchar | Identification of the code to complete the payment. |
| 10 | sign_time | varchar | Payment date. Format is «YYYY-MM-DD HH:mm:ss» |
| 11 | sign_string | varchar | TestString confirming the authenticity of the submitted query. MD5 hash from the following options:
md5 (click_trans_id + service_id + SECRET_KEY* + merchant_trans_id + merchant_prepare_id + amount + action + sign_time) SECRET_KEY – a unique string issued to a supplier when connecting. |
Options of the reply:
| # | Parameter name | Data type | Description |
|---|---|---|---|
| 1 | click_trans_id | bigint | Payment ID in CLICK system |
| 2 | merchant_trans_id | varchar | Order ID (for online shopping) / personal account / login in the billing of the supplier |
| 3 | merchant_confirm_id | int | Transaction ID to complete the payment in the billing system (may be NULL) |
| 4 | error | int | Status code about completion of payment. 0 – successfully. In case of an error returns an error code. |
| 5 | error_note | varchar | Identification of the code to complete the payment. |
This request completes the process of on-line payment. Upon receiving the positive response from the Service Provider on the Prepare request, CLICK system checks the possibility of payment
for the order by the User. Depending on the success of writing off of amounts, Complete request contains the error parameter with the following values:
1. “0” – successfully. Sent when the funds are written off successfully. In this case the Supplier shall supply the goods or render the paid service.
2. “<= – 1” – Cancel. Sent in case of writing off error or other error, the error code is returned. In this case the Supplier shall remove the reservation (if it is available) from the products, as well as return the response code -9 (see. Table of responses). In case of cancellation by the CLICK, an error description will be sent.
Note. If the response to the ‘Prepare’ request and withdrawal of funds from the card are successful, the response to the Complete request cannot be an error (unless the payment was previously confirmed error = -4 or a second attempt to confirm the previously canceled payment is done error = -9). Upon receipt of an ‘error’ response from the Vendor, after several attempts, the payment will hang for manual investigation by the CLICK Technical Support Service.
If necessary, if an error occurred in the provision of services / sales of the goods after the successful withdrawal of funds from the card and during the execution of the ‘Complete’ request, the Vendor’s Billing responds to the ‘Complete’ request ‘successfully’ and sends a request for ‘cancellation of payment’ (see CLICK-API- MERCHANT item 3. Payment_cancel)