Проведение оплат

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

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

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

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

Разовая оплата в одну стадию, или разовая одностадийная оплата — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один (разовый) перевод денежных средств от пользователя к мерчанту. Операция возврата средств пользователю в рамках разовой одностадийной оплаты осуществляется с помощью интерфейсов Gate или Dashboard.

С помощью Payment Page можно проводить разовые оплаты в одну стадию с использованием платёжных карт или других платёжных инструментов, в том числе оплаты Mail Order/Telephone Order (MO/TO), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. При добавлении новой карты для проведения оплаты сохраняются её платёжные данные и формируется токен платёжной карты, если это настроено для проекта мерчанта (подробнее — в разделе Формирование токенов). Для выполнения этих операций используется режим работы платёжной формы Purchase.

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



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

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

    В дополнение к выбранным реквизитам для некоторых инструментов требуется подтверждение, такое как ввод проверочного кода (CVC, CVV, CID) при работе с платёжными картами.

  • Через выбор до вызова формы. В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты, и платёжная форма открывается с указанием всех реквизитов кроме проверочного кода (CVC, CVV, CID), который необходимо указать непосредственно на форме.


Payment Page при разных способах указания платёжных данных: при заполнении через ввод на форме, выборе из уже сохранённых данных и выборе конкретной карты до вызова формы, соответственно.

Схема работы

Для проведения оплаты с помощью Payment Page со стороны веб-сервиса необходимо:

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

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

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

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

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

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

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

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

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

{
   "project_id": "42",
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": "131970",
   "customer_id": "customer_12",
   "customer_phone": "44991234567",
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

// при проведении оплаты по предварительно выбранной карте:
    "account_token":"959c664ad6045679d71d89caff6c242a0..."

}
Рис. 1. Пример запроса на открытие Payment Page
https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&customer_id=customer_12&customer_phone=44991234567&project_id=42&payment_amount=131970&payment_id=456789&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB...

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

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

В следующем примере содержится информация о том, что в рамках проекта 42 для пользователя customer_12 была проведена оплата в одну стадию в размере 1 319,70 USD с использованием платёжной карты 431422******0056.

Рис. 2. Пример данных из оповещения о проведённой оплате в одну стадию
{
    "account": {
        "number": "431422****0056",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 131970,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2019-01-11T13:02:42+0000",
        "created_date": "2019-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 131970,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2019-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

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

Рис. 3. Пример данных из оповещения об отказе в проведении оплаты в одну стадию
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 131970,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "431422****0056",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 13300000004505,
        "type": "sale",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "created_date": "2019-01-11T14:11:00+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 131970,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "USD"
        },
        "provider": {
            "id": 12,
            "payment_id": "48219213050",
            "auth_code": "",
            "endpoint_id": 12
        },
        "code": "10102",
        "message": "Incorrect data entered",
        "eci": "05"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}