Проверка платёжных инструментов

Notice: Эта статья посвящена тому, как проверять действительность платёжных инструментов через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт.

Помимо этой статьи для работы с проверкой действительности могут быть полезны:

статья Проверка действительности платёжного инструмента модели проведения платежей с описанием того, как в целом проверяется действительность платёжных инструментов через платёжную платформу ecommpay и какие статусы при этом могут использоваться;
статьи раздела Платёжные методы с описанием того, как проверять действительность платёжных инструментов через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом.

Информацию о возможности проведения проверки действительности платёжного инструмента необходимо уточнять у курирующего менеджера ecommpay.

Общая информация

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

Например, это может быть актуально при регистрации подписок на товары и услуги без списания средств за первый (пробный) период или перед проведением выплат пользователям. Подробная информация о регистрации повторяемых оплат представлена в разделе Повторяемые оплаты. Также эта возможность актуальна и для так называемых оплат Mail Order/Telephone Order (MO/TO), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. Подробная информация об оплатах MO/TO представлена в разделе Проведение оплат MO/TO.

Схема проведения

Для проверки действительности платёжного инструмента через Gate со стороны веб-сервиса необходимо:

Отправить запрос к конечной точке /v2/payment/{название метода}/account_verification[/token].
При необходимости выполнить вспомогательные процедуры, инициируемые со стороны платёжной платформы. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже.
- Аутентификация 3‑D Secure. Такая аутентификация предназначена для обеспечения безопасности проведения оплаты с использованием карт через интернет. Подробная информация об этой процедуре представлена в разделе Аутентификация 3‑D Secure.
- Дополнение информации о платеже. Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе Дополнение информации о платеже.
Принять от платёжной платформы оповещение о результате проверки.

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

Рис. 1. Проверка платёжного инструмента на действительность

Пользователь на стороне веб-сервиса вводит реквизиты платёжного инструмента.
От веб-сервиса к платёжной платформе передаётся запрос на проверку действительности платёжного инструмента.
Запрос на проверку действительности поступает в платёжную платформу.
Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в платёжную среду: при работе с платёжными картами — в сервис банка, при работе с альтернативными платёжными инструментами — в платёжную систему.
Выполняется проверка действительности платёжного инструмента.
К платёжной платформе направляется уведомление о результате проверки.
От платёжной платформы к веб-сервису направляется оповещение о результате проверки.

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

Формат запросов

При формировании запросов на проверку действительности платёжных карт необходимо учитывать следующее:

POST-запрос должен отправляться к одной из следующих конечных точек:
- если проверка по номеру карты — /v2/payment/card/account_verification;
- если проверка по токену, ассоциированному с картой, — /v2/payment/card/account_verification/token.
В запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;
  - payment_id — идентификатор платежа, уникальный в рамках проекта мерчанта;
  - signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью);
- customer — объект, содержащий сведения о пользователе:
  - ip_address — используемый IP-адрес;
  - id — идентификатор пользователя в рамках проекта мерчанта;
- payment — объект, содержащий сведения о платеже:
  - amount — сумма платежа, равная нулю;
  - currency — валюта платежа в формате ISO-4217 alpha-3.
В запросе должны содержаться сведения о платёжной карте пользователя:
- при передаче реквизитов карты в явном виде — следующие данные в объекте card:
  - pan — номер карты,
  - year — год окончания срока действия карты,
  - month — месяц окончания срока действия карты,
  - card_holder — имя держателя карты (в соответствии с указанным на карте),
  - cvv — код проверки подлинности карты (в соответствии с указанным на карте); при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе Проведение оплат MO/TO;
- при передаче токена — токен, полученный от ecommpay, и код проверки подлинности карты в параметрах token и cvv (при проведении MO/TO оплат последний параметр необязателен, подробнее — в разделе Проведение оплат MO/TO).
Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Прим.: Сумма платежа должна быть равна нулю.

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

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

{
  "general":{
    "project_id":874,
    "payment_id":"15538406111",
    "signature":"1wR1YgD5PxxTIJfQ=="
  },
  "customer":{
    "ip_address":"185.123.193.224",
    "id":"customer_10"
  },
  "payment":{
    "amount":0,
    "currency":"USD"
  },

//при передаче реквизитов карты в явном виде:
  "card":{
    "pan":"4314220000000056",
    "year":2021,
    "month":9,
    "card_holder":"John Smith",
    "cvv":"123"
  },

//при передаче токена, ассоциированного с картой:
  "token":"f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654",
  "cvv":"123"


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

Формат оповещений

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

В следующем примере содержится информация о том, что в рамках проекта 874 карта 431422******0056 пользователя customer_10 действительна — может использоваться при проведении платежей — и зарегистрирована для проведения повторяемых оплат.

Рис. 3. Пример данных о результате проверки платёжной карты и регистрации повторяемой оплаты

{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"success",
    "date":"2019-09-10T13:45:59+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"EUR"
    },
    "description":"Добавить карту"
  },
  "account":{
    "number":"431422******0056",
    "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":8861226,
    "expiry_month":"09",
    "expiry_year":"2021"
  },
  "customer":{
    "id":"customer_10"
  },
  "recurring":{
    "id":10505,
    "currency":"EUR",
    "valid_thru":"2022-09-30T00:00:00+0000"
  },
  "operation":{
    "id":4314220000000056,
    "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":"EUR"
    },
    "sum_converted":{
      "amount":0,
      "currency":"EUR"
    },
    "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=="
}

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

Рис. 4. Пример данных об отказе в проверке карты на действительность

{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"decline",
    "date":"2019-09-16T06:06:53+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"EUR"
    },
    "description":"Добавить карту"
  },
  "account":{
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "expiry_month":"09",
    "expiry_year":"2021"
  },
  "customer":{
    "id":"customer_10"
  },
  "operation":{
    "id":4314220000000056,
    "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":"EUR"
    },
    "sum_converted":{
      "amount":0,
      "currency":"EUR"
    },
    "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=="
}