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

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

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

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

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

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

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

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

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

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

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

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



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

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

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

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

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

Таким образом, корректный запрос для проверки действительности платёжной карты пользователя должен содержать идентификаторы проекта и платежа, подпись, сведения о платёжной карте пользователя, 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=="
}