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

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

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

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

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

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

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

В Payment Page для проверки действительности платёжных инструментов используется отдельный режим Card Verify, при работе с которым доступны возможности указания реквизитов, получаемых от пользователей через средства связи (Mail Order / Telephone Order; MO/TO), а также возможности сохранения предоставленных реквизитов в платформе.

Базовыми действиями пользователя при выполнении проверки действительности платёжного инструмента с использованием Payment Page могут быть указание реквизитов платёжного инструмента, сохранение реквизитов для выполнения последующих платежей и ожидание уведомления о результате.



Схема работы

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

  1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page.
  2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы.

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

  • Аутентификация 3‑D Secure, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания (в то время, пока эмитент подтверждает подлинность без участия пользователя).
  • Дополнение информации о платеже, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме.

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

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

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

Формат запроса на открытие Payment Page для проверки действительности платёжного инструмента соответствует описанному в разделе Описание Payment Page API. При формировании такого запроса необходимо учитывать следующее:

  1. Должны использоваться следующие обязательные параметры:
    • mode — индикатор режима работы Payment Page, для которого необходимо передавать значение card_verify;
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_amount — сумма платежа в дробных единицах валюты, необходимо передавать значение 0;
    • payment_currency — код валюты платежа в формате ISO 4217 alpha-3;
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
  2. Для регистрации повторяемой оплаты дополнительно необходимо использовать параметр recurring со сведениями об этой повторяемой оплате (подробнее — в статье Регистрация повторяемых оплат).
  3. Для сохранения данных платёжного инструмента дополнительно необходимо использовать параметр customer_id — идентификатор пользователя, уникальный в рамках проекта.
  4. Для проведения проверки по токену инструмента необходимо использовать параметр account_token — токен, полученный от ecommpay.
  5. Для отображения пользователю платёжной формы на заданном языке дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически (по языку браузера, языку региона или по умолчанию; подробнее).
  6. Для добавления описания платежа дополнительно необходимо использовать параметр payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа.
  7. Для указания реквизитов, получаемых от пользователей через средства связи, дополнительно должен указываться параметр moto_type — со значением 1 при использовании почтовой связи (Mail Order) и 2 при использовании телефонной связи (Telephone Order).
  8. Дополнительно могут использоваться любые другие параметры, доступные при работе в режиме Card Verify. Полный список параметров вызова Payment Page представлен в разделе Параметры вызова платёжной формы.

Таким образом, корректный запрос на открытие Payment Page для проверки действительности платёжного инструмента должен содержать индикатор режима работы Payment Page, идентификаторы проекта и платежа, подпись, валюту и сумму платежа. Для сохранения данных платёжного инструмента в запросе дополнительно необходимо передать идентификатор пользователя в веб-сервисе мерчанта, а для регистрации повторяемых оплат — строку с соответствующим набором параметров.

{
   "mode": "card_verify",
   "project_id": 874,
   "payment_id": "15538406111",
   "payment_currency": "EUR",
   "payment_amount": 0,
   "signature": "TSzdE5rJpfXriFf82MxF...",

// при сохранении данных платёжного инструмента:
    "customer_id": "customer_10",

// при проведении проверки по токену карты:
   "account_token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021",

// при регистрации повторяемых оплат:
   "recurring": {
        "register": "true",
        "type": "R",
        ...
   }

}
Рис. 1. Пример запроса на открытие Payment Page
https://paymentpage.ecommpay.com/payment?payment_currency=EUR&language_code=en&mode=card_verify&project_id=874&payment_amount=0&payment_id=15538406111&css_modal_wrap=standart&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E...

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

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

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

Рис. 2. Пример данных из оповещения о результате проверки действительности платёжной карты
{
  "project_id": 874,
  "payment":{
    "id": "15538406111",
    "type": "account_verification",
    "status": "success",
    "date": "2020-06-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":{
    "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": "EUR"
    },
    "sum_converted":{
      "amount": 0,
      "currency": "EUR"
    },
    "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..."
}

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

Рис. 3. Пример данных из оповещения об отказе в проверке карты на действительность
{
  "project_id": 874,
  "payment":{
    "id": "15538406111",
    "type": "account_verification",
    "status": "decline",
    "date": "2020-06-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": 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": "EUR"
    },
    "sum_converted":{
      "amount": 0,
      "currency": "EUR"
    },
    "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..."
}