Two-Stage Payment

When necessary, Partners can enable additional confirmation of the payment amount. This functionality is useful in cases where the price of goods or services may change due to various reasons, such as the client purchasing multiple items while fewer are available in stock, price adjustments, and more.

To enable this functionality, the parameter auto_capture should be set to false in the prepare_payment method. Instead of debiting the funds, they will be held, and the Payment Processor (PC) will wait for an additional method call, set_accept, to finalize the amount for debiting. If the amount remains unchanged, the hold is converted into a debit and the transaction is completed. If the confirmed amount is less than the original amount, the remaining funds are returned to the client's bank card.

---

Note

If the transaction amount is not confirmed within 30 minutes (see the Cancel payment section for more details), the transaction will be automatically canceled.

Important!

A callback will continue to be sent from our side until we receive a waiting_user_action status or capture status to stop further notifications.

---

User Flows

Full Amount Confirmation, 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 redirects the client to our FE.
6. The client selects a payment method.
7. Our FE displays a 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 an OTP code.
11. The client submits the OTP code*.
12. After verification, our BE sends a hold request set_accept to the PC.
13. The PC confirms or declines the hold request.
14. We notify the Partner about the success or failure of the hold.
15. A confirmation request is sent as a callback
16. The Partner confirms the full payment amount.
17. We verify that the amount has not changed.
18. The amount is confirmed with the PC.
19. Confirmation is received from the PC.
20. A confirmation response is sent to the Partner.
21. The client is redirected back to the Partner’s website.

Partial Amount Confirmation, 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 redirects the client to our FE.
6. The client selects a payment method.
7. Our FE displays a 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 PC sends an OTP code.
11. The client submits the OTP code*.
12. After verification, our BE sends a hold request set_accept to the PC.
13. The PC confirms or declines the hold request.
14. We notify the Partner about the success or failure of the hold.
15. A confirmation request is sent as a callback
16. The Partner confirms a partial payment amount.
17. We receive an amount less than the original.
18. The transaction amount is adjusted.
19. Confirmation is received from the PC.
20. A confirmation response is sent to the Partner.
21. The client is redirected back to the Partner’s website.
22. The PC refunds the remaining amount to the client.

Full Amount Confirmation, Visa/MC (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 redirects the client to our FE.
6. The client selects a payment method.
7. Our FE displays a form to enter bank card details.
8. The client fills out and submits their bank card details.
9. Our BE sends a hold request set_accept to the PC.
10. The PC sends a link to the OTP code entry form.
11. Our BE redirects the client to the OTP code entry form.
12. The PC sends an OTP code.
13. The client submits the OTP code.
14. The PC sends confirmation of the funds being held.
15. We notify the Partner about the success or failure of the hold.
16. A confirmation request is sent as a callback
17. The Partner confirms the full payment amount.
18. We verify that the amount has not changed.
19. The amount is confirmed with the PC.
20. Confirmation is received from the PC.
21. A confirmation response is sent to the Partner.
22. The client is redirected back to the Partner’s website.

Partial Amount Confirmation, Visa/MC (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 redirects the client to our FE.
6. The client selects a payment method.
7. Our FE displays a form to enter bank card details.
8. The client fills out and submits their bank card details.
9. Our BE sends a hold request set_accept to the PC.
10. The PC sends a link to the OTP code entry form.
11. Our BE redirects the client to the OTP code entry form.
12. The PC sends an OTP code.
13. The client submits the OTP code.
14. The PC sends confirmation of the funds being held.
15. We notify the Partner about the success or failure of the hold.
16. A confirmation request is sent as a callback
17. The Partner confirms a partial payment amount.
18. We receive an amount less than the original.
19. The transaction amount is adjusted.
20. Confirmation is received from the PC.
21. A confirmation response is sent to the Partner.
22. The client is redirected back to the Partner’s website.
23. The PC refunds the remaining amount to the client.

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.

---

set_accept

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

---

Note

The set_accept method must be called after a successful payment initiation using the prepare_payment method. For integration issues, please contact technical support.

---

Request example

{
    "octo_shop_id": "{{merchant_id}}",
    "octo_secret": "{{merchant_secret}}",
    "octo_payment_UUID": "{{octo_payment_UUID}}",
    "accept_status": "capture", // or "cancel"
    "final_amount": 10.00
}

Request parameters

Parameter	Type	Required	Description
octo_shop_id	int	Yes	The shop's unique ID, available in the shop's personal account.
octo_secret	string	Yes	The shop's personal secret key, generated in the shop's personal account.
octo_payment_UUID	string	Yes	A unique payment ID created by the OCTO system.
accept_status	string	Yes	Transaction confirmation status: capture for confirmation or cancel for cancellation.
final_amount	decimal	Yes	Final payment amount.

---

Successful response example

{
    "error": 0,
    "data": {
        "shop_transaction_id": "6354c573-040a-490f-8d1f-2bb5c89b6d9d",
        "octo_payment_UUID": "6b6b4477-ab8b-49dc-97eb-638b15b9b3e9",
        "status": "succeeded",
        "octo_pay_url": "https://dev-pay.octo.uz/pay/6b6b4477-ab8b-49dc-97eb-638b15b9b3e9?language=uz",
        "transfer_sum": 980.00,
        "refunded_sum": 0.00,
        "total_sum": 1000.00,
        "payed_time": "2024-12-18 16:15:34"
    },
    "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."
}

Successful response parameters

Parameter	Type	Required	Description
error	int	Yes	Error code. 0 means a successful request.
data	object	Yes	Object with detailed information about the payment.
data.shop_transaction_id	string	Yes	The unique ID of the transaction in the shop.
data.octo_payment_UUID	string	Yes	The unique ID of the payment in the Octo system.
data.status	string	Yes	Payment status. Possible values: succeeded, failed, pending, etc.
data.octo_pay_url	string	Yes	Link for payment or review of the payment status.
data.transfer_sum	float	Yes	The amount that was transferred including all deductions.
data.refunded_sum	float	No	The amount that was refunded within the framework of the transaction. Value is 0 if no refunds were made.
data.total_sum	float	Yes	Initially requested amount of the payment.
data.payed_time	string	No	Time of successful completion of the payment in YYYY-MM-DD HH:MM:SS format.
apiMessageForDevelopers	string	No	Message for developers about API status or changes.

---

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	int	Yes	Error code.
errMessage	string	Yes	Error message.
data	object	No	Main data about the transaction (can be null in case of an error).
errorMessage	string	Yes	Deprecated field, error message (recommended to use errMessage).
apiMessageForDevelopers	string	No	Message for developers about API status or changes.

---

callback

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

---

Callback amount confirmation:

{
  "octo_secret":"***",
  "octo_payment_UUID":"0800a75f-1f50-4da8-9225-ae43028cbad1",
  "accept_status":"capture",
  "final_amount":437278.66
}

Parameter	Type	Required	Description
octo_secret	String	Yes	Personal secret key of the store, generated in the store’s account. Must be stored in a secure, inaccessible zone of the store’s website
octo_payment_UUID	String	Yes (if error=0)	Unique payment identifier in the Octo system
accept_status	String	Yes	Confirmation status, required for transactions with the waiting_for_capturestatus Possible values:: capture – payment confirmation cancel – payment cancellation
final_amount	Decimal	No	Confirmed payment amount

---

Callback response structure:

{
  "accept_status": "capture",
  "final_amount": 1000.00
}

Parameter	Type	Required	Description
accept_status	String	Yes	Confirmation status, required for transactions with the waiting_for_capturestatus Possible values: capture – payment confirmation cancel – payment cancellation
final_amount	Decimal	No	Confirmed payment amount

Warning

Octo does not store merchant secret keys in plain text and does not use them to sign notifications. Therefore, before changing the status based on a notification from Octo, it is recommended to additionally request the actual status. This request is signed and encrypted with the store’s secret key, ensuring its authenticity.