Проверка платежной карты

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

В этом разделе рассказывается, как проверить действительность платежной карты.

Чтобы инициировать проверку платежной карты, отправьте запрос в платежную платформу (пример запроса будет представлен далее). При выполнении такого запроса в платформе формируется операция account verification.

Есть два варианта проверки:

  • условный (нулевой) перевод денежных средств от пользователя на ваш счет;
  • реальная (ненулевая) блокировка средств пользователя с последующей отменой. Сумму блокировки вы можете согласовать со своим курирующим менеджером, а срок отмены блокировки может составлять до 45 дней.

В данном разделе мы рассмотрим вариант проверки карты с помощью нулевого платежа. Подробнее о блокировке средств см Оплата в две стадии.

Ограничение: Информацию о возможности проверки карт в вашем проекте уточняйте у курирующего менеджера Rocketpay.

Шаги проверки карт

Для проверки действительности карты через Gate:

  1. Отправьте запрос с нужными параметрами и подписью на рабочий URL-адрес платежной платформы Rocketpay.
  2. При необходимости выполните вспомогательные процедуры, инициируемые платежной платформой. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже:
  3. Примите от платежной платформы оповещение (callback) о результате проверки.

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



Рис.: Здесь описаны шаги проверки карты через Gate

  1. Пользователь вводит реквизиты карты в вашей системе.
  2. Ваша система передает запрос на проверку карты в Gate.
  3. Платежная платформа получает запрос.
  4. Платежная платформа проверяет наличие обязательных параметров и корректной подписи в запросе.
  5. Платежная платформа отправляет вашей системе ответ с информацией о получении запроса и о результате проверки его корректности. (Подробнее о структуре ответа см. Ответ.)
  6. Платежная платформа обрабатывает запрос и отправляет его в сервис банка.
  7. Сервис банка проверяет действительность карты.
  8. Сервис банка направляет в платежную платформу уведомление о результате проверки.
  9. Платежная платформа отправляет в вашу систему оповещение (callback) с результатом проверки.

Далее рассказывается о структуре запросов на проверку действительности платежных карт и о структуре оповещений с результатами проверки.

Запрос

Далее представлена информация, необходимая для создания и отправки запроса для проверки действительности платежной карты.

HTTP-метод запроса POST
Формат тела запроса JSON
Конечная точка
  • /v2/payment/card/account_verification — конечная точка для проверки по номеру карты;
  • /v2/payment/card/account_verification/token — конечная точка для проверки по токену, ассоциированному с картой.
Полная спецификация конечной точки
Табл. 1. Базовые параметры запроса на проверку карты

strictly required — параметр обязательно должен присутствовать в начальном запросе.
Объекты и параметры Описание

general
object
strictly required

project_id
integer
strictly required

 Идентификатор проекта, полученный от Rocketpay при интеграции.

Пример: 123

payment_id
string
strictly required

 Идентификатор платежа, уникальный в рамках проекта.

Пример: payment_47

signature
string
strictly required

 Подпись запроса, составленная после определения всех параметров запроса. Подробнее о составлении подписи см. Использование подписи к данным.

customer
object
strictly required

id
string
strictly required

 Идентификатор пользователя, уникальный в рамках проекта.

Пример: customer_123

ip_address
string
strictly required

 IP-адрес устройства пользователя.

Пример: 198.51.100.47

email
string
strictly required

 Адрес электронной почты пользователя.

Пример: johndoe@example.com

first_name
string
strictly required

 Имя пользователя.

Пример: John

last_name
string
strictly required

 Фамилия пользователя.

Пример: Doe

payment
object
strictly required

amount
integer
strictly required

 Сумма оплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют.

Пример: 100,00 USD передается как 10000

Ограничение: Для проверки карты сумма платежа должна быть равна нулю.

currency
string
strictly required

 Код валюты оплаты в формате ISO-4217 alpha-3.

Пример: USD
Сведения о платежной карте пользователя при передаче реквизитов карты в явном виде:

card
object
strictly required

pan
string
strictly required

 Номер карты.

Пример: 1122334455667788

year
integer
strictly required

 Год окончания срока действия карты.

Пример: 2025

month
integer
strictly required

 Месяц окончания срока действия карты.

Пример: 8

card_holder
string
strictly required

 Имя держателя карты (в соответствии с указанным на карте).

Пример: JOHN DOE

cvv
string
strictly required

 Код проверки подлинности карты (в соответствии с указанным на карте).

Пример: 123
Сведения о платежной карте пользователя при передаче токена:

token
string
strictly required

 Токен банковской карты пользователя. Токен представляет собой уникальную последовательность из 64 символов, связанную с банковской картой.

Пример: f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654

Подробнее см. Использование токенов

cvv
string
strictly required

 Код проверки подлинности карты (в соответствии с указанным на карте).

Пример: 123
Для регистрации повторяемой оплаты

recurring
object
strictly required

register
boolean
strictly required

 Признак регистрации повторяемой оплаты.

Пример: true
В объекте recurring также могут использоваться и другие параметры. Подробнее о регистрации повторяемой оплаты см. Повторяемая оплата.
При необходимости добавьте в запрос необязательные параметры, указанные в спецификации Gate: API Reference.

Рис.: Пример тела запроса на проверку карты

{
  "general":{
    "project_id":123,
    "payment_id":"payment_47",
    "signature":"1wR1YgD5PxxTIJfQ=="
  },
  "customer":{
    "ip_address":"185.123.193.224",
    "id":"customer_123"
  },
  "payment":{
    "amount":0,
    "currency":"USD"
  },

//при передаче реквизитов карты в явном виде:
  "card":{
    "pan":"1122334455667788",
    "year":2025,
    "month":8,
    "card_holder":"John Doe",
    "cvv":"123"
  },

//при передаче токена:
  "token":"f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654",
  "cvv":"123"

//при необходимости зарегистрировать повторяемую оплату:
  "recurring":{
    "register":true
  }
}

Оповещение (callback)

Результат проверки платежной карты платежная платформа возвращает в оповещении. Подробнее о структуре оповещений см. Оповещения (callbacks) в Gate.

Вот пример тела оповещения с информацией о том, что в рамках проекта 123 карта 112233******7788 пользователя customer_123 действительна и зарегистрирована для повторяемой оплаты.

Рис.: Пример тела оповещения о том, что карта успешно прошла проверку

{
  "project_id":123,
  "payment":{
    "id":"payment_47",
    "type":"account_verification",
    "status":"success",
    "date":"2019-09-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":{
    "id":10505,
    "currency":"USD",
    "valid_thru":"2022-09-30T00:00:00+0000"
  },
  "operation":{
    "id":42209000002431,
    "type":"account verification",
    "status":"success",
    "date":"2019-09-10T13:45:59+0000",
    "created_date":"2019-09-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":"2019-09-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":"2019-09-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":"2019-09-16T06:06:53+0000",
    "created_date":"2019-09-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":"2019-09-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 в параметре 3ds_result. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, то платеж будет отклонен и переведен в статус decline.

Промежуточное состояние
awaiting clarification Проведение платежа приостановлено. Платежная платформа ожидает от вас запрос с недостающей информацией. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, платеж будет отклонен и переведен в статус decline.

Промежуточное состояние
decline Платеж отклонен.

Конечное состояние
success Платеж проведен.

Конечное состояние

Статусы операции account verification

Следующие статусы могут быть назначены операции account verification.

Статус операции Описание
processing Операция выполняется.

Промежуточное состояние
awaiting 3ds result Выполнение операции приостановлено. Платежная платформа ожидает от вас запрос с информацией о результате аутентификации 3‑D Secure в параметре 3ds_result. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, операция будет отклонена и переведена в статус decline.

Промежуточное состояние
awaiting clarification Выполнение операции приостановлено. Платежная платформа ожидает от вас запрос с недостающей информацией. Если такой запрос не поступит от вас в платежную платформу в течение 30 минут, операция будет отклонена и переведена в статус decline.

Промежуточное состояние
decline Операция отклонена.

Конечное состояние
success Операция выполнена.

Конечное состояние

Ссылки по теме