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

Оповещение (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 отправляет оповещения

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

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

Когда со стороны вашей системы необходимы какие-то действия для выполнения платежа, платежная платформа Rocketpay присваивает платежу определенный статус и отправляет вам соответствующее оповещение. Чтобы узнать, какие статусы могут принимать платежи в платежной платформе, см. раздел Типы платежей, операции и платежи.

Ниже перечислены некоторые действия, которые могут потребоваться со стороны вашей системы для выполнения платежа:

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

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

  "clarification_fields": {
              "account": {
                  "type": "object",
                  "description": "Object contains the account details of bank",
                  "properties": {
                      "number": {
                          "type": "string",
                          "maxLength": 100,
                          "minLength": 1,
                          "description": "Customer account number"
                      }
                  },
                  "required": [
                      "number"
                  ],
                  "errors": [
                      {
                          "property": "account.number",
                          "message": "The property number is required",
                          "constraint": "required"
                      }
                  ]
              }
          },

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

  Если в процессе оплаты пользователь получает от платежной системы данные, которые затем вы должны передать платежной платформе, информация об этом будет указана в статье о платежном методе, с помощью которого производилась оплата. Список платежных методов, доступных в Rocketpay для проведения платежей, см. в разделе Платежные методы.

  Рис.: Пример фрагмента оповещения, где указано, какие данные ваша система должна передать для продолжения платежа

  {
      "clarification_fields": [
          "approval_code"
      ]
  }

• Ваша система должна осуществить необходимые действия, чтобы пользователь прошел процедуру 3-D Secure для совершения оплаты. Подробную информацию об этой процедуре см. в разделах Аутентификация по протоколу 3‑D Secure 1 и Аутентификация по протоколу 3‑D Secure 2 или уточняйте у своего курирующего менеджера в Rocketpay;
• Ваша система должна перенаправить пользователя для совершения оплаты. В таком случае Rocketpay отправит вам в оповещении данные для перенаправления пользователя:

  Рис.: Пример фрагмента оповещения, содержащий данные для перенаправления пользователя

  "redirect_data": {
      "method": "GET",
      "body": [],
      "encrypted": [],
      "url": "https://example.com/redirect"
  }

• Ваша система должна отобразить пользователю информацию для оплаты, например платежную инструкцию или QR-код для оплаты. В таком случае Rocketpay отправит вам в оповещении данные для отображения пользователю:

  Рис.: Пример фрагмента оповещения, содержащий данные для отображения QR-кода пользователю

  "display_data": [
              {
                  "type": "qr_data",
                  "title": "QR code",
                  "data": "00020101com.359a71a-0cad-4cb2-a9503***63042BBF"
              }
          ],

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

Оповещения отправляются на 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 , но с поправкой на то, что речь идет об итоговом оповещении об отклонении платежа.

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "merchant_callback_url": "http://example.com/callback/default",
        "merchant_success_callback_url": "http://example.com/success",
        "merchant_decline_callback_url": "http://example.com/decline",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    }
}

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

Ваша система должна ответить на оповещение кодом состояния 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 суток. Расписание отправки оповещений может незначительно изменяться в зависимости от загрузки системы.

Вы можете отложить отправку оповещений по конкретному платежу. Для этого в запросе на проведение платежа передайте параметр delay в объекте callback с необходимым значением в секундах. Максимальное значение задержки отправки — 600 секунд.

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    },
    "callback": {
            "delay": 30                // время задержки отправки оповещения в секундах
    }
}