One-Stage Payment

A one-stage payment is configured using the prepare_payment method by setting the parameter auto_capture = true, which is the default value in the request body. In this payment process, funds are debited immediately without requiring additional confirmation of the amount by the Partner.

User Flows

Payment via OCTO Form - Humo/Uzcard (Processing Center - PC)

1. The client selects a product or service;
2. In the shopping cart, the client clicks "Pay";
3. The Partner initiates the transaction using the prepare_payment method;
4. Our Back-end (BE) sends a link to our Front-end (FE) for payment;
5. The Partner provides the link for the client to access our FE;
6. The client selects a payment method;
7. Our FE displays the form to enter bank card details;
8. The client fills out and submits their bank card details;
9. Our FE redirects the client to the OTP code entry form;
10. The Processing Center (PC) sends the OTP code;
11. The client submits the OTP code*;
12. After verification, our BE sends a debit request to the PC;
13. The PC confirms the debit or sends a rejection;
14. We notify the Partner of the success or failure of the debit;
15. The client is redirected back to the Partner's website.

Important!

There is a limit for incorrect OTP code entries for Uzcard. If the client enters an incorrect OTP code three times, the transaction is canceled, and a new payment must be registered.

---

Payment via OCTO Form

Payment via OCTO Form - Visa/MC (Processing Center - PC)

1. The client selected a product/service;
2. Clicked "Pay" in the shopping cart;
3. The partner initiates the transaction using the prepare_payment method;
4. Our Back-end (BE) sends a link to our Front-end (FE) for payment;
5. The partner redirects the client to our FE for payment;
6. The client selects the payment method;
7. Our FE sends an on-screen form for entering bank card details;
8. The client fills in and sends bank card details;
9. Our FE displays an on-screen form for entering the OTP code to the client;
10. Visa/MC PC sent the OTP code to the client;
11. The client enters the OTP code received from Visa/MC PC;
12. Visa/MC PC sends a confirmation of the write-off to our BE;
13. Our BE notifies the Partner about successful/unsuccessful write-off;
14. Our BE redirects the client to the Partner's website.

Payment via OCTO Form

Methods

prepare_payment

• URL: https://secure.octo.uz/prepare_payment
• Method: POST
• Content-type: application/json

Test transactions

To conduct a test transaction, when initiating the prepare_payment method, you must specify the test parameter with the value true in the request body. This parameter is optional. If it is not specified, a real transaction will be created.

To conduct a test transaction, specify - test: true

{
  "auto_capture": true,
  "test": true, 
  "init_time": "2024-05-02 09:17:00"
}

Example request

Important!

One-stage payment - auto_capture: true

Two-stage payment - auto_capture: false

{
    "octo_shop_id": 123,
    "octo_secret": "537da54b-835a-4968-9864-c2ae02c5902e",
    "shop_transaction_id": "0000_0000_0000_0000_0010",
    "auto_capture": true,  
    "test": false,
    "init_time": "2024-05-02 09:17:00",
    "user_data": {
        "user_id": "Johnny Depp",
        "phone": "998901234567",
        "email": "octo@mail.com"
    },
    "total_sum": 1000.0,
    "currency": "UZS",
    "description": "TEST_PAYMENT",
    "basket": [
        {
            "position_desc": "Йогурт MANON клубничный",
            "count": 2,
            "price": 10.0,
            "spic": "special_information_for_position"
        },
        {
            "position_desc": "Йогурт MANON банановый",
            "count": 1,
            "price": 20.0,
            "spic": "special_information_for_position"
        }
    ],
    "payment_methods": [
        {
            "method": "bank_card"
        },
        {
            "method": "uzcard"
        },
        {
            "method": "humo"
        }
    ],
    "tsp_id": 18,
    "return_url": "https://octo.uz" // (URL must always be complete),
    "notify_url": "https://notify-url.uz",
    "language": "uz",
    "ttl": 15
}

Request parameters

Parameter	Type	Required	Description
octo_shop_id	Integer	Yes	The shop's unique ID (available in the Personal Account).
octo_secret	String	Yes	The shop's personal secret key, generated in the Personal Account. Must be kept securely.
shop_transaction_id	String	Yes	The unique transaction ID on the shop's side. Used to prevent duplication.
auto_capture	Boolean	Yes	If true, funds are automatically written off. If false, additional confirmation is required.
test	Boolean	Yes	Indicates if it is a test payment.
init_time	Datetime	Yes	Time of payment creation (format: yyyy-MM-dd HH:mm:ss).
user_data	Object	No	Information about the customer, displayed on the payment page.
user_data.user_id	String	Yes (if present)	User's ID in the shop's database.
user_data.phone	String	Yes (if present)	User's phone number.
user_data.email	String	Yes (if present)	User's email address.
total_sum	Double	Yes	Total payment amount.
currency	String	Yes	Payment currency (e.g., USD, UZS, RUB).
description	String	Yes	Description of the product.
basket	Array	Yes	Detailed information about the basket.
basket.position_desc	String	Yes (if present)	Item name in the receipt.
basket.count	Integer	Yes (if present)	Quantity of the item.
basket.price	Double	Yes (if present)	Price per item.
basket.spic	String	No	Additional field for item details.
payment_methods	Array	No	Available payment methods (e.g., bank_card, uzcard, humo).
tsp_id	Integer	No	ID of the sales and service provider.
return_url	String	Yes	URL to redirect the customer after payment. Must identify the specific payment.
notify_url	String	No	URL for payment status notifications.
language	String	Yes	Language of the payment form (e.g., en, uz, ru).
ttl	Integer	No	Payment lifetime in minutes.

---

Successful response example

{
    "error": 0,
    "data": {
        "shop_transaction_id": "c9211e0f-c6ba-4d97-b8be-fb230ef3985b",
        "octo_payment_UUID": "e3f40dc3-4955-412a-853a-2ddd28d3201f",
        "status": "created",
        "octo_pay_url": "https://pay2.octo.uz/pay/e3f40dc3-4955-412a-853a-2ddd28d3201f?language=uz",
        "refunded_sum": 0,
        "total_sum": 1000.0
    },
    "apiMessageForDevelopers": "",
    "shop_transaction_id": "c9211e0f-c6ba-4d97-b8be-fb230ef3985b",
    "octo_payment_UUID": "e3f40dc3-4955-412a-853a-2ddd28d3201f",
    "status": "created",
    "octo_pay_url": "https://pay2.octo.uz/pay/e3f40dc3-4955-412a-853a-2ddd28d3201f?language=uz",
    "refunded_sum": 0,
    "total_sum": 1000.0
}

Successful response parameters

Parameter	Type	Required	Description
error	Integer	Yes	Error code (0 indicates success).
data	Object	Yes	Main object with payment details.
data.shop_transaction_id	String	Yes	Shop's transaction ID.
data.octo_payment_UUID	String	Yes	Octo's payment ID.
data.status	String	Yes	Payment status.
data.octo_pay_url	String	Yes	URL to access the payment in Octo.
data.refunded_sum	Double	No	Amount refunded, if any.
data.total_sum	Double	Yes	Total payment amount.
apiMessageForDevelopers	String	No	Message for developers (empty if successful).

---

Unsuccessful response example

{
    "error": 2,
    "errMessage": "Wrong secret",
    "data": null,
    "errorMessage": "Wrong secret",
    "apiMessageForDevelopers": "The ErrorMessage field is outdated. Please switch to errMessage for unification of the responses. Also, please know that in the future, all fields except error and errMessage will be passed to data. For more information, please contact the technical support of the service."
}

Unsuccessful response parameters

Parameter	Type	Required	Description
error	Integer	Yes	Error code.
errMessage	String	Yes	Error message.
data	Object	No	Main transaction data.
errorMessage	String	Yes	Error message (deprecated, use errMessage).
apiMessageForDevelopers	String	No	Technical message for developers.

Important

In the future, all fields except error and errMessage will be passed to the data object. If you have any questions about the response structure, please contact Octo's technical support.