Оплата с использованием Payment Page

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

Payment Page позволяет проводить разовые оплаты. В этом разделе рассказывается о выполнении разовой оплаты в одну стадию с использованием Payment Page, которая дополняет сведения в разделе Типы платежей, операции и платежи.

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

Payment Page позволяет проводить разовые оплаты в одну стадию с использованием платежных карт. При добавлении новой карты для проведения оплаты сохраняются ее платежные данные и формируется токен платежной карты, если это настроено для проекта мерчанта (подробнее — в разделе Создание токенов). Для выполнения этих операций используется режим работы платежной формы Purchase.

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

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

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

Схема работы

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

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

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

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

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

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

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

В запросе должны использоваться следующие обязательные параметры:
- project_id — идентификатор проекта, полученный от Rocketpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- customer_id — идентификатор пользователя, уникальный в рамках проекта;
- payment_amount — сумма платежа в дробных единицах валюты без пробелов, запятых и десятичной точки. Например, в запросе на открытие платежной формы для оплаты на сумму 100,00 KZT в параметре payment_amount следует передавать значение 10000. Количество разрядов дробных единиц для разных валют указано в справочнике Коды валют.
- payment_currency — код валюты платежа в формате ISO 4217 alpha-3;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Подписывание и проверка подписи).
Для проведения одностадийной оплаты в случае, если по запросу мерчанта в рамках проекта по умолчанию настроена блокировка средств, в запросе дополнительно необходимо использовать параметр card_operation_type со значением sale; иначе использование этого параметра не требуется.
Для предварительного выбора платежной карты в запросе дополнительно необходимо использовать параметр account_token, в котором необходимо передать токен платежной карты.
Для отображения пользователю платежной страницы на заданном языке в запросе дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платежная страница отображается на языке, определенном по IP-адресу пользователя: на английском (для всех стран, кроме России) или на русском (для России).
Для добавления описания платежа в запросе дополнительно необходимо использовать параметр payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передается мерчанту в составе оповещения о результате платежа.
Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Purchase. Полный список параметров вызова Payment Page представлен в разделе Параметры открытия платежной страницы Payment Page.

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

{
   "project_id": "42",
   "payment_id": "456789",
   "payment_currency": "KZT",
   "payment_amount": "131970",
   "customer_id": "customer_123",
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

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

}

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

https://paymentpage.rocketpay.kz/payment?payment_currency=KZT&language_code=ru&customer_id=customer_12&project_id=42&payment_amount=131970&payment_id=456789&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB...

Структура оповещений

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

В следующем примере содержится информация о том, что в рамках проекта 42 для пользователя customer_123 была проведена оплата в одну стадию в размере 1 319,70 KZT с использованием платежной карты №424242******4243.

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

{
    "account": {
        "number": "424242******4243",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_123",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 131970,
            "currency": "KZT"
        },
        "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": "KZT"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "KZT"
        },
        "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..."
}

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

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

{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 131970,
            "currency": "KZT"
        },
        "description": ""
    },
    "account": {
        "number": "424242******4243",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_123",
        "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": "KZT"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "KZT"
        },
        "provider": {
            "id": 12,
            "payment_id": "48219213050",
            "auth_code": "",
            "endpoint_id": 12
        },
        "code": "10102",
        "message": "Incorrect data entered",
        "eci": "05"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}