OCTO Payment Service

English

Русский
O‘zbekcha

English

Русский
O‘zbekcha

Appearance

Two-Stage Payment ​

A two-stage payment is configured using the prepare_payment method by specifying the parameter auto_capture = false in the request body. In this payment process, the client's funds are held and it is necessary to invoke the set_accept method to confirm the transaction amount. There are two possible scenarios: when the confirmed amount equals the held amount or when the confirmed amount is less than the held amount.

Note

If the transaction amount is not confirmed within 30 minutes (for more information on cancellations, see the Cancel payment section), 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 ​

Scheme of work when confirming the entire amount, Humo/Uzcard (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 displays their payment page to the client;
  6. The client fills in and sends the bank card details;
  7. The partner conducts the transaction by initiating the pay method;
  8. Our BE confirms;
  9. The partner initiates the verificationInfo method to receive the payment id and the OTP code expiration date;
  10. Our BE confirms;
  11. The processing center (PC) sends the OTP code to the client;
  12. The client sends the OTP code* to the partner;
  13. The partner initiates the check_sms_key method to send the OTP code;
  14. Our BE sends a request to hold funds in the PC;
  15. The PC confirms the hold or refuses;
  16. We notify the Partner about successful/unsuccessful hold;
  17. We send a request to confirm the amount in the form of a callback;
  18. The Partner confirms the full payment amount by initiating the set_accept method;
  19. We made sure that the amount has not changed;
  20. Confirmed the PC amount;
  21. Received confirmation from the PC;
  22. Sent a response to confirm the amount;
  23. Redirected the client back to the Partner's website.

Логотип

Scheme of work with partial confirmation of the amount, Humo/Uzcard (PC) ​

  1. The client selected a product/service;
  2. Clicked "Pay" in the 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 displays their payment page to the Client;
  6. The Client fills in and sends their bank card details;
  7. The Partner conducts the transaction by initiating the pay method;
  8. Our BE confirms;
  9. The Partner initiates the verificationInfo method to receive the payment id and the OTP code expiration date;
  10. Our BE confirms;
  11. The Processing Center (PC) sends the OTP code to the Client;
  12. The Client sends the OTP code* to the Partner;
  13. The Partner initiates the check_sms_key method to send the OTP code;
  14. Our BE sends a request to hold funds to the PC;
  15. The PC confirms the hold or refuses;
  16. We notify the Partner about successful/unsuccessful holding;
  17. We send a request to confirm the amount in the form of a callback;
  18. The Partner confirms part of the payment amount by initiating the set_accept method;
  19. We received an amount less than the original;
  20. We adjusted the transaction amount;
  21. We received confirmation from the PC;
  22. We sent a response to confirm the amount;
  23. We redirected the client back to the Partner's website;
  24. The PC returned the remaining funds to the client.

Логотип

Scheme of work when confirming the entire amount, Visa/MC (PC) ​

  1. The customer selected a product/service;
  2. Clicked "Pay" in the shopping cart;
  3. The partner initiates a transaction using the prepare_payment method;
  4. Our Back-end (BE) sends a link to our Front-end (FE) for payment;
  5. The customer fills in and sends the bank card details on the Partner's page;
  6. The partner conducts the transaction by initiating the pay method;
  7. Our BE sends a request to hold funds to the PC;
  8. The PC sends a link to the OTP code entry form;
  9. Our BE confirms the transaction and sends a link to the on-screen OTP code entry form;
  10. The partner displays the OTP code entry page to the customer;
  11. The PC sends the OTP code to the customer;
  12. The customer sends the OTP code;
  13. The PC sends us a notification about confirmation of holding funds;
  14. We notify the Partner about successful/unsuccessful holding;
  15. We send a request to confirm the amount in the form of a callback;
  16. The Partner confirms the full payment amount by initiating the set_accept method;
  17. We made sure that the amount has not changed;
  18. Confirmed the PC amount;
  19. Received confirmation from the PC;
  20. Sent a response to confirm the amount.

Логотип

Scheme of work with partial confirmation of the amount, Visa/MC (PC) ​

  1. The Client selected a product/service;
  2. Clicked "Pay" in the cart;
  3. The partner initiates a transaction using the prepare_payment method;
  4. Our Back-end (BE) sends a link to our Front-end (FE) for payment;
  5. The Client fills in and sends the bank card details on the Partner's page;
  6. The Partner conducts the transaction by initiating the pay method;
  7. Our BE sends a request to hold funds to the PC;
  8. The PC sends a link to the OTP code entry form;
  9. Our BE confirms the transaction and sends a link to the on-screen OTP code entry form;
  10. The Partner displays the OTP code entry page to the client;
  11. The PC sends the OTP code to the client;
  12. The client sends the OTP code;
  13. The PC sends us a notification about confirmation of holding funds;
  14. We notify the Partner about successful/unsuccessful holding;
  15. We send a request to confirm the amount in the form of a callback;
  16. The Partner confirms part of the payment amount by initiating the set_accept method;
  17. We received an amount less than the original;
  18. We adjusted the transaction amount;
  19. We received confirmation from the PC;
  20. We sent a response to confirm the amount;
  21. The PC returned the remaining funds 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

json
{
  "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

json
{
    "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 ​

ParameterTypeRequiredDescription
octo_shop_idIntegerYesThe shop's unique ID (available in the Personal Account).
octo_secretStringYesThe shop's personal secret key, generated in the Personal Account. Must be kept securely.
shop_transaction_idStringYesThe unique transaction ID on the shop's side. Used to prevent duplication.
auto_captureBooleanYesIf true, funds are automatically written off. If false, additional confirmation is required.
testBooleanYesIndicates if it is a test payment.
init_timeDatetimeYesTime of payment creation (format: yyyy-MM-dd HH:mm:ss).
user_dataObjectNoInformation about the customer, displayed on the payment page.
user_data.user_idStringYes (if present)User's ID in the shop's database.
user_data.phoneStringYes (if present)User's phone number.
user_data.emailStringYes (if present)User's email address.
total_sumDoubleYesTotal payment amount.
currencyStringYesPayment currency (e.g., USD, UZS, RUB).
descriptionStringYesDescription of the product.
basketArrayYesDetailed information about the basket.
basket.position_descStringYes (if present)Item name in the receipt.
basket.countIntegerYes (if present)Quantity of the item.
basket.priceDoubleYes (if present)Price per item.
basket.spicStringNoAdditional field for item details.
payment_methodsArrayNoAvailable payment methods (e.g., bank_card, uzcard, humo).
tsp_idIntegerNoID of the sales and service provider.
return_urlStringYesURL to redirect the customer after payment. Must identify the specific payment.
notify_urlStringNoURL for payment status notifications.
languageStringYesLanguage of the payment form (e.g., en, uz, ru).
ttlIntegerNoPayment lifetime in minutes.

Successful response example ​

json
{
    "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 ​

ParameterTypeRequiredDescription
errorIntegerYesError code (0 indicates success).
dataObjectYesMain object with payment details.
data.shop_transaction_idStringYesShop's transaction ID.
data.octo_payment_UUIDStringYesOcto's payment ID.
data.statusStringYesPayment status.
data.octo_pay_urlStringYesURL to access the payment in Octo.
data.refunded_sumDoubleNoAmount refunded, if any.
data.total_sumDoubleYesTotal payment amount.
apiMessageForDevelopersStringNoMessage for developers (empty if successful).

Unsuccessful response example ​

json
{
    "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 ​

ParameterTypeRequiredDescription
errorIntegerYesError code.
errMessageStringYesError message.
dataObjectNoMain transaction data.
errorMessageStringYesError message (deprecated, use errMessage).
apiMessageForDevelopersStringNoTechnical 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.

pay ​

  • URL: https://secure.octo.uz/pay/{octo_payment_UUID}
  • Method: POST
  • Content-type: application/json

Request example ​

json
{
    "pan": "8600313260861293",
    "exp": "2602",
    "method": "uzcard",
    "cvc2": "",
    "cardHolderName": "CardHolder Name",
    "email": "client@mail.com"
}

Request parameters ​

ParameterTypeRequiredDescription
panstringYesThe customer's card number used for the transaction.
expstringYesCard validity period in YYYY format (year/month).
methodstringYesPayment method. Acceptable values: bank_card, uzcard, humo.
cvc2stringYesCard's CVC2 code.
cardHolderNamestringYesCardholder's name (as indicated on the card).
emailstringYesUser's email address. Required if the user_data block was provided earlier.

Successful response example ​

json
{
    "error": 0,
    "errMessage": "",
    "data": {
        "id": 5520,
        "uuid": "04b7f6dd-4693-4afa-96e9-f42790413de7",
        "processorKey": null,
        "merchantId": 242,
        "merchant": null,
        "merchantTransId": "638421f6-dbc0-4875-8ff9-c6ffe3766087",
        "initialSum": 1000.00,
        "totalSum": 1000.00,
        "splittedSum": 1000.00,
        "currency": "UZS",
        "convertSum": null,
        "convertRate": null,
        "convertCurrency": null,
        "selectedMethod": null,
        "createTime": 1732700367802,
        "expireTime": 1732701267781,
        "peyedTime": null,
        "expiredHoldTime": null,
        "merCreateTime": 15420000,
        "description": "TEST_PAYMENT",
        "autoCapture": true,
        "withoutSite": false,
        "isTest": false,
        "refundLocked": false,
        "returnUrl": "octo.uz",
        "redirectUrl": "https://pay2.octo.uz/uzcard/sms/04b7f6dd-4693-4afa-96e9-f42790413de7",
        "details": {
            "cardInfo": {
                "first6": "860031",
                "last4": "1293",
                "issuerCountryCode": "UZ",
                "cardHolder": "CardHolder Name",
                "saveToken": null
            },
            "transType": "SMS"
        },
        "hold": null,
        "payMethods": [
            {
                "only": null,
                "method": "bank_card"
            },
            {
                "only": null,
                "method": "uzcard"
            },
            {
                "only": null,
                "method": "humo"
            }
        ],
        "status": "created",
        "basket": null,
        "user": {
            "email": "client@mail.com",
            "phone": "998901234567",
            "user_id": "Elbek"
        },
        "language": "uz",
        "tariffId": 2,
        "fee": null,
        "refundedSum": 0.00,
        "bankCode": "RB",
        "cardInputType": "merchant_site",
        "tag": "ticket",
        "test": false
    }
}

Successful response parameters ​

ParameterTypeRequiredDescription
errorintYesError code: 0 means no errors.
errMessagestringNoError message, empty if there is no error.
dataobjectYesAn object containing transaction details.
data.idintYesUnique transaction ID.
data.uuidstringYesUnique UUID for transaction identification.
data.processorKeystringNoProcessing ID, if applicable.
data.merchantIdintYesMerchant ID associated with the transaction.
data.merchantobjectNoMerchant information.
data.merchantTransIdstringYesUnique transaction ID from the merchant.
data.initialSumdecimalYesInitial transaction amount.
data.totalSumdecimalYesTotal transaction amount, including fees.
data.splittedSumdecimalYesAmount split among multiple recipients (if applicable).
data.currencystringYesTransaction currency.
data.convertSumdecimalNoConverted amount (if applicable).
data.convertRatedecimalNoConversion rate (if applicable).
data.convertCurrencystringNoConverted currency (if applicable).
data.selectedMethodstringNoSelected payment method.
data.createTimeintYesTransaction creation time (UNIX timestamp).
data.expireTimeintYesTransaction expiration time (UNIX timestamp).
data.peyedTimeintNoPayment time of the transaction, if paid.
data.expiredHoldTimeintNoExpiration time of funds retention.
data.merCreateTimeintYesTransaction creation time on the merchant’s side.
data.descriptionstringYesDescription of the transaction.
data.autoCaptureboolYesIndicates whether the payment will be automatically captured.
data.withoutSiteboolYesIndicates whether the operation is performed without a website.
data.isTestboolYesIndicates whether the transaction is a test transaction.
data.refundLockedboolYesIndicates whether refunds are locked.
data.returnUrlstringYesURL for redirection after payment.
data.redirectUrlstringYesURL for redirecting to the payment page.
data.detailsobjectNoAdditional transaction details (e.g., cardInfo).
data.details.cardInfoobjectNoInformation about the card used for payment.
data.details.transTypestringYesType of transaction (e.g., SMS).
data.holdobjectNoData regarding funds retention (if applicable).
data.payMethodsarrayYesList of available payment methods.
data.statusstringYesTransaction status.
data.userobjectNoUser information.
data.user.emailstringNoUser’s email address.
data.user.phonestringNoUser’s phone number.
data.user.user_idstringYesUnique user ID (provided in prepare_payment).
data.languagestringYesInterface language. Acceptable values: uz, ru, en.
data.tariffIdintYesTariff ID.
data.riskLevelintYesTransaction risk level.
data.bankCodestringYesBank code.
data.cardInputTypestringYesCard data entry type (merchant_site / octo_page).
data.tagstringNoTag associated with the transaction (e.g., ticket).

Unsuccessful response example ​

json
{
    "error": 2,
    "errMessage": "Wrong secret",
    "data": null
}

Unsuccessful response parameters ​

ParameterTypeRequiredDescription
errorintYesError code.
errMessagestringYesError message.
dataobjectNoMain transaction data, can be null if no additional data.

verificationInfo ​

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

Note

Only the octo_payment_UUID is sent.

Successful response example ​

json
{
    "error": 0,
    "errMessage": "",
    "data": {
        "verifyId": 819,
        "phone": "+998** *****33",
        "secondsLeft": 221
    }
}

Successful response parameters ​

ParameterTypeRequiredDescription
errorIntegerYesError code (0 means no errors).
errMessageStringNoError message, empty if no error.
dataObjectYesObject with verification process details.
verifyIdIntegerYesUnique ID of the verification process.
phoneStringYesPhone number associated with verification (partially hidden).
secondsLeftIntegerYesRemaining time (in seconds) until the verification period expires.

Unsuccessful response example ​

json
{
    "error": 0,
    "errMessage": "",
    "data": {
        "verifyId": 819,
        "phone": "+998** *****33",
        "secondsLeft": 0
    }
}

Unsuccessful response parameters ​

ParameterTypeRequiredDescription
errorIntegerYesError code (0 means no errors, but secondsLeft=0 indicates that the verification period has expired or is inactive).
errMessageStringNoError message, empty if no error.
dataObjectYesObject with verification process details.
verifyIdIntegerYesUnique ID of the verification process.
phoneStringYesPhone number associated with verification (partially hidden).
secondsLeftIntegerYesRemaining time (in seconds) until the verification period expires (0 if verification failed).

Important!

If secondsLeft=0, then the verification time has expired or the verification process is inactive. If you have any questions about integration, please contact Octo technical support.

check_sms_key ​

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

Request Example ​

json
{
  "smsKey": "317168", // Confirmation code sent via SMS
  "paymentId": 822, // Unique payment identifier
  "verifyId": "{{verifyId}}" // Unique verification process identifier (replaced by the value from the previous step)
}

Request Parameters ​

ParameterTypeRequiredDescription
smsKeystringYesSMS code sent for transaction confirmation.
paymentIdintYesUnique payment identifier.
verifyIdintYesIdentifier for operation verification.

Successful Response Example ​

json
{
    "error": 0,                // Error code: 0 means no errors
    "errMessage": "",         // Error message, empty if no errors
    "data": {
        "id": 5520,             // Unique transaction identifier
        "uuid": "04b7f6dd-4693-4afa-96e9-f42790413de7", // Unique UUID for transaction identification
        "processorKey": "010967385013", // Identifier in the processing system
        "merchantId": 242,      // Merchant identifier
        "merchant": null,       // Merchant information
        "merchantTransId": "638421f6-dbc0-4875-8ff9-c6ffe3766087", // Unique transaction ID from the merchant
        "initialSum": 1000.00,  // Initial transaction amount
        "totalSum": 1000.00,    // Total transaction amount, including fees
        "splittedSum": 1000.00, // Amount distributed among several recipients
        "currency": "UZS",     // Transaction currency (Uzbek Sum)
        "convertSum": null,      // Amount in the converted currency
        "convertRate": null,     // Conversion rate
        "convertCurrency": null, // Converted currency
        "selectedMethod": "uzcard", // Selected payment method
        "createTime": 1732700367802, // Transaction creation time (UNIX timestamp)
        "expireTime": 1732701267781, // Transaction expiration time (UNIX timestamp)
        "peyedTime": 1732700437809,  // Successful payment time (UNIX timestamp)
        "expiredHoldTime": null,     // Funds hold expiration time
        "merCreateTime": 15420000,   // Transaction creation time on the merchant side
        "description": "TEST_PAYMENT", // Transaction description
        "autoCapture": true,         // Indicates whether the payment will be auto-captured
        "withoutSite": false,        // Indicates whether the operation is conducted without a website
        "isTest": false,             // Indicates whether the transaction is a test
        "refundLocked": false,       // Indicates whether the refund is locked
        "returnUrl": "octo.uz",     // Return URL after transaction completion
        "redirectUrl": "https://dev-pay.octo.uz/status/04b7f6dd-4693-4afa-96e9-f42790413de7", // URL for redirecting the user
        "details": {
            "transType": "SMS",     // Transaction type (e.g., SMS confirmation)
            "commission": "2.00",  // Transaction commission
            "cardType": "uzcard"   // Type of card used for payment
        },
        "hold": null,                 // Funds hold information
        "payMethods": [              // List of available payment methods
            {
                "only": null,
                "method": "bank_card" // Payment via bank card
            },
            {
                "only": null,
                "method": "uzcard"   // Payment via Uzcard
            },
            {
                "only": null,
                "method": "humo"     // Payment via Humo
            }
        ],
        "status": "succeeded",      // Transaction status (successfully completed)
        "basket": null,              // Information about the shopping basket
        "user": {
            "email": "client@mail.com", // User email
            "phone": "998901234567",   // User phone number
            "user_id": "Elbek"        // User's unique identifier
        },
        "airline": null,             // Airline information (if applicable)
        "language": "uz",           // Interface language
        "tariffId": 2,               // Tariff identifier
        "fee": 20.0000,              // Commission amount
        "transferSum": 980.0000,     // Amount to be transferred after deducting commission
        "refundedSum": 0.00,         // Refunded amount
        "provCode": "uzcard",       // Provider code
        "optionalData": null,        // Additional data
        "forConsideration": false,   // Marked for consideration
        "riskLevel": 0,              // Transaction risk level
        "auditedAt": null,           // Transaction audit time
        "auditorId": null,           // Auditor identifier
        "bankCode": "RB",           // Bank code
        "merchantCardId": null,      // Merchant card identifier
        "processingReference": "1732700437604_5520", // Processing reference
        "requestProcessingStatus": null, // Request processing status
        "requestProcessingTryCount": 0,  // Number of processing attempts
        "currentStep": null,         // Current transaction step
        "tag": "ticket",           // Transaction tag
        "tspId": null,               // TSP identifier
        "cardInputType": "merchant_site", // Type of card input
        "redirectTimeout": null,     // Redirect timeout
        "merchantStatus": null,      // Merchant side status
        "fiscalDetails": {
            "fiscalClassifierIds": [18], // List of fiscal classifiers
            "status": "success",    // Fiscalization status
            "errorCode": "0",       // Fiscalization error code
            "message": "accepted",  // Fiscalization status message
            "createTime": "1732700438714" // Fiscalization creation time (UNIX timestamp)
        },
        "showButtonSaveCard": null,  // Whether to show the save card button
        "test": false                // Indicates whether the transaction is a test
    }
}

Successful Response Parameters ​

ParameterTypeRequiredDescription
errorintYesError code. 0 means the request was successfully processed.
errMessagestringNoError message. Empty if the request was successful.
dataobjectYesObject containing detailed information about the payment.
data.idintYesUnique payment identifier.
data.uuidstringYesUnique UUID of the payment.
data.processorKeystringYesProcessor key involved in the transaction.
data.merchantIdintYesUnique identifier of the merchant.
data.merchant-YesMerchant information.
data.merchantTransIdstringYesUnique transaction identifier provided by the merchant.
data.initialSumdecimalYesInitial payment amount.
data.totalSumdecimalYesTotal payment amount.
data.splittedSumdecimalYesSplit payment amount.
data.currencystringYesPayment currency.
data.convertSumDecimalYesAmount after conversion (if applicable).
data.convertRateDecimalYesConversion rate.
data.convertCurrencyStringYesCurrency after conversion.
data.selectedMethodstringYesSelected payment method.
data.createTimelongYesPayment creation time in Unix Time format.
data.expireTimelongYesPayment expiration time in Unix Time format.
data.peyedTimelongYesPayment completion time in Unix Time format.
data.expiredHoldTimeLongYesExpiration time of funds hold (if applicable).
data.merCreateTimeLongYesCreation time on the merchant's side.
data.descriptionstringYesPayment description.
data.autoCaptureboolYesFlag indicating whether the payment will be auto-captured.
data.returnUrlstringYesURL to return the user after payment completion.
data.redirectUrlstringYesURL to redirect the user for viewing payment status.
data.detailsobjectYesObject with additional payment details.
data.details.transTypestringYesTransaction type.
data.details.commissionstringYesTransaction commission.
data.details.cardTypestringYesType of card used for the payment.
data.holdobjectYesInformation about funds hold, if applicable.
data.payMethodsarrayYesList of available payment methods.
data.payMethods.onlystringYesOptional field indicating method availability for specific conditions.
data.payMethods.methodstringYesName of the payment method.
data.statusstringYesPayment status.
data.basketList<Object>YesInformation about the shopping basket related to the transaction.
data.userobjectYesObject containing user information.
data.user.emailstringYesUser email.
data.user.phonestringYesUser phone number.
data.user.user_idstringYesUnique identifier of the user.
data.airlineObjectYesAirline details (if applicable).
data.languagestringYesLanguage of the payment form interface.
data.tariffIdIntegerYesTariff identifier (if applicable).
data.feedecimalYesAmount of the fee.
data.transferSumdecimalYesTransfer amount after deducting the fee.
data.refundedSumDecimalYesRefunded amount (if applicable).
data.provCodeStringYesCode of the provider that processed the transaction.
data.optionalDatastringYesAdditional data sent in the request or system, may be null.
data.forConsiderationboolYesFlag indicating whether the transaction is under consideration.
data.riskLevelintYesRisk level associated with the transaction. Usually expressed as a number.
data.auditedAtlongYesTime when the transaction was audited, in timestamp format.
data.auditorIdIntegerYesIdentifier of the auditor who conducted the audit.
data.bankCodestringYesBank code.
data.merchantCardIdstringYesUnique identifier of the card stored for the merchant, if applicable.
data.processingReferencestringYesUnique identifier related to the transaction processing in the system.
data.requestProcessingStatusstringYesCurrent status of the request processing, if applicable.
data.requestProcessingTryCountintYesNumber of attempts to process the request.
data.currentStepstringYesCurrent step of transaction processing. May be null.
data.tagstringYesShort tag of the transaction type defined by the merchant, used for identification or filtering transactions.
data.tspIdintYesIdentifier of the trade and service enterprise that provided the service or product.
data.cardInputTypestringYesType of card data input.
data.redirectTimeoutlongYesTimeout for redirecting to the status or payment page, in milliseconds.
data.merchantStatusstringYesCurrent status of the operation on the merchant's side, if supported.
data.fiscalDetailsobjectYesObject containing fiscal details.
data.fiscalDetails.fiscalClassifierIdsList<intr>YesList of fiscal classifier identifiers related to the transaction.
data.fiscalDetails.statusstringYesFiscalization status.
data.fiscalDetails.errorCodestringYesError code associated with fiscal data processing.
data.fiscalDetails.messagestringYesMessage from the fiscal service.
data.fiscalDetails.createTimelongYesTime when fiscal data was created, in timestamp format.
data.showButtonSaveCardboolYesFlag indicating whether to display the save card button.
data.testboolYesIndicates whether the transaction is a test.

Unsuccessful response example ​

json
{
    "error": 2,                // Error code
    "errMessage": "Wrong secret",  // Error message
    "data": null               // Payment data object
}

Unsuccessful response parameters ​

ParameterTypeRequiredDescription
errorintYesError code.
errMessagestringYesError message.
dataobjectNoCore transaction data. Can be null.

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 ​

json
{
    "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 ​

ParameterTypeRequiredDescription
octo_shop_idintYesThe shop's unique ID, available in the shop's personal account.
octo_secretstringYesThe shop's personal secret key, generated in the shop's personal account.
octo_payment_UUIDstringYesA unique payment ID created by the OCTO system.
accept_statusstringYesTransaction confirmation status: capture for confirmation or cancel for cancellation.
final_amountdecimalYesFinal payment amount.

Successful response example ​

json
{
    "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 ​

ParameterTypeRequiredDescription
errorintYesError code. 0 means a successful request.
dataobjectYesObject with detailed information about the payment.
data.shop_transaction_idstringYesThe unique ID of the transaction in the shop.
data.octo_payment_UUIDstringYesThe unique ID of the payment in the Octo system.
data.statusstringYesPayment status. Possible values: succeeded, failed, pending, etc.
data.octo_pay_urlstringYesLink for payment or review of the payment status.
data.transfer_sumfloatYesThe amount that was transferred including all deductions.
data.refunded_sumfloatNoThe amount that was refunded within the framework of the transaction. Value is 0 if no refunds were made.
data.total_sumfloatYesInitially requested amount of the payment.
data.payed_timestringNoTime of successful completion of the payment in YYYY-MM-DD HH:MM:SS format.
apiMessageForDevelopersstringNoMessage for developers about API status or changes.

Unsuccessful response example ​

json
{
    "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 ​

ParameterTypeRequiredDescription
errorintYesError code.
errMessagestringYesError message.
dataobjectNoMain data about the transaction (can be null in case of an error).
errorMessagestringYesDeprecated field, error message (recommended to use errMessage).
apiMessageForDevelopersstringNoMessage for developers about API status or changes.

callback ​

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

Callback amount confirmation: ​

json
{
  "octo_secret":"***",
  "octo_payment_UUID":"0800a75f-1f50-4da8-9225-ae43028cbad1",
  "accept_status":"capture",
  "final_amount":437278.66
}
ParameterTypeRequiredDescription
octo_secretStringYesPersonal 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_UUIDStringYes (if
error=0)		Unique payment identifier in the Octo system
accept_statusStringYesConfirmation status, required for transactions with the waiting_for_capturestatus
Possible values::
capture – payment confirmation
cancel – payment cancellation
final_amountDecimalNoConfirmed payment amount

Callback response structure: ​

json
{
  "accept_status": "capture",
  "final_amount": 1000.00
}
ParameterTypeRequiredDescription
accept_statusStringYesConfirmation status, required for transactions with the waiting_for_capturestatus
Possible values:
capture – payment confirmation
cancel – payment cancellation
final_amountDecimalNoConfirmed 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.

Copyright © Octo Payment Service. All Rights Reserved. 2018-2024