Проверка платежной карты
Проверка действительности платежной карты нужна, чтобы узнать, может ли карта использоваться для проведения платежей. Это может быть актуально перед проведением выплаты пользователю или при регистрации подписки на товары и услуги без списания средств за первый (пробный) период. Подробнее о регистрации повторяемой оплаты см. Регистрация повторяемой оплаты.
В этом разделе рассказывается, как проверить действительность платежной карты с использованием Payment Page.
Чтобы инициировать проверку карты, в параметрах запроса на вызов платежной формы (пример запроса будет представлен далее) укажите режим работы card_verify. После этого пользователь должен подтвердить свое согласие на проверку. Далее ваша система направляет в платежную платформу запрос, для выполнения которого в платформе формируется операция account verification.
Есть два варианта проверки:
- условный (нулевой) перевод денежных средств от пользователя на ваш счет;
- реальная (ненулевая) блокировка средств пользователя с последующей отменой. Сумму блокировки вы можете согласовать со своим курирующим менеджером, а срок отмены блокировки может составлять до 45 дней.
В данном разделе мы рассмотрим вариант проверки карты с помощью нулевого платежа. Подробнее о блокировке средств см. Блокировка средств.
В процессе проверки карты Payment Page может потребовать от пользователя указать реквизиты карты, сохранить реквизиты карты для последующих платежей и/или подождать уведомления о результате проверки.
Шаги проверки карт
Для проверки действительности карты через Payment Page:
- Сформируйте и отправьте в платежную платформу запрос на открытие Payment Page.
- При необходимости выполните вспомогательные процедуры, инициируемые платежной платформой. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже:
- Аутентификация 3‑D Secure Такая аутентификация предназначена для обеспечения безопасности оплаты с использованием карт через интернет. Подробнее об этой процедуре см. Аутентификация по протоколу 3‑D Secure 2.
- Дополнение информации о платеже Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе Дополнение информации о платеже.
- Примите от платежной платформы оповещение (callback) о результате проверки.
Далее рассказывается о структуре запросов на проверку действительности платежных карт и о структуре оповещений с результатами проверки.
Запрос
В запросе на открытие Payment Page для проверки действительности карты укажите необходимые параметры:
|
||
|---|---|---|
| Параметр | Описание | |
|
mode |
Режим работы Payment Page. Для проверки карты укажите в этом параметре значение Пример: |
|
|
project_id |
Идентификатор проекта, полученный от Rocketpay при интеграции. Пример: |
|
|
payment_id |
Идентификатор платежа, уникальный в рамках проекта. Пример: |
|
|
customer_id |
Идентификатор пользователя, уникальный в рамках проекта. Пример: |
|
|
customer_first_name |
Имя пользователя. Пример: |
|
|
customer_last_name |
Фамилия пользователя. Пример: |
|
|
customer_email |
Адрес электронной почты пользователя. Пример: |
|
|
payment_currency |
Код валюты оплаты в формате ISO-4217 alpha-3. Пример: |
|
|
payment_amount |
Сумма оплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют. Пример: 100,00 USD передается как Ограничение: Для проверки карты сумма платежа должна быть равна нулю.
|
|
|
signature |
Подпись запроса, составленная после определения всех параметров запроса. Подробнее о составлении подписи см. Подписывание и проверка подписи. | |
| Для проверки платежной карты по токену: | ||
|
account_token |
Токен банковской карты пользователя. Токен представляет собой уникальную последовательность из 64 символов, связанную с банковской картой. Пример: Ограничение: Применяется в режимах Purchase и Card Verify.
Подробнее см. Создание токенов |
|
| Для регистрации повторяемой оплаты | ||
|
recurring |
Строка, содержащая в закодированном виде параметры регистрации и проведения COF-платежа. Данные собираются в JSON-объект и кодируются в URL-encoded. Структура JSON-объекта приведена в спецификации API в схеме recurringinfo. Подробнее см. Регистрация повторяемой оплаты |
|
| При необходимости добавьте в запрос необязательные параметры из числа доступных для работы с Payment Page. Подробнее о параметрах запросов в Payment Page см. Параметры открытия платежной страницы Payment Page. | ||
Вот пример параметров из запроса на открытие Payment Page с использованием виджета EPayWidget:
EPayWidget.run(
{
"mode": "card_verify",
"project_id": "123",
"payment_id": "payment_47",
"payment_currency": "USD",
"payment_amount": "0",
"signature": "TSzdE5rJpfXriFf82MxF..."
// При сохранении данных платежной карты:
"customer_id": "customer_123"
// При проведении проверки по токену карты:
"account_token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021"
// При регистрации повторяемой оплаты:
"recurring": {
"register": "true",
"type": "R",
...
}
}
)
Пример GET-запроса на открытие Payment Page:
https://paymentpage.rocketpay.kz/payment?language_code=ru&mode=card_verify&project_id=123&payment_amount=0&payment_currency=USD&payment_id=15538406111&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E...
Оповещение (callback)
Результат проверки платежной карты платежная платформа возвращает в оповещении. Подробнее о структуре оповещений см. Оповещения (callbacks) в Payment Page.
Вот пример тела оповещения с информацией о том, что платежная карта 112233******7788 пользователя customer_123 действительна и зарегистрирована для повторяемой оплаты.
Рис.: Пример тела оповещения о том, что карта успешно прошла проверку
{
"project_id":123,
"payment":{
"id":"payment_47",
"type":"account_verification",
"status":"success",
"date":"2020-06-10T13:45:59+0000",
"method":"card",
"sum":{
"amount":0,
"currency":"USD"
},
"description":"Добавить карту"
},
"account":{
"number":"112233******7788",
"token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
"type":"visa",
"card_holder":"JOHN DOE",
"id":8861226,
"expiry_month":"08",
"expiry_year":"2025"
},
"customer":{
"id":"customer_123"
},
"recurring":{
"register":"true",
"type":"R"
},
"operation":{
"id":42209000002431,
"type":"account verification",
"status":"success",
"date":"2020-06-10T13:45:59+0000",
"created_date":"2020-06-10T13:45:57+0000",
"request_id":"5cb898347e62b2c1-52dac6c8c",
"sum_initial":{
"amount":0,
"currency":"USD"
},
"sum_converted":{
"amount":0,
"currency":"USD"
},
"provider":{
"id":120,
"payment_id":"306449667",
"date":"2020-06-10T13:45:59+0000",
"auth_code":"188591",
"endpoint_id":120
},
"code":"0",
"message":"Success"
},
"signature":"P9g0U+eF2QWs2A..."
}
Если карта не прошла проверку, платежная платформа отправит вам оповещение с информацией о том, что проведение платежа было отклонено.
Рис.: Пример тела оповещения о том, что карта не прошла проверку
{
"project_id":123,
"payment":{
"id":"payment_47",
"type":"account_verification",
"status":"decline",
"date":"2020-06-16T06:06:53+0000",
"method":"card",
"sum":{
"amount":0,
"currency":"USD"
},
"description":"Добавить карту"
},
"account":{
"number":"112233******7788",
"type":"visa",
"card_holder":"JOHN DOE",
"expiry_month":"08",
"expiry_year":"2025"
},
"customer":{
"id":"customer_123"
},
"operation":{
"id":40975000002863,
"type":"account verification",
"status":"decline",
"date":"2020-06-16T06:06:53+0000",
"created_date":"2020-06-16T06:06:47+0000",
"request_id":"9120271eb02-83e0e70fc0a0a3c1b4d",
"sum_initial":{
"amount":0,
"currency":"USD"
},
"sum_converted":{
"amount":0,
"currency":"USD"
},
"provider":{
"id":120,
"payment_id":"308822001",
"date":"2020-06-16T06:06:49+0000",
"auth_code":"",
"endpoint_id":120
},
"code":"10100",
"message":"Declined by external provider"
},
"signature":"P9g0U+eaZ9EeNiWiaQWs2A..."
}
Статусы платежа
В данном разделе представлена информация о возможных статусах платежа и связанных с ним операций.
Рис.: Диаграмма состояний платежа
В процессе проверки карты платежу могут присваиваться следующие статусы.
| Статус платежа | Описание |
|---|---|
error |
При проверке принятого в платежной платформе запроса возникла ошибка, и проведение платежа не было инициировано. Конечное состояние. Допускается повторное инициирование этого платежа |
processing |
Платеж проводится. Промежуточное состояние |
awaiting 3ds result |
Проведение платежа приостановлено. Платежная платформа ожидает от вас запрос с информацией о результате аутентификации 3‑D Secure. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, платеж будет переведен в статус decline.Промежуточное состояние |
awaiting clarification |
Проведение платежа приостановлено. Платежная платформа ожидает от вас запрос с недостающей информацией. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, платеж будет переведен в статус decline.Промежуточное состояние |
decline |
Платеж отклонен. Конечное состояние |
success |
Платеж проведен. Конечное состояние |
Статусы операции Account verification
Следующие статусы могут быть назначены операции account verification.
| Статус | Значение статуса |
|---|---|
processing |
Операция выполняется. Промежуточное состояние |
awaiting 3ds result |
Выполнение операции приостановлено. Платежная платформа ожидает от вас запрос с информацией о результате аутентификации 3‑D Secure. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, операция будет переведена в статус decline.Промежуточное состояние |
awaiting clarification |
Выполнение операции приостановлено. Платежная платформа ожидает от вас запрос с недостающей информацией. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, операция будет переведена в статус decline.Промежуточное состояние |
decline |
Операция отклонена. Конечное состояние |
success |
Операция выполнена. Конечное состояние |