Оповещения (callbacks) в Payment Page

Оповещение (callback) — это техническое сообщение, которое платежная платформа Rocketpay отправляет на заданный URL-адрес мерчанта, чтобы сообщить определенную информацию, например результат выполнения платежа.

Как выглядит оповещение в Rocketpay

Оповещение представляет собой HTTP-запрос, отправляемый методом POST на URL-адрес, который вы предоставляете Rocketpay в процессе интеграции.

Параметры оповещения передаются в теле запроса в формате JSON, при этом массив параметров преобразуется в одну строку. Вы можете настраивать, какие параметры должны передаваться в теле запроса. Для этого обращайтесь в службу поддержки Rocketpay.

Вот пример данных из тела оповещения типового формата. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "mobile",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Ниже приведен пример данных из тела оповещения, настроенного индивидуально под потребности мерчанта.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "mobile",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": ""
    },
    "customer": {            // объект с расширенной информацией о пользователе
        "id": "customer_123",
        "email": "johndoe@example.com",
        "phone": "491234567890",
        "first_name": "John",
        "last_name": "Doe"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Оповещения от Rocketpay содержат подпись. Подробнее о том, как проверить подпись в оповещении, см. раздел Подписывание и проверка подписи.

Когда Rocketpay отправляет оповещения

Платежная платформа отправляет вашей системе оповещения, когда:

• изменяется статус платежа. Это может быть связано, например, с перенаправлением пользователя, отображением пользователю инструкции для оплаты, прохождением процедуры аутентификации 3-D Secure пользователем, запросом у пользователя данных, недостающих для проведения платежа и т. д. Подробнее о статусах различных операций см. раздел Типы платежей, операции и платежи.

  Если вы проводите платежи с использованием Payment Page, данные оповещения для вас несут информационный характер. Ваша система должна отвечать на них кодом состояния HTTP 200 OK и не выполнять других действий. Вы можете отказаться от получения этих оповещений, если необходимо. Для этого обращайтесь в службу поддержки Rocketpay;

• создан, удален или истек токен для банковской карты. Пример такого оповещения см. в разделе Оповещение (callback);
• завершена обработка операции в платежной платформе.

Адреса для приема оповещений

Оповещения отправляются на URL-адрес, который вы предоставляете Rocketpay в процессе интеграции. Если у вас есть несколько проектов, вы можете предоставить для каждого проекта отдельный URL-адрес, на который Rocketpay будет отправлять оповещения.

Вы можете предоставить Rocketpay отдельные URL-адреса, чтобы получать оповещения с определенной информацией по платежу. Например, чтобы оповещения об успешном завершении платежа платежная платформа отправляла на один адрес, а об отклонении — на другой. Вы также можете использовать отдельный URL-адрес для получения оповещений по платежам определенного типа или платежам, проведенным с использованием конкретного платежного метода.

Вы можете самостоятельно указать дополнительные адреса для приема оповещений в Dashboard. Для этого в Dashboard перейдите в раздел Проекты и выберите вкладку Оповещения. Инструменты в Dashboard позволят вам определить, в каких случаях и на какие адреса Rocketpay будет отправлять вашей системе оповещения. Подробнее о том, как задать адреса для отправки оповещений в Dashboard, см. раздел Правила отправки оповещений.

Обратите внимание, что ваша система должна принимать оповещения только с IP-адреса, полученного от команды интеграции Rocketpay. Чтобы уточнить IP-адрес, с которого Rocketpay отправляет оповещения, обратитесь в службу поддержки Rocketpay.

Адреса для приема оповещений по конкретному платежу

Вы можете указать отдельный URL-адрес для приема оповещений по конкретному платежу. Для этого добавьте в запрос на открытие страницы оплаты параметр merchant_callback_url и задайте в качестве значения URL-адрес, на который Rocketpay будет отправлять оповещения. После этого все оповещения по этому платежу (и только по нему) будут отправляться на указанный URL-адрес независимо от того, какой URL-адрес для приема оповещений задан для вашего проекта.

Вы также можете указать в запросе параметры с URL-адресами, на которые Rocketpay будет отправлять оповещения с результатом конкретного платежа:

• merchant_success_callback_url — URL-адрес, на который Rocketpay отправит callback-оповещение о результате платежа, если он будет успешно проведен;
• merchant_decline_callback_url — URL-адрес, на который Rocketpay отправит callback-оповещение о результате платежа, если он будет отклонен.

Эти параметры приоритетнее параметра merchant_callback_url и URL-адреса, указанного в настройках вашего проекта. Так, если задать значения обоих параметров — merchant_callback_url и merchant_success_callback_url, то в случае успеха Rocketpay отправит оповещение с результатом платежа на URL-адрес, указанный в merchant_success_callback_url, игнорируя как параметр merchant_callback_url, так и URL-адрес, указанный для вашего проекте в платежной платформе. Аналогичная ситуация с параметром merchant_decline_callback_url , но с поправкой на то, что речь идет об итоговом оповещении об отклонении платежа.

EPayWidget.run(
    {
        project_id: 1234,
        payment_id: 'payment_47',
        customer_id: 'customer_123',
        customer_first_name: 'John',
        customer_last_name: 'Doe',
        customer_email: 'johndoe@example.com',
        merchant_callback_url: 'http://example.com/callback/default',
        merchant_success_callback_url: 'http://example.com/success',
        merchant_decline_callback_url: 'http://example.com/decline',
        payment_currency: 'USD',
        payment_amount: 10000,    
        signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO\/RLUkDJrOcZzUCwX6R\/ekpZhkIQg=='
    }
)

Как отреагировать на оповещение

Ваша система должна ответить на оповещение кодом состояния HTTP 200 OK, если она успешно приняла его. При этом, ваша система не должна ограничивать время приема оповещений, потому что оповещения от Rocketpay могут поступать с задержкой.

Если ваша система приняла оповещение с ошибкой, она должна ответить на него кодом состояния HTTP, соответствующим ошибке, например 400 Bad Request (если вам не удалось преобразовать строку параметров в массив) или 500 Internal Server Error (если оповещение пришло на неправильный URL-адрес). Несмотря на то что ваша система приняла оповещение с ошибкой, она должна быть готова принять последующие оповещения, относящиеся к этому же платежу.

Если ваша система не ответила на оповещение кодом состояния HTTP 200 OK, Rocketpay будет отправлять вам оповещения снова по следующему расписанию:

• 6 попыток с интервалом в 10 секунд;
• далее 62 попытки в течение четырех часов с увеличивающимся интервалом (интервал увеличивается в соответствии с формулой 70 + 10·1,12n-4, где n — порядковый номер попытки отправки);
• потом каждые 4 часа до достижения максимального количества попыток.

Всего Rocketpay отправляет 120 оповещений в течение 11 суток. Расписание отправки оповещений может незначительно изменяться в зависимости от загрузки системы.