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

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

При работе с Payment Page можно выполнять проверку платёжного инструмента на возможность дальнейшего использования, например, для проведения выплат пользователям. В этом разделе представлена информация о проверке действительности платёжного инструмента с использованием Payment Page. Эта информация дополняет сведения из модели проведения платежей Модель проведения платежей.

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

Такой вариант может быть актуален, когда необходимо подтвердить подлинность конкретного платёжного инструмента без немедленного списания средств (с бесплатным пробным периодом), например перед проведением выплат пользователям или для регистрации подписок на услуги (подробная информация о регистрации повторяемых оплат представлена в разделе Регистрация повторяемых оплат). Для проверки действительности платёжных инструментов, в том числе с сохранением их данных, используется режим Card Verify.

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

Базовыми действиями пользователя при выполнении проверки действительности платёжного инструмента с использованием 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, представляющий собой строку, полученную в результате кодирования с применением алгоритма Base64, и содержащую данные о регистрации повторяемой оплаты. Подробнее — в разделе Регистрация повторяемых оплат.
  3. Для сохранения данных платёжного инструмента в запросе дополнительно необходимо использовать параметр customer_id — идентификатор пользователя, уникальный в рамках проекта.
  4. Для проведения проверки по токену инструмента необходимо использовать параметр account_token — токен, полученный от ECommPay.
  5. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом по IP-адресу пользователя: на английском (для всех стран, кроме России) или на русском (для России).
  6. Для добавления описания платежа в запросе дополнительно необходимо использовать параметр payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard (Dashboard Light), а также передаётся мерчанту в составе оповещения о результате платежа.
  7. Дополнительно могут использоваться любые другие параметры, доступные при работе в режиме Card Verify. Полный список параметров вызова Payment Page представлен в разделе Параметры открытия платежной формы 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",
        ...
   }

}

Рис.: Пример запроса на открытие Payment Page

https://paymentpage.ecommpay.com/payment?payment_currency=EUR&language_code=ru&mode=card_verify&project_id=874&payment_amount=0&payment_id=15538406111&css_modal_wrap=standart&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E...

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

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

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

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

{
  "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..."
}

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

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

{
  "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..."
}