Basket formation and Payment creation

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

Octo PS response to the request for 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 created
canceled - payment canceled
wait_user_action - awaiting user action
waiting_for_capture - payment authorized and awaiting the store confirmation
succeeded - 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