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

Токенизация доступна мерчантам, чей ресурс сертифицирован PCI DSS.

Токенизация - это механизм, который позволяет мерчанту один раз запросить данные карты у пользователя, а затем сохранить эти данные на защищенных ресурсах OCTO обменяв их на уникальный ключ - токен. Этот токен может быть сохранен на серверах мерчанта и связан с аккаунтом покупателя для того, чтобы все последующие покупки инициировать передавая в OCTO данный токен (не запрашивая у пользователя повторно данные карты кроме трехзначного кода безопасности cvv2/cvc2 с обратной стороны карты).

Обобщенный алгоритм оплаты с использованием токенов:

  1. Магазин инициирует создание токена методом '/bind_card' и получает ссылку для на которую надо отправить пользователя для завершения токенизации карты
  2. Магазин получает от OCTO уведомление об успешной активации токена
  3. Магазин создает платеж методом /prepare_payment) и получает от OCTO UUID платежа
  4. Магазин инициирует оплату (метод /pay) токеном с указанием созданного ранее UUID платежа и токена и получает URL на который надо перенаправить пользователя для завершения процесса 3DS.
  5. OCTO перенаправляет покупателя обратно в магазин на URL, указанный при создании платежа

Cоздание токена

Метод: POST https://secure.octo.uz/bind_card

Тело запроса:

{
"octo_shop_id": 242,
"octo_secret": "1d45df74-bb95-47cf-a616-8d6dcee2e10d",
"shop_transaction_id": "d87f4hd8d76f4h58d",
"pan" : "4276380012341025",
"exp":"2006",
“phone” : “99812341212”,
"cardHolderName" : "BOB MARLEY",
"cvc2" : "123",
"method" : "bank_card",
"return_url": "http://merchant.site.uz/return_URL",
"notify_url": "http://merchant.site.uz/send_me_status_URL",
"bind_notify_url": "http://merchant.site.uz/send_me_status_URL"
}

Описание полей запроса:

Поле Обязательное Описание
octo_shop_id да Уникальный ID магазина (доступен в ЛК магазина)
octo_secret да Персональный секретный ключ магазина, который генерируется в ЛК магазина. Должен содержаться в безопасной недоступной зоне сайта магазина
shop_transaction_id да Уникальный идентификатор транзакции на стороне магазина. Используется OCTO для предотвращения случайного дублирования транзакций
pan да 16-значный номер карты
exp да Дата истечения срока действия карты в формате YYMM
cardHolderName нет Имя держателя карты. Необязательно для карт Uzcard и HUMO, обязательно для международных карт
cvc2 нет трехзначный код безопасности с обратной стороны карты. Необязательно для карт Uzcard и HUMO, обязательно для международных карт
method да Метод оплаты (платежная система bank_card, uzcard, mir_card, humo)
return_url да Адрес на который надо вернуть покупателя после окончания процедуры верификации карты
notify_url да URL нотификаций о статусе платежа, который авторизует карту
bind_notify_url да URL нотификации о статусе токенизации

Ответ сервера:

{
"error": 0,
"status": "created",
"shop_transaction_id": "d87f4hd8d76f4h58d",
"octo_payment_UUID": "1145df74-bb95-47cf-a616-8d6dcee2e222",
"octo_pay_url": "https://pay.octo.uz/pay_wisard/1145df74-bb95-47cf-a616-8d6dcee2e222",
"card_token": "sdf9g87sd6f9g876sdf9g876sdf98g"
}

Описание полей ответа:

Поле Обязательное Описание
error да Код ошибки, 0 – нет ошибки
status да Статус авторизационного платежа
shop_transaction_id да Уникальный идентификатор транзакции на стороне магазина. Используется OCTO для предотвращения случайного дублирования транзакций
octo_payment_UUID да UUID авторизационного платежа в OCTO
octo_pay_url нет URL на который надо перенаправить пользователя для завершения авторизации (покупка с возвратом). Может отсутствовать если номер телефона phone, переданный в запросе совпал с номер телефона привязанным к карте и при этом мерчант обладает повышенным уровнем доверия
card_token нет Токен, связанный с данной картой. Этот токен можно будет использовать для процессинга платежей, до завершения авторизации токен не активен. Здесь токен передается только при максимальном уровне безопасности мерчанта в безакцептном режиме токенизации

Уведомление магазина о финальном статусе процесса токенизации карты

POST запрос отправляется со стороны OCTO на указанный адрес bind_notify_url, указанный магазином при вызове /bind_card.

Тело запроса:

{
"shop_transaction_id": "d87f4hd8d76f4h58d",
"pan" : "4276380012341025", // исходный PAN
"exp":"2006", // YYMM
"cardHolderName" : "BOB MARLEY",
"card_token": "sdf9g87sd6f9g876sdf9g876sdf98g",
"status" : "active" // (или failed)
}

OCTO ожидает в ответ HTTP status 200 и OK в теле. Если OCTO безуспешно пытается отправить уведомление мерчанту 3 раза подряд, то попытки уведомления прекращаются и токен переходит в статус failed.

Блокировка выпущенного ранее токена

Если мерчант знает, что пользователь и его данные в регистрации на стороне магазина скомпрометированы или если пользователь сам аннулировал свою регистрацию или по другим соображениям безопасности магазин обязан заблокировать выпущенный для данного пользователя токен.

Метод POST https://secure.octo.uz/block_card_token Тело запроса:

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

Ответ:

{
"error": 0,
"errorMessage": null,
“status” : "blocked"
}

Коды ошибок

  • 0 - нет ошибок
  • 1 - ошибка формата данных
  • 2 - ошибка авторизации
  • 4 - внутренняя ошибка сервиса
  • 5 – токен не найден
  • 6 – токен был не в статусе active

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

  • active - готов к оплате
  • blocked - заблокирован
  • init – в стадии авторизации карты
  • failed – неуспешная авторизация

Запуск оплаты созданного ранее платежа с использованием токена

Механизм описан в разделе Ввод карточных данных на сайте магазина