Двухстадийная оплата

Двухстадийная оплата задаётся в методе prepare_payment с помощью параметра auto_capture = false, указанного в теле запроса. В данном процесса оплаты, денежные средства клиента холдируются и необходимо дополнительно вызывать метод set_accept для подтверждения суммы транзакции. Возможны два сценария: когда подтверждённая сумма равна сумме списания и когда подтверждённая сумма меньше списанной суммы.

Примечание

В случае, если сумма транзакции не будет подтверждена в течение 30 минут (больше информации про отмены, см. в разделе «Отмена платежа»), то транзакция будет автоматически отменена.

Важно!

Callback с нашей стороны будет отправляться до тех пор, пока мы не получим статус waiting_user_action в ответе для прекращения отправок, либо статус capture.

Схема работы

Схема работы при подтверждении всей суммы, Humo/Uzcard (ПЦ)

Клиент выбрал товар/услугу;
В корзине нажал «Оплатить»;
Партнер инициирует транзакцию методом prepare_payment;
Наш Back-end (BE) отправляет ссылку на наш Front-end (FE) для оплаты;
Партнер отображает клиенту свою страницу оплаты;
Клиент заполняет и отправляет данные банковской карты;
Партнер проводит транзакцию инициируя метод pay;
Наш BE подтверждает;
Партнер инициирует метод verificationInfo для получения id платежа и срока действия OTP кода;
Наш BE подтверждает;
Процессинговый центр (ПЦ) отправляет клиенту OTP код;
Клиент отправляет OTP код* Партнеру;
Партнер инициирует метод check_sms_key для отправки OTP кода;
Наш BE отправляет запрос на холдирование средств в ПЦ;
ПЦ подтверждает холдирование, или отказывает;
Мы уведомляем Партнера об успешном/неуспешном холдировании;
Отправляем запрос подтверждения суммы в виде callback;
Партнер подтверждает полную сумму оплаты, инициируя метод set_accept;
Мы убедились, что сумма не изменилась;
Подтвердили сумму ПЦ;
Получили подтверждение от ПЦ;
Отправили ответ на подтверждение суммы;
Перенаправили клиента обратно на сайт Партнера.

Логотип

Схема работы при частичном подтверждении суммы, Humo/Uzcard (ПЦ)

Клиент выбрал товар/услугу;
В корзине нажал «Оплатить»;
Партнер инициирует транзакцию методом prepare_payment;
Наш Back-end (BE) отправляет ссылку на наш Front-end (FE) для оплаты;
Партнер отображает клиенту свою страницу оплаты;
Клиент заполняет и отправляет данные банковской карты;
Партнер проводит транзакцию инициируя метод pay;
Наш BE подтверждает;
Партнер инициирует метод verificationInfo для получения id платежа и срока действия OTP кода;
Наш BE подтверждает;
Процессинговый центр (ПЦ) отправляет клиенту OTP код;
Клиент отправляет OTP код* Партнеру;
Партнер инициирует метод check_sms_key для отправки OTP кода;
Наш BE отправляет запрос на холдирование средств в ПЦ;
ПЦ подтверждает холдирование, или отказывает;
Мы уведомляем Партнера об успешном/неуспешном холдировании;
Отправляем запрос подтверждения суммы в виде callback;
Партнер подтверждает часть суммы оплаты, инициируя метод set_accept;
Мы получили сумму меньше первоначальной;
Провели коррекцию суммы транзакции;
Получили подтверждение от ПЦ;
Отправили ответ на подтверждение суммы;
Перенаправили клиента обратно на сайт Партнера;
ПЦ вернул остаток средств клиенту.

Логотип

Схема работы при подтверждении всей суммы, Visa/MC (ПЦ)

Клиент выбрал товар/услугу;
В корзине нажал «Оплатить»;
Партнер инициирует транзакцию методом prepare_payment;
Наш Back-end (BE) отправляет ссылку на наш Front-end (FE) для оплаты;
Клиент на странице Партнера заполняет и отправляет данные банковской карты;
Партнер проводит транзакцию инициируя метод pay;
Наш BE отправляет запрос на холдирование средств в ПЦ;
ПЦ отправляет ссылку на форму ввода OTP кода;
Наш BE подтверждает проведение транзакции и отправляет ссылку на экранную форму ввода OTP кода;
Партнера отображает страницу ввода OTP кода клиенту;
ПЦ отправляет клиенту OTP код;
Клиент отправляет OTP код;
ПЦ отправляет нам уведомление о подтверждении холдирования средств;
Мы уведомляем Партнера об успешном/неуспешном холдировании;
Отправляем запрос подтверждения суммы в виде callback;
Партнер подтверждает полную сумму оплаты, инициируя метод set_accept;
Мы убедились, что сумма не изменилась;
Подтвердили сумму ПЦ;
Получили подтверждение от ПЦ;
Отправили ответ на подтверждение суммы.

Логотип

Схема работы при частичном подтверждении суммы, Visa/MC (ПЦ)

Клиент выбрал товар/услугу;
В корзине нажал «Оплатить»;
Партнер инициирует транзакцию методом prepare_payment;
Наш Back-end (BE) отправляет ссылку на наш Front-end (FE) для оплаты;
Клиент на странице Партнера заполняет и отправляет данные банковской карты;
Партнер проводит транзакцию инициируя метод pay;
Наш BE отправляет запрос на холдирование средств в ПЦ;
ПЦ отправляет ссылку на форму ввода OTP кода;
Наш BE подтверждает проведение транзакции и отправляет ссылку на экранную форму ввода OTP кода;
Партнера отображает страницу ввода OTP кода клиенту;
ПЦ отправляет клиенту OTP код;
Клиент отправляет OTP код;
ПЦ отправляет нам уведомление о подтверждении холдирования средств;
Мы уведомляем Партнера об успешном/неуспешном холдировании;
Отправляем запрос подтверждения суммы в виде callback;
Партнер подтверждает часть суммы оплаты, инициируя метод set_accept;
Мы получили сумму меньше первоначальной;
Провели коррекцию суммы транзакции;
Получили подтверждение от ПЦ;
Отправили ответ на подтверждение суммы;
ПЦ вернул остаток средств клиенту.

Логотип

Методы

`prepare_payment`

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

Тестовые транзакции

Для проведения тестовой транзакции необходимо при инициации метода prepare_payment указать в теле запроса параметр test со значением true. Этот параметр является необязательным. Если он не указан, будет создана реальная транзакция.

Для проведения тестовой транзакции укажите - test: true

json

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

Пример запроса

Важно!

Одностадийная оплата - auto_capture: true

Двухстадийная оплата - 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 всегда должен быть полным),
    "notify_url": "https://notify-url.uz",
    "language": "uz",
    "ttl": 15
}

Параметры запроса

Параметр	Тип	Обязательность	Описание
octo_shop_id	Integer	Да	Уникальный ID магазина (доступен в ЛК магазина).
octo_secret	String	Да	Персональный секретный ключ магазина, который генерируется в ЛК магазина. Должен содержаться в безопасной недоступной зоне сайта магазина.
shop_transaction_id	String	Да	Уникальный идентификатор транзакции на стороне магазина. Используется OCTO для предотвращения случайного дублирования транзакций.
auto_capture	Bool	Да	Если true, то ПС Octo будет автоматически подтверждать списание средств со счета покупателя. Если false, то после авторизации платежа Octo будет ожидать от магазина дополнительного подтверждения завершения транзакции. По умолчанию false
test	Bool	Да	Тестовый платёж или нет.
init_time	Datetime	Да	Время создания платежа в формате yyyy-MM-dd HH:mm:ss.
user_data	Object	Нет	Информация о покупателе, используется для отображения на странице оплаты.
user_data.user_id	String	Да (если передаётся весь блок user_data)	ID пользователя в БД магазина.
user_data.phone	String	Да (если передаётся весь блок user_data)	Номер телефона пользователя.
user_data.email	String	Да (если передаётся весь блок user_data)	Электронная почта пользователя.
total_sum	Double	Да	Итоговая сумма платежа.
currency	String	Да	Валюта. Варианты: USD, UZS, RUB.
description	String	Да	Описание товара.
basket	Array	Да	Блок детальной информации по корзине. Если присутствует, то будет отображен покупателю при оплате.
basket.position_desc	String	Да (если передаётся весь блок basket)	Название позиции в чеке.
basket.count	Int	Да (если передаётся весь блок basket)	Число таких позиций.
basket.price	Double	Да (если передаётся весь блок basket)	Цена одной позиции.
basket.spic	String	Нет	Дополнительное поле для уточнения информации о позиции в корзине.
payment_methods	Array	Нет	Множество доступных покупателю методов оплаты. Если не передается, то будут предложены все доступные методы.
payment_methods.method	String	Да (если передаётся весь блок payment_methods)	Название одного метода из вариантов: bank_card, uzcard, humo.
tsp_id	Int	Нет	Идентификатор торгово-сервисного предприятия, обеспечивающего продажу данной услуги или товара.
return_url	String	Да	URL на который следует перенаправить покупателя после завершения оплаты. URL должен содержать уникальный параметр, идентифицирующий конкретный платеж.
notify_url	String	Нет	URL на который сервер OCTO будет отправлять нотификации об изменении статуса платежа. Если не установлен, то используется общий URL, который установлен в личном кабинете.
language	String	Да	Язык платежной формы. По умолчанию - язык браузера или en. Допустимые значения: oz - узбекский (латиница), uz - узбекский (кириллица), en - английский, ru - русский.
ttl	Int	Нет	Время жизни платежа с момента создания (в минутах). По истечению этого времени провести платеж будет невозможно.

Пример успешного ответа

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
}

Параметры успешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да (если `error=0`)	Код ошибки (0 — ошибок нет).
data	object	Да (если `error=0`)	Основной объект с данными о платеже.
data.shop_transaction_id	string	Да (если `error=0`)	Уникальный идентификатор транзакции на стороне магазина.
data.octo_payment_UUID	string	Да (если `error=0`)	Уникальный идентификатор платежа в системе Octo.
data.status	string	Да (если `error=0`)	Статус платежа.
data.octo_pay_url	string	Да (если `error=0`)	URL для перехода к оплате в системе Octo.
data.refunded_sum	double	Нет	Сумма, которая была возвращена (если есть возвраты).
data.total_sum	double	Да (если `error=0`)	Итоговая сумма платежа.
apiMessageForDevelopers	string	Нет	Сообщение для разработчиков, предоставляемое API (пустое в случае успеха).
shop_transaction_id	string	Да (если `error=0`)	Дублирует `shop_transaction_id` из объекта `data`.
octo_payment_UUID	string	Да (если `error=0`)	Дублирует `octo_payment_UUID` из объекта `data`.
status	string	Да (если `error=0`)	Дублирует `status` из объекта `data`.
octo_pay_url	string	Да (если `error=0`)	Дублирует `octo_pay_url` из объекта `data`.
refunded_sum	double	Да (если `error=0`)	Дублирует `refunded_sum` из объекта `data`.
total_sum	double	Да (если `error=0`)	Дублирует `total_sum` из объекта `data`.

Пример неуспешного ответа

json

{
    "error": 2,
    "errMessage": "Wrong secret",
    "data": null,
    "errorMessage": "Wrong secret",
    "apiMessageForDevelopers": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов. Так же пожалуйста знайте, что в дальнейшем все поля кроме error и errMessage будут передаваться в data. Для более подробного ознакомление свяжитесь с технической поддержкой сервиса"
}

Параметры неуспешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки (0 указывает на отсутствие ошибок).
errMessage	string	Да	Сообщение об ошибке (если ошибка произошла).
data	object	Нет	Основные данные транзакции (при ошибке может быть `null`).
errorMessage	string	Да	Сообщение об ошибке (если ошибка произошла).
apiMessageForDevelopers	string	Нет	Техническое сообщение (поле для дополнительной информации).

Важно!

В дальнейшем все поля, кроме error и errMessage, будут передаваться в объект data. Если у вас возникают вопросы по поводу структуры ответов, пожалуйста, свяжитесь с технической поддержкой сервиса Octo.

`pay`

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

Пример запроса

json

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

Параметры запроса

Параметр	Тип	Обязательность	Описание
pan	string	Да	Номер карты клиента, который используется для проведения транзакции.
exp	string	Да	Срок действия карты в формате ГГММ (год/месяц).
method	string	Да	Метод оплаты. Допустимые значения: `bank_card`, `uzcard`, `humo`.
cvc2	string	Да	CVC2 код карты.
cardHolderName	string	Да	Имя держателя карты (как указано на карте).
email	string	Да	Электронная почта пользователя. (Обязательно, если передаётся весь блок `user_data` в `prepare_payment`)

Пример успешного ответа

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"
        },
        "airline": null,
        "language": "uz",
        "tariffId": 2,
        "fee": null,
        "transferSum": null,
        "refundedSum": 0.00,
        "provCode": null,
        "optionalData": null,
        "forConsideration": false,
        "riskLevel": -1,
        "auditedAt": null,
        "auditorId": null,
        "bankCode": "RB",
        "merchantCardId": null,
        "processingReference": null,
        "requestProcessingStatus": null,
        "requestProcessingTryCount": 0,
        "currentStep": null,
        "tag": "ticket",
        "tspId": null,
        "cardInputType": "merchant_site",
        "redirectTimeout": null,
        "merchantStatus": null,
        "fiscalDetails": null,
        "showButtonSaveCard": null,
        "test": false
    }
}

Параметры успешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки: `0` означает отсутствие ошибок.
errMessage	string	Нет	Сообщение об ошибке, пустое если ошибки нет.
data	object	Да	Объект с деталями транзакции.
data.id	int	Да	Уникальный идентификатор транзакции.
data.uuid	string	Да	Уникальный UUID для идентификации транзакции.
data.processorKey	string	Нет	Идентификатор процессинга, если применимо.
data.merchantId	int	Да	Идентификатор торговца, связанный с транзакцией.
data.merchant	object	Нет	Информация о торговце.
data.merchantTransId	string	Да	Уникальный ID транзакции от торговца.
data.initialSum	decimal	Да	Изначальная сумма транзакции.
data.totalSum	decimal	Да	Общая сумма транзакции, включая комиссии.
data.splittedSum	decimal	Да	Сумма, разделенная на несколько получателей (если применимо).
data.currency	string	Да	Валюта транзакции.
data.convertSum	decimal	Нет	Сумма в конвертированной валюте (если применимо).
data.convertRate	decimal	Нет	Курс конвертации (если применимо).
data.convertCurrency	string	Нет	Конвертируемая валюта (если применимо).
data.selectedMethod	string	Нет	Выбранный метод оплаты.
data.createTime	int	Да	Время создания транзакции (UNIX timestamp).
data.expireTime	int	Да	Время истечения транзакции (UNIX timestamp).
data.peyedTime	int	Нет	Время оплаты транзакции, если оплачена.
data.expiredHoldTime	int	Нет	Время истечения удержания средств.
data.merCreateTime	int	Да	Время создания транзакции на стороне торговца.
data.description	string	Да	Описание транзакции.
data.autoCapture	bool	Да	Указывает, будет ли оплата автоматически захвачена.
data.withoutSite	bool	Да	Указывает, происходит ли операция без веб-сайта.
data.isTest	bool	Да	Указывает, является ли транзакция тестовой.
data.refundLocked	bool	Да	Указывает, заблокирован ли возврат средств.
data.returnUrl	string	Да	URL возврата после оплаты.
data.redirectUrl	string	Да	URL для перенаправления на страницу оплаты.
data.details	object	Нет	Дополнительные детали о транзакции (например, `cardInfo`).
data.details.cardInfo	object	Нет	Информация о карте, используемой для оплаты.
data.details.transType	string	Да	Тип транзакции (например, `SMS`).
data.hold	object	Нет	Данные об удержании средств (если применимо).
data.payMethods	array	Да	Список доступных методов оплаты.
data.status	string	Да	Статус транзакции.
data.user	object	Нет	Информация о пользователе.
data.user.email	string	Нет	Email пользователя.
data.user.phone	string	Нет	Телефон пользователя.
data.user.user_id	string	Да	Уникальный идентификатор пользователя (переданный в `prepare_payment`).
data.language	string	Да	Язык интерфейса. Допустимые значения: `uz`, `ru`, `en`.
data.tariffId	int	Да	Идентификатор тарифа.
data.riskLevel	int	Да	Уровень риска транзакции.
data.bankCode	string	Да	Код банка.
data.cardInputType	string	Да	Тип ввода данных карты (`merchant_site` / `octo_page`).
data.tag	string	Нет	Тег, связанный с транзакцией (например, `ticket`).

Пример неуспешного ответа

json

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

Параметры неуспешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки.
errMessage	string	Да	Сообщение об ошибке.
data	object	Нет	Основные данные транзакции (может быть `null`).

`verificationInfo`

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

Примечание

Отправляется только octo_payment_UUID.

Пример успешного ответа

json

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

Параметры успешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки: 0 означает отсутствие ошибок.
errMessage	string	Нет	Сообщение об ошибке, пустое если ошибки нет.
data	object	Да	Объект с деталями процесса верификации.
verifyId	int	Да	Уникальный идентификатор процесса верификации.
phone	string	Да	Номер телефона, к которому привязана верификация (частично скрыт для безопасности).
secondsLeft	int	Да	Оставшееся время (в секундах) до истечения срока действия верификации.

Пример неуспешного ответа

json

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

Примечание

В случае неуспешного ответа verificationInfo, будет такой же формат ответа, что и при успехе, но в параметре secondsLeft будет значение 0.

Параметры неуспешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки (0 означает отсутствие ошибок, но secondsLeft=0 говорит о том, что верификация неактивна или время истекло).
errMessage	string	Нет	Сообщение об ошибке (может быть пустым).
data	object	Да	Объект с деталями процесса верификации.
verifyId	int	Да	Уникальный идентификатор процесса верификации.
phone	string	Да	Номер телефона, к которому привязана верификация (частично скрыт).
secondsLeft	int	Да	Оставшееся время (в секундах) до истечения срока действия верификации (равно 0 в случае неуспешного ответа).

Важно!

Если secondsLeft=0, значит время верификации истекло или процесс верификации неактивен. При возникновении вопросов по интеграции обращайтесь в техническую поддержку сервиса Octo.

`check_sms_key`

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

Пример запроса

json

{
  "smsKey": "317168", // Код подтверждения, отправленный по SMS
  "paymentId": 822, // Уникальный идентификатор платежа
  "verifyId": "{{verifyId}}" // Уникальный идентификатор процесса верификации (заменяется значением из предыдущего шага)
}

Параметры запроса

Параметр	Тип	Обязательность	Описание
smsKey	string	Да	SMS-код, отправленный для подтверждения транзакции.
paymentId	int	Да	Уникальный идентификатор платежа
verifyId	int	Да	Идентификатор для подтверждения операции

Пример успешного ответа

json

{
    "error": 0,                // Код ошибки: 0 означает отсутствие ошибок
    "errMessage": "",         // Сообщение об ошибке, пустое если ошибки нет
    "data": {
        "id": 5520,             // Уникальный идентификатор транзакции
        "uuid": "04b7f6dd-4693-4afa-96e9-f42790413de7", // Уникальный UUID для идентификации транзакции
        "processorKey": "010967385013", // Идентификатор в процессинговой системе
        "merchantId": 242,      // Идентификатор торговца
        "merchant": null,       // Информация о торговце
        "merchantTransId": "638421f6-dbc0-4875-8ff9-c6ffe3766087", // Уникальный ID транзакции от торговца
        "initialSum": 1000.00,  // Изначальная сумма транзакции
        "totalSum": 1000.00,    // Общая сумма транзакции, включая комиссии
        "splittedSum": 1000.00, // Сумма, распределенная между несколькими получателями
        "currency": "UZS",     // Валюта транзакции (узбекский сум)
        "convertSum": null,      // Сумма в конвертированной валюте
        "convertRate": null,     // Курс конвертации
        "convertCurrency": null, // Конвертируемая валюта
        "selectedMethod": "uzcard", // Выбранный метод оплаты
        "createTime": 1732700367802, // Время создания транзакции (UNIX timestamp)
        "expireTime": 1732701267781, // Время истечения транзакции (UNIX timestamp)
        "peyedTime": 1732700437809,  // Время успешной оплаты (UNIX timestamp)
        "expiredHoldTime": null,     // Время истечения удержания средств
        "merCreateTime": 15420000,   // Время создания транзакции на стороне торговца
        "description": "TEST_PAYMENT", // Описание транзакции
        "autoCapture": true,         // Автоматическое завершение оплаты
        "withoutSite": false,        // Выполнение операции без использования веб-сайта
        "isTest": false,             // Является ли транзакция тестовой
        "refundLocked": false,       // Заблокирован ли возврат средств
        "returnUrl": "octo.uz",     // URL возврата после завершения транзакции
        "redirectUrl": "https://dev-pay.octo.uz/status/04b7f6dd-4693-4afa-96e9-f42790413de7", // URL для перенаправления пользователя
        "details": {
            "transType": "SMS",     // Тип транзакции (например, SMS-подтверждение)
            "commission": "2.00",  // Комиссия за транзакцию
            "cardType": "uzcard"   // Тип карты, используемой для оплаты
        },
        "hold": null,                 // Данные об удержании средств
        "payMethods": [              // Список доступных методов оплаты
            {
                "only": null,
                "method": "bank_card" // Оплата банковской картой
            },
            {
                "only": null,
                "method": "uzcard"   // Оплата через Uzcard
            },
            {
                "only": null,
                "method": "humo"     // Оплата через Humo
            }
        ],
        "status": "succeeded",      // Статус транзакции (успешно завершена)
        "basket": null,              // Информация о корзине покупок
        "user": {
            "email": "client@mail.com", // Электронная почта пользователя
            "phone": "998901234567",   // Телефон пользователя
            "user_id": "Elbek"        // Уникальный идентификатор пользователя
        },
        "airline": null,             // Данные авиакомпании (если применимо)
        "language": "uz",           // Язык интерфейса
        "tariffId": 2,               // Идентификатор тарифа
        "fee": 20.0000,              // Сумма комиссии
        "transferSum": 980.0000,     // Сумма к перечислению после вычета комиссии
        "refundedSum": 0.00,         // Сумма возврата
        "provCode": "uzcard",       // Код провайдера
        "optionalData": null,        // Дополнительные данные
        "forConsideration": false,   // Пометка для анализа
        "riskLevel": 0,              // Уровень риска транзакции
        "auditedAt": null,           // Время аудита транзакции
        "auditorId": null,           // Идентификатор аудитора
        "bankCode": "RB",           // Код банка
        "merchantCardId": null,      // Идентификатор карты торговца
        "processingReference": "1732700437604_5520", // Референс процессинга
        "requestProcessingStatus": null, // Статус обработки запроса
        "requestProcessingTryCount": 0,  // Количество попыток обработки запроса
        "currentStep": null,         // Текущий шаг транзакции
        "tag": "ticket",           // Тег транзакции
        "tspId": null,               // Идентификатор TSP
        "cardInputType": "merchant_site", // Тип ввода карты
        "redirectTimeout": null,     // Тайм-аут перенаправления
        "merchantStatus": null,      // Статус на стороне торговца
        "fiscalDetails": {
            "fiscalClassifierIds": [18], // Список фискальных классификаторов
            "status": "success",    // Статус фискализации
            "errorCode": "0",       // Код ошибки фискализации
            "message": "accepted",  // Сообщение о статусе фискализации
            "createTime": "1732700438714" // Время создания фискализации (UNIX timestamp)
        },
        "showButtonSaveCard": null,  // Показ кнопки для сохранения карты
        "test": false                // Является ли транзакция тестовой
    }
}

Параметры успешного ответа

Параметр	Тип	Обязательность	Описание
`error`	int	Да	Код ошибки. 0 означает, что запрос выполнен успешно.
`errMessage`	string	Нет	Сообщение об ошибке. Пустое значение при успешном выполнении запроса.
`data`	object	Да	Объект с детальной информацией о платеже.
`data.id`	int	Да	Уникальный идентификатор платежа.
`data.uuid`	string	Да	Уникальный UUID платежа.
`data.processorKey`	string	Да	Ключ процессора, участвующего в транзакции.
`data.merchantId`	int	Да	Уникальный идентификатор мерчанта.
`data.merchant`	-	Да	Данные о мерчанте.
`data.merchantTransId`	string	Да	Уникальный идентификатор транзакции, предоставленный мерчантом.
`data.initialSum`	decimal	Да	Изначальная сумма платежа.
`data.totalSum`	decimal	Да	Общая сумма платежа.
`data.splittedSum`	decimal	Да	Разделённая сумма платежа.
`data.currency`	string	Да	Валюта платежа.
`data.convertSum`	Decimal	Да	Сумма после конвертации (если применимо).
`data.convertRate`	Decimal	Да	Курс конвертации.
`data.convertCurrency`	String	Да	Валюта после конвертации.
`data.selectedMethod`	string	Да	Выбранный метод оплаты.
`data.createTime`	long	Да	Время создания платежа в формате Unix Time.
`data.expireTime`	long	Да	Время истечения платежа в формате Unix Time.
`data.peyedTime`	long	Да	Время завершения платежа в формате Unix Time.
`data.expiredHoldTime`	Long	Да	Время истечения удержания средств (если применимо).
`data.merCreateTime`	Long	Да	Время создания на стороне мерчанта.
`data.description`	string	Да	Описание платежа.
`data.autoCapture`	bool	Да	Флаг автоматического завершения платежа.
`data.returnUrl`	string	Да	URL для возврата пользователя после завершения платежа.
`data.redirectUrl`	string	Да	URL для перенаправления пользователя для просмотра статуса платежа.
`data.details`	object	Да	Объект с дополнительной информацией о платеже.
`data.details.transType`	string	Да	Тип транзакции.
`data.details.commission`	string	Да	Размер комиссии за транзакцию.
`data.details.cardType`	string	Да	Тип карты, использованной для платежа.
`data.hold`	object	Да	Информация о блокировке средств, если применимо (null, если не используется).
`data.payMethods`	array	Да	Список доступных методов оплаты.
`data.payMethods.only`	string	Да	Опциональное поле, указывающее доступность метода оплаты для конкретных условий.
`data.payMethods.method`	string	Да	Название метода оплаты.
`data.status`	string	Да	Статус платежа.
`data.basket`	`List<Object>`	Да	Данные о корзине товаров/услуг, связанных с транзакцией.
`data.user`	object	Да	Объект с информацией о пользователе.
`data.user.email`	string	Да	Электронная почта пользователя.
`data.user.phone`	string	Да	Телефонный номер пользователя.
`data.user.user_id`	string	Да	Уникальный идентификатор пользователя.
`data.airline`	Object	Да	Детали авиаперевозки (если применимо).
`data.language`	string	Да	Язык интерфейса платежной формы.
`data.tariffId`	Integer	Да	Идентификатор тарифа (если применимо).
`data.fee`	decimal	Да	Размер комиссии в валюте платежа.
`data.transferSum`	decimal	Да	Сумма перевода за вычетом комиссии.
`data.refundedSum`	Decimal	Да	Сумма возврата (если применимо).
`data.provCode`	String	Да	Код провайдера, который обработал транзакцию.
`data.optionalData`	string	Да	Дополнительные данные, переданные в запросе или системе, могут быть null.
`data.forConsideration`	bool	Да	Флаг, указывающий, находится ли транзакция на стадии рассмотрения.
`data.riskLevel`	int	Да	Уровень риска, связанный с транзакцией. Обычно задаётся числом.
`data.auditedAt`	long	Да	Время, когда транзакция была проверена, в формате timestamp.
`data.auditorId`	Integer	Да	Идентификатор пользователя или системы, проводившей аудит.
`data.bankCode`	string	Да	Код банка, участвующего в обработке транзакции.
`data.merchantCardId`	string	Да	Уникальный идентификатор карты, сохранённой для данного мерчанта, если применимо.
`data.processingReference`	string	Да	Уникальный идентификатор, связанный с обработкой транзакции в процессинговой системе.
`data.requestProcessingStatus`	string	Да	Текущий статус обработки запроса, если применимо.
`data.requestProcessingTryCount`	int	Да	Количество попыток обработки текущего запроса.
`data.currentStep`	string	Да	Текущий этап обработки транзакции. Может быть null.
`data.tag`	string	Да	Короткий маркер типа транзакции, заданный мерчантом, для идентификации или фильтрации транзакций.
`data.tspId`	int	Да	Идентификатор торгово-сервисного предприятия.
`data.cardInputType`	string	Да	Тип ввода данных карты.
`data.redirectTimeout`	long	Да	Таймаут для редиректа на страницу статуса или оплаты, в миллисекундах.
`data.merchantStatus`	string	Да	Текущий статус операции со стороны мерчанта, если поддерживается.
`data.fiscalDetails`	object	Да	Объект с фискальными данными.
`data.fiscalDetails.fiscalClassifierIds`	`List<intr>`	Да	Список идентификаторов налоговых классификаторов, связанных с транзакцией.
`data.fiscalDetails.status`	string	Да	Статус фискализации.
`data.fiscalDetails.errorCode`	string	Да	Код ошибки, связанный с обработкой фискальных данных.
`data.fiscalDetails.message`	string	Да	Сообщение от фискального сервиса.
`data.fiscalDetails.createTime`	long	Да	Время создания фискальных данных в формате timestamp.
`data.showButtonSaveCard`	bool	Да	Флаг, указывающий, нужно ли отображать кнопку для сохранения карты.
`data.test`	bool	Да	Указывает, является ли транзакция тестовой.

Пример неуспешного ответа

json

{
    "error": 2,                // Код ошибки
    "errMessage": "Wrong secret",  // Текст ошибки
    "data": null               // Объект с данными о платеже
}

Параметры неуспешного ответа

Параметр	Тип	Обязательность	Описание
`error`	int	Да	Код ошибки.
`errMessage`	string	Да	Сообщение об ошибке.
`data`	object	Нет	Основные данные транзакции. Может быть `null`.

`set_accept`

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

Важно!

Метод set_accept должен вызываться после успешной инициации платежа методом prepare_payment. При возникновении вопросов по интеграции обратитесь в техническую поддержку.

Пример запроса

json

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

Параметры запроса

Параметр	Тип	Обязательность	Описание
octo_shop_id	int	Да	Уникальный идентификатор магазина, доступный в личном кабинете магазина.
octo_secret	string	Да	Персональный секретный ключ магазина, генерируемый в личном кабинете.
octo_payment_UUID	string	Да	Уникальный идентификатор платежа, созданный системой OCTO.
accept_status	string	Да	Статус подтверждения транзакции: `capture` для подтверждения или `cancel` для отмены.
final_amount	decimal	Да	Окончательная сумма платежа.

Пример успешного ответа

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": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов."
}

Параметры успешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки. `0` означает успешный запрос.
data	object	Да	Объект с детальной информацией о платеже.
data.shop_transaction_id	string	Да	Уникальный идентификатор транзакции в магазине.
data.octo_payment_UUID	string	Да	Уникальный идентификатор платежа в системе Octo.
data.status	string	Да	Статус платежа. Возможные значения: `succeeded`, `failed`, `pending` и др.
data.octo_pay_url	string	Да	Ссылка для оплаты или просмотра статуса платежа.
data.transfer_sum	float	Да	Сумма, которая была переведена, с учетом всех вычетов.
data.refunded_sum	float	Нет	Сумма, которая была возвращена в рамках транзакции. Если возвратов не было, значение `0`.
data.total_sum	float	Да	Изначально запрошенная сумма платежа.
data.payed_time	string	Нет	Время успешного завершения платежа в формате `YYYY-MM-DD HH:MM:SS`.
apiMessageForDevelopers	string	Нет	Сообщение для разработчиков о статусе API или изменениях.

Пример неуспешного ответа

json

{
    "error": 2,
    "errMessage": "Wrong secret",
    "data": null,
    "errorMessage": "Wrong secret",
    "apiMessageForDevelopers": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов."
}

Параметры неуспешного ответа

Параметр	Тип	Обязательность	Описание
error	int	Да	Код ошибки.
errMessage	string	Да	Сообщение об ошибке.
data	object	Нет	Основные данные транзакции (при ошибке может быть `null`).
errorMessage	string	Да	Устаревшее поле, сообщение об ошибке (рекомендуется использовать `errMessage`).
apiMessageForDevelopers	string	Нет	Сообщение для разработчиков о статусе API или изменениях.

`callback`

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

Callback подтверждения суммы:

json

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

Параметр	Тип	Обязательность	Описание
octo_secret	String	Да	Персональный секретный ключ магазина, который генерируется в ЛК магазина. Должен содержаться в безопасной недоступной зоне сайта магазина
octo_payment_UUID	String	Да (если `error=0`)	Уникальный идентификатор платежа в системе Octo
accept_status	String	Да	Статус подтверждения, обязательно для транзакций со статусом `waiting_for_capture` Возможные значения: `capture` – подтверждение платежа `cancel` – отмена платежа
final_amount	Decimal	Нет	Подтверждаемая сумма платежа

Структура ответа callback:

json

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

Параметр	Тип	Обязательность	Описание
accept_status	String	Да	Статус подтверждения, обязательно для транзакций со статусом `waiting_for_capture` Возможные значения: `capture` – подтверждение платежа `cancel` – отмена платежа
final_amount	Decimal	Нет	Подтверждаемая сумма платежа

Предупреждение

Octo не хранит секретные ключи магазинов в открытом виде и не использует их для подписи нотификаций. Поэтому, прежде чем изменять статус на основе уведомления от Octo, рекомендуется дополнительно запросить актуальный статус. Такой запрос подписывается и шифруется секретным ключом магазина, что гарантирует его подлинность.

Двухстадийная оплата ​

Схема работы ​

Схема работы при подтверждении всей суммы, Humo/Uzcard (ПЦ) ​

Схема работы при частичном подтверждении суммы, Humo/Uzcard (ПЦ) ​

Схема работы при подтверждении всей суммы, Visa/MC (ПЦ) ​

Схема работы при частичном подтверждении суммы, Visa/MC (ПЦ) ​

Методы ​

prepare_payment ​

Пример запроса ​

Параметры запроса ​

Пример успешного ответа ​

Параметры успешного ответа ​

Пример неуспешного ответа ​

Параметры неуспешного ответа ​

pay ​

Пример запроса ​

Параметры запроса ​

Пример успешного ответа ​

Параметры успешного ответа ​

Пример неуспешного ответа ​

Параметры неуспешного ответа ​

verificationInfo ​

Пример успешного ответа ​

Параметры успешного ответа ​

Пример неуспешного ответа ​

Параметры неуспешного ответа ​

check_sms_key ​

Пример запроса ​

Параметры запроса ​

Пример успешного ответа ​

Параметры успешного ответа ​

Пример неуспешного ответа ​

Параметры неуспешного ответа ​

set_accept ​

Пример запроса ​

Параметры запроса ​

Пример успешного ответа ​

Параметры успешного ответа ​

Пример неуспешного ответа ​

Параметры неуспешного ответа ​

callback ​

Callback подтверждения суммы: ​

Структура ответа callback: ​

Двухстадийная оплата

Схема работы

Схема работы при подтверждении всей суммы, Humo/Uzcard (ПЦ)

Схема работы при частичном подтверждении суммы, Humo/Uzcard (ПЦ)

Схема работы при подтверждении всей суммы, Visa/MC (ПЦ)

Схема работы при частичном подтверждении суммы, Visa/MC (ПЦ)

Методы

`prepare_payment`

Пример запроса

Параметры запроса

Пример успешного ответа

Параметры успешного ответа

Пример неуспешного ответа

Параметры неуспешного ответа

`pay`

Пример запроса

Параметры запроса

Пример успешного ответа

Параметры успешного ответа

Пример неуспешного ответа

Параметры неуспешного ответа

`verificationInfo`

Пример успешного ответа

Параметры успешного ответа

Пример неуспешного ответа

Параметры неуспешного ответа

`check_sms_key`

Пример запроса

Параметры запроса

Пример успешного ответа

Параметры успешного ответа

Пример неуспешного ответа

Параметры неуспешного ответа

`set_accept`

Пример запроса

Параметры запроса

Пример успешного ответа

Параметры успешного ответа

Пример неуспешного ответа

Параметры неуспешного ответа

`callback`

Callback подтверждения суммы:

Структура ответа callback: