When a customer goes to the basket, the store’s website must prepare a payment through the Octo system in order to receive a link to redirect the customer to the Octo payment pages. To do this, a request must be made from the store server (from a zone inaccessible to the customer):
URL: https://secure.octo.uz/prepare_payment
Method: POST
Content-type: application/json
Request body:
{
"octo_shop_id": 10000,
"octo_secret": "2d45df74-bb95-47cf-a616-8d6dcee2e10d",
"shop_transaction_id": "uniq shop transaction_id",
"auto_capture": true,
"test": false,
"init_time": "2018-03-30 11:22:33",
"user_data": {
"user_id": "unique user_id in store system",
"phone": "79001112233",
"email": "user@mail.com"
},
"total_sum": 103.33,
"currency": "USD",
"description": "Payment name, for example: Moscow-Singapore flight",
"basket": [
{
"position_desc": "MANON Strawberry Yogurt",
"count": 2,
"price": 33.99
},
{
"position_desc": "MANON Banana Yogurt",
"count": 1,
"price": 31.99
}
],
"payment_methods": [
{
"method": "bank_card"
},
{
"method": "qiwi"
}
],
"return_url": "http://merchant.site.uz/return_URL",
"notify_url": "http://merchant.site.uz/send_me_status_URL",
"language": "uz",
"ttl": 15
}Description of request fields:
| Field | Required | Description |
|---|---|---|
| octo_shop_id | Yes | Unique ID of the store (available in the personal cabinet of the store) |
| octo_secret | Yes | The personal secret key of the store, which is generated in the personal cabinet of the store. The key must be kept in a safe, inaccessible area of the store website. |
| shop_transaction_id | Yes | Unique transaction identifier on the store side. Used by OCTO to prevent accidental duplication of transactions. |
| auto_capture | No | If true, then OCTO PS will automatically confirm the debit from the buyer's account. If false, then after authorization of the payment, Octo payment system will expect from the store additional confirmation of the completion of the transaction. False by default. |
| test | No | Test payment or No |
| init_time | Yes | Payment creation time yyyy-MM-dd HH:mm:ss |
| user_data | No | Information about the buyer, used to display on the payment page. |
| user_id | Yes | The user ID in the store database. Required in case of transfer of the entire user_data block. |
| phone | Yes | Required in case of transfer of the entire user_data block. |
| Yes | Required in case of transfer of the entire user_data block. | |
| total_sum | Yes | Total payment amount |
| currency | Yes | Currency. Options: “USD”, “UZS” |
| description | Yes | Product description |
| basket | No | Block of detailed information on the basket. If present, it will be displayed to the buyer when paying. |
| position_desc | Yes | The item name in the receipt. Required in case of transfer of the entire basket block. |
| supplier_shop_id | No | Store ID of the supplier of particular product in the OCTO system (used for splitting payments in the marketplace) |
| count | Yes | The number of such items. Required in case of transfer of the entire basket block. |
| price | Yes | Price of one item. Required in case of transfer of the entire basket block. |
| payment_methods | No | Payment methods available to the buyer. If not transferred, then all available methods will be offered. |
| method | Yes | Name of one method from the following options: bank_card, qiwi, yandex. Required in case of transfer of the entire payment_methods block. |
| return_url | Yes | The URL to which the buyer should be redirected after payment is completed. The URL must contain a unique parameter that identifies a specific payment. |
| notify_url | No | The URL to which the OCTO server will send notifications about payment status changes. If not specified, then the common URL, set in the personal cabinet, will be used. |
| language | No | Language of the payment form. By default is browser language or En. Valid Values: oz - Uzbek, Latin uz - Uzbek, Cyrillic en - English ru - Russian |
| ttl | No | Payment lifetime since creation (in minutes). After this time is up, it will be impossible to make a payment. |
| customer_ip | No | Buyer’s IP address. If specified, the OCTO service will verify it with the payer's IP address and, if different, will block payment. |
In response to a store request, Octo PS responds with the following JSON in the response body:
{
"error": 0,
"status": "created",
"shop_transaction_id": "uniq shop transaction_id",
"octo_payment_UUID": "1145df74-bb95-47cf-a616-8d6dcee2e222",
"octo_pay_url": "https://pay.octo.uz/pay_wisard/1145df74-bb95-47cf-a616-8d6dcee2e222"
}Description of Octo response fields:
| Field | Required | Description |
|---|---|---|
| status | Yes (if error=0) | The status of the payment in the Octo system, one of the following:created - payment createdcanceled - payment canceledwait_user_action - awaiting user actionwaiting_for_capture - payment authorized and awaiting the store confirmationsucceeded - payment completed successfully |
| shop_transaction_id | Yes (if error=0) | Unique transaction identifier on the store side. |
| octo_payment_UUID | Yes (if error=0) | Unique transaction identifier in Octo PS. |
| octo_pay_url | Yes (if error=0) | The URL to redirect buyer to make payment |
| error | Yes | Error code. Options: 0 - no errors 1 - data format error 2 - authorisation error 3 - total amount in the basket (basket) does not match with total_sum 4 - internal service error 5 - store status does not allow to create real payments 6 - invalid currency |
| errorMessage | No | Detailed error description |
| transfer_sum | No | Bill amount minus Octo fees available for a refund to the buyer |
| refunded_sum | No | Amount refunded to the buyer |