Токенизация банковских карт

Токенизация – это механизм, позволяющий Партнёру один раз запросить данные карты у пользователя и сохранить их в защищённой среде OCTO, обменяв на уникальный токен. Этот токен может быть сохранён на серверах Партнёра и связан с аккаунтом покупателя. Последующие покупки инициируются передачей токена в OCTO, запрашивая только код CVV2/CVC2.

Важно!

Отправка уведомления о финальном статусе токенизации карты, производится посредством POST запроса со стороны ПС OCTO (callback) на адрес, указанный Партнёром в параметре bind_notify_url, в методе bind_card

Блокировка токена карты.

Для блокировки выпущенного токена банковской карты, необходимо с сервера Партнёра отправить запрос /block_card_token

Алгоритм токенизации Humo/Uzcard

Клиент инициирует токенизацию карты.
Партнёр вызывает метод привязки карт bind_card.
Наш BE отправляет запрос в Humo/Uzcard для проверки данных карты.
Humo/Uzcard подтверждает данные.
Наш BE подтверждает Партнёру.
Партнёр вызывает метод получения срока действия OTP verificationInfo.
Наш BE подтверждает запрос Партнёра.
Humo/Uzcard отправляет OTP код клиенту.
Клиент передаёт OTP код Партнёру.
Партнёр вызывает метод проверки кода /bind_card/check_sms.
Наш BE отправляет код в Humo/Uzcard.
Humo/Uzcard подтверждает списание.
Наш BE уведомляет Партнёра.
Наш BE отправляет запрос на возврат средств в Humo/Uzcard.
Humo/Uzcard подтверждает возврат.
Наш BE отправляет callback о статусе Партнёру.
Наш BE отправляет токен Партнёру.
Партнёр отправляет подтверждение получения.*

Примечание

Если Партнёр не отправит подтверждение получения, наш BE отправит повторные запросы до трёх раз. При отсутствии ответа токен аннулируется.

*BE - Back End

Логотип

Токенизация Humo/Uzcard

Алгоритм токенизации Visa/MC

Клиент инициирует токенизацию карты.
Партнёр вызывает метод привязки карт bind_card.
Наш BE отправляет запрос в Visa/MC для проверки данных карты и тестового списания средств.
Visa/MC подтверждает данные и отправляет ссылку на форму ввода OTP.
Visa/MC отправляет OTP код клиенту.
Клиент отправляет OTP код.
Visa/MC подтверждает списание.
Наш BE уведомляет Партнёра.
Наш BE отправляет запрос на возврат средств в Visa/MC.
Visa/MC подтверждает возврат.
Наш BE отправляет callback о статусе Партнёру.
Наш BE отправляет токен Партнёру.
Партнёр отправляет подтверждение получения.

Примечание

*BE - Back End

Логотип

Токенизация Visa/MC

Методы

`/bind_card`

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

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

json

{
    "octo_shop_id": "{{merchant_id}}",
    "octo_secret": "{{merchant_secret}}",
    "shop_transaction_id": "{{$randomUUID}}",
    "pan": "9860240101226506",
    "exp": "2805",
    "phone": "998901234567",
    "cardHolderName": "Card Holder Name",
    "cvc2": "",
    "method": "humo",
    "return_url": "https://notify-url.uz",
    "notify_url": "https://notify-url.uz",
    "bind_notify_url": "https://notify-url.uz"
}

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

Параметр	Тип	Обязательность	Описание
octo_shop_id	Integer	Да	Уникальный ID магазина, доступный в личном кабинете (ЛК).
octo_secret	String	Да	Персональный секретный ключ магазина, генерируемый в ЛК.
shop_transaction_id	String	Да	Уникальный идентификатор транзакции на стороне магазина.
pan	String	Да	Номер карты клиента.
exp	String	Да	Срок действия карты в формате ГГММ.
phone	String	Да	Номер телефона клиента, связанный с картой.
method	String	Да	Метод оплаты. Возможные значения: humo, uzcard, bank_card.
cvc2	String	Нет	Код безопасности карты (CVC2).
return_url	String	Да	URL для перенаправления пользователя после завершения оплаты.
notify_url	String	Нет	URL для уведомлений о статусе платежа.
bind_notify_url	String	Нет	URL для уведомлений при успешной привязке карты.

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

json

{
    "error": 0,
    "data": {
        "shop_transaction_id": "123431321323334132333",
        "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
        "status": "created",
        "octo_pay_url": "https://pay-dev.octo.uz/uzcard/sms/06000144-db56-47b6-9eba-021ad4ff246b",
        "refunded_sum": 0,
        "total_sum": 1000
    },
    "apiMessageForDevelopers": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов."
}

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

Параметр	Тип	Обязательность	Описание
error	Integer	Да	Код ошибки. `0` указывает на успешную операцию.
data	Object	Да	Основной объект с информацией о транзакции.
shop_transaction_id	String	Да	Уникальный идентификатор транзакции на стороне магазина.
octo_payment_UUID	String	Да	Уникальный идентификатор платежа в системе Octo.
status	String	Да	Статус платежа. Возможные значения: created, succeeded, failed и др.
octo_pay_url	String	Да	Ссылка на платежную страницу для проведения оплаты.
refunded_sum	Number	Да	Сумма возврата. По умолчанию `0`, если возврат не проводился.
total_sum	Number	Да	Общая сумма транзакции.
apiMessageForDevelopers	String	Нет	Сообщение для разработчиков о возможных изменениях в API.

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

json

{
    "error": 20,
    "errMessage": "Active or pending token already exists",
    "data": null,
    "errorMessage": "Active or pending token already exists",
    "apiMessageForDevelopers": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов."
}

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

`/bind_card/check_sms_key`

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

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

json

{
    "octo_shop_id": "{{merchant_id}}",
    "octo_secret": "{{merchant_secret}}",
    "smsKey": "61135",
    "paymentUUID": "{{bind_octo_payment_UUID}}",
    "verifyId": "{{bind_verifyId}}"
}

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

Параметр	Тип	Обязательность	Описание
octo_shop_id	Integer	Да	Уникальный ID магазина (доступен в личном кабинете).
octo_secret	String	Да	Персональный секретный ключ магазина.
smsKey	String	Да	SMS-код, отправленный на телефон клиента, связанный с картой.
paymentUUID	String	Да	Уникальный идентификатор транзакции привязки карты.
verifyId	Integer	Да	Идентификатор для подтверждения привязки карты.

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

json

{
  "error": 0,
  "data": {
    "shop_transaction_id": "123431321323334132333",
    "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
    "status": "succeeded",
    "octo_pay_url": "https://pay-dev.octo.uz/status/06000144-db56-47b6-9eba-021ad4ff246b",
    "processor_key": "023205044087",
    "processing_reference": "1735210612392_71229",
    "transfer_sum": 980.0000,
    "refunded_sum": 1000.00,
    "total_sum": 1000.00,
    "payed_time": "2024-12-26 15:56:52",
    "first6": "860050",
    "last4": "2744"
  },
  "apiMessageForDevelopers": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов. Так же пожалуйста знайте, что в дальнейшем все поля кроме error и errMessage будут передаваться в data. Для более подробного ознакомление свяжитесь с технической поддержкой сервиса",
  "shop_transaction_id": "123431321323334132333",
  "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
  "status": "succeeded",
  "octo_pay_url": "https://pay-dev.octo.uz/status/06000144-db56-47b6-9eba-021ad4ff246b",
  "processor_key": "023205044087",
  "processing_reference": "1735210612392_71229",
  "transfer_sum": 980.0000,
  "refunded_sum": 1000.00,
  "total_sum": 1000.00,
  "payed_time": "2024-12-26 15:56:52"
}

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

Параметр	Тип	Обязательность	Описание
`error`	Integer	Да	Код ошибки. Значение 0 указывает на успешное выполнение операции.
`data`	Object	Да	Данные ответа, содержащие детали платежа.
`shop_transaction_id`	String	Да	Уникальный идентификатор транзакции на стороне магазина.
`octo_payment_UUID`	String	Да	Уникальный идентификатор платежа, созданный системой OCTO.
`status`	String	Да	Текущий статус платежа (`succeeded`, `failed`, `created` и т.д.).
`octo_pay_url`	String	Да	URL для проверки или получения статуса платежа.
`processor_key`	String	Нет	Уникальный ключ процессора для идентификации транзакции.
`processing_reference`	String	Нет	Референс транзакции в системе обработки платежей.
`transfer_sum`	Decimal	Нет	Сумма, перечисленная получателю после вычета комиссий.
`refunded_sum`	Decimal	Нет	Сумма, которая была возвращена пользователю в результате возврата.
`total_sum`	Decimal	Да	Полная сумма транзакции.
`payed_time`	String	Нет	Дата и время завершения оплаты в формате `YYYY-MM-DD HH:MM:SS`.
`first6`	String	Нет	Первые 6 цифр номера карты, использованной для платежа.
`last4`	String	Нет	Последние 4 цифры номера карты, использованной для платежа.
`apiMessageForDevelopers`	String	Нет	Сообщение для разработчиков, содержащее дополнительные детали или уведомления о будущем изменении API.

Пример ошибки сервера

json

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Cannot invoke \"com.octo.uzcard.dto.CardInfo.getCardtype()\" because the return value of \"com.octo.uzcard.dto.CardNewVerifyResponse.getResult()\" is null"
}

`callback`

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

json

{
    "shop_transaction_id": "d87f4hd8d76f4h58d",
    "pan": "4276380012341025",
    "exp": "2006",
    "cardHolderName": "BOB MARLEY",
    "card_token": "sdf9g87sd6f9g876sdf9g876sdf98g",
    "status": "active"
}

Параметров запроса `callback`

Параметр	Тип	Обязательность	Описание
`shop_transaction_id`	String	Да	Уникальный идентификатор транзакции в магазине.
`pan`	String	Да	Исходный PAN (номер карты).
`exp`	String	Да	Дата истечения срока действия карты в формате `YYMM`.
`cardHolderName`	String	Да	Имя держателя карты.
`card_token`	String	Да	Токен карты, полученный после привязки.
`status`	String	Да	Статус карты: `active` (успешно привязана) или `failed` (привязка не удалась).

Ожидаемый ответ - HTTP статус: `200`

Важно!

Если ответ успешный, система OCTO считает, что запрос обработан.
Если ответ неуспешный, система OCTO повторит запрос до трёх раз.
Если после трёх попыток успешный ответ не будет получен, OCTO прекратит отправку запросов и аннулирует токен.

Пример успешного ответа - HTTP статус: `200`

json

{
    "status": "success",
    "message": "Callback processed successfully"
}

Пример неуспешного ответа - HTTP статус: `400` и выше

json

{
    "status": "error",
    "message": "Invalid shop_transaction_id"
}

`block_card_token`

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

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

json

{
    "octo_shop_id": 242,
    "octo_secret": "1d45df74-bb95-47cf-a616-8d6dcee2e10d",
    "card_token": "sdf9g87sd6f9g876sdf9g876sdf98g"
}

Описание параметров тела запроса:

Параметр	Тип	Обязательность	Описание
`octo_shop_id`	Integer	Да	Уникальный идентификатор магазина в системе Octo.
`octo_secret`	String	Да	Секретный ключ для аутентификации запросов.
`card_token`	String	Да	Токен карты, используемый для проведения платежа.

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

json

{
    "error": 0,
    "errMessage": null,
    "status": "blocked"
}

Описание параметров ответа:

Параметр	Тип	Обязательность	Описание
`error`	Integer	Да	Код ошибки. `0` указывает на отсутствие ошибок.
`errMessage`	String	Нет	Сообщение об ошибке, если таковая имеется.
`status`	String	Да	Статус операции. Например, `blocked`.

Возможные коды ошибок

Код	Описание
`0`	Нет ошибок.
`1`	Ошибка формата данных.
`2`	Ошибка авторизации.
`4`	Внутренняя ошибка сервиса.
`5`	Токен не найден.
`6`	Токен был не в статусе `active`.

Возможные статусы токена

Статус	Описание
`active`	Готов к оплате.
`blocked`	Заблокирован.
`init`	В стадии авторизации карты.
`failed`	Неуспешная авторизация.

Оплата через платежную страницу OCTO

Оплата через сайт Партнёра

Проведение транзакций

Токенизация банковских карт

Алгоритм токенизации Humo/Uzcard

Алгоритм токенизации Visa/MC

Методы

`/bind_card`

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

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

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

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

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

`verificationInfo`

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

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

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

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

`/bind_card/check_sms_key`

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

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

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

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

Пример ошибки сервера

`callback`

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

Параметров запроса `callback`

Ожидаемый ответ - HTTP статус: `200`

Пример успешного ответа - HTTP статус: `200`

Пример неуспешного ответа - HTTP статус: `400` и выше

`block_card_token`

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

Описание параметров тела запроса:

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

Описание параметров ответа:

Возможные коды ошибок

Возможные статусы токена

Токенизация банковских карт ​

Алгоритм токенизации Humo/Uzcard ​

Алгоритм токенизации Visa/MC ​

Методы ​

/bind_card ​

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

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

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

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

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

verificationInfo ​

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

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

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

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

/bind_card/check_sms_key ​

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

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

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

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

Пример ошибки сервера ​

callback ​

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

Параметров запроса callback ​

Ожидаемый ответ - HTTP статус: 200 ​

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

Пример неуспешного ответа - HTTP статус: 400 и выше ​

block_card_token ​

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

Описание параметров тела запроса: ​

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

Описание параметров ответа: ​

Возможные коды ошибок ​

Возможные статусы токена ​

Токенизация банковских карт

Алгоритм токенизации Humo/Uzcard

Алгоритм токенизации Visa/MC

Методы

`/bind_card`

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

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

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

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

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

`verificationInfo`

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

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

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

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

`/bind_card/check_sms_key`

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

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

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

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

Пример ошибки сервера

`callback`

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

Параметров запроса `callback`

Ожидаемый ответ - HTTP статус: `200`

Пример успешного ответа - HTTP статус: `200`

Пример неуспешного ответа - HTTP статус: `400` и выше

`block_card_token`

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

Описание параметров тела запроса:

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

Описание параметров ответа:

Возможные коды ошибок

Возможные статусы токена