Работа с оповещениями

Введение

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

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

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

Виды оповещений

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

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

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

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

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

Типовые случаи применения

К типовым случаям применения оповещений можно отнести следующие.

• Изменение статуса платежа.

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

  {
      "project_id": 42,
      "customer": {
          "id": "17008"
      },
      "payment": {
          "id": "6789101",
          "type": "purchase",
          "status": "awaiting capture",      // промежуточный статус платежа
          "date": "2022-01-11T13:00:40+0000",
          "method": "card",
          "sum": {
              "amount": 200000,
              "currency": "USD"
          },
          "description": ""
      },
      "account": {
          "number": "431422******0056",
          "type": "visa",
          "card_holder": "SONYA KOVALEVSKY",
          "expiry_month": "05",
          "expiry_year": "2025"
      },
      "operation": {
          "id": 77000002,
          "type": "auth",
          "status": "success",
          "date": "2022-01-11T13:00:40+0000",
          "created_date": "2022-01-11T13:00:37+0000",
          "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
          "sum_initial": {
              "amount": 200000,
              "currency": "USD"
          },
          "sum_converted": {
              "amount": 200000,
              "currency": "USD"
          },
          "provider": {
              "id": 120,
              "payment_id": "224750650",
              "date": "2022-01-11T13:00:39+0000",
              "result_code": "000",
              "result_message": "Approved",
              "auth_code": "505050",
              "endpoint_id": 120
          },
          "code": "0",
          "message": "Success",
          "description": "SUCCESS",
          "eci": "00"
      },
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
  }

  {
      "project_id": 42,
      "payment": {
          "id": "6789102",
          "type": "purchase",
          "status": "success",      // итоговый статус платежа
          "date": "2022-01-11T15:54:40+0000",
          "method": "card",
          "sum": {
              "amount": 200000,
              "currency": "EUR"
          },
          "description": ""
      },
      "account": {
          "number": "431422******0056",
          "type": "visa",
          "card_holder": "SONYA KOVALEVSKY",
          "expiry_month": "05",
          "expiry_year": "2025"
      },
      "customer": {
          "id": "17008"
      },
      "operation": {
          "id": 7178000006597,
          "type": "capture",
          "status": "success",
          "date": "2022-01-11T15:54:40+0000",
          "created_date": "2022-01-11T15:54:39+0000",
          "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
          "sum_initial": {
              "amount": 200000,
              "currency": "EUR"
          },
          "sum_converted": {
              "amount": 200000,
              "currency": "EUR"
          },
          "provider": {
              "id": 120,
              "payment_id": "227307324",
              "date": "2022-01-11T15:54:40+0000",
              "auth_code": "919372",
              "endpoint_id": 120
          },
          "code": "0",
          "message": "Success"
      },
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
  }

• Необходимость действий на стороне веб-сервиса.

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

  "redirect_data": {
      "body": {},
      "method": "GET",
      "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
    }

   "display_data": [
              {
                  "type": "qr_data",
                  "title": "QR code",
                  "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
              },
              {
                  "type": "add_info",
                  "title": "QR Code Timeout",
                  "data": "600"
              }
          ]

• Формирование или удаление токена платёжной карты.

  Это оповещения с информацией о событиях, связанных с токенами платёжных карт (таких, как формирование и удаление токенов).

  {
      "general":{
      "project_id":42,
      "customer_id":17008,
      "signature":"gmTHcy4ISuWEiV8+AupOYkl9S5eLZ",
          "request": {
  			"id": "3c7f53fdbb5b8c96f9707457d75f",
  			"action": "tokenize",
  			"status": "success"
          },
      "token":"f365bb1729f9b72fd9c0970e35c91d18070d15654",
      "token_created_at":"2022-01-28 13:30:57",
      "token_status":"active"
  }

Конфигурирование для проектов

В общем случае отправка оповещений для рабочих проектов мерчанта настраивается при интеграции веб-сервиса с платёжной платформой ecommpay. Вместе с тем, для изменения правил отправки оповещений всегда можно использовать возможности интерфейса Dashboard (подробнее), а также указывать специальные параметры в запросах на проведение платежей (подробнее далее) и при необходимости обращаться к специалистам технической поддержки ecommpay.

Со стороны мерчанта для оповещений можно настраивать следующие свойства:

В общем случае отправка оповещений настраивается при интеграции веб-сервиса с платёжной платформой ecommpay. Вместе с тем, со стороны мерчанта (используя возможности Dashboard и Gate API, а также обращения в техническую поддержку) всегда можно настраивать следующие свойства:

• Обязательность отправки.

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

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

• Адреса доставки.

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

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

• Время задержки отправки.

  При необходимости оповещения могут отправляться с задержкой до 600 секунд включительно, например для удобства их обработки на стороне веб-сервиса.

  При необходимости оповещения могут отправляться с задержкой до 600 секунд включительно.

• Состав параметров.

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

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

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

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

  {
      "account": {
          "number": "431422******0056",
          "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
          "type": "visa",
          "card_holder": "SONYA KOVALEVSKY",
          "expiry_month": "05",
          "expiry_year": "2025"
      },
      "customer": {
          "id": "17008",
          "phone": "79012345678"
      },
      "payment": {
          "date": "2022-11-11T13:02:42+0000",
          "id": "456789",
          "method": "card",
          "status": "success",
          "sum": {
              "amount": 40000,
              "currency": "EUR"
          },
          "type": "purchase",
          "description": ""
      },
      "project_id": 42,
      "operation": {
          "id": 969000002636,
          "type": "sale",
          "status": "success",
          "date": "2022-11-11T13:02:42+0000",
          "created_date": "2022-11-11T13:01:45+0000",
          "request_id": "c6eed1eb14c6290088cbc0be4667c",
          "sum_initial": {
              "amount": 40000,
              "currency": "EUR"
          },
          "sum_converted": {
              "amount": 40000,
              "currency": "EUR"
          },
          "provider": {
              "id": 408,
              "payment_id": "330157196",
              "date": "2022-11-11T13:02:32+0000",
              "auth_code": "",
              "endpoint_id": "612266625"
          },
          "code": "0",
          "message": "Success",
          "eci": "07"
      },
      "signature": "v7KNMpfIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  }

  {
      "account": {
          "number": "431422******0056",
          "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
          "type": "visa",
          "card_holder": "SONYA KOVALEVSKY",
          "id": 45678,
          "expiry_month": "05",
          "expiry_year": "2025"
      },
      "customer": {            // объект с расширенной информацией о пользователе
          "id": "17008",
          "email": "sonya.kovalevsky@example.com"
          "phone": "79012345678",
          "first_name": "Sonya",
          "last_name": "Kovalevsky"
      },
      "payment": {
          "date": "2022-11-11T13:02:42+0000",
          "id": "456789",
          "method": "card",
          "status": "success",
          "sum": {
              "amount": 40000,
              "currency": "EUR"
          },
          "type": "purchase",
          "description": ""
      },
      "project_id": 91663,
      "operation": {
          "id": 969000002636,
          "type": "sale",
          "status": "success",
          "date": "2022-11-11T13:02:42+0000",
          "created_date": "2022-11-11T13:01:45+0000",
          "request_id": "c6eed1e088cbc0be4667c",
          "sum_initial": {
              "amount": 40000,
              "currency": "EUR"
          },
          "sum_converted": {
              "amount": 40000,
              "currency": "EUR"
          },
          "provider": {
              "id": 408,
              "payment_id": "330157196",
              "date": "2022-11-11T13:02:32+0000",
              "auth_code": "",
              "endpoint_id": "612266625"
          },
          "code": "0",
          "message": "Success",
          "eci": "07"
      },
      "signature": "v7KNMpfogVftZ1ZZ5D/aZAeb0VMdeR+CqGrYyilUwSm...=="
  }

Управление отправкой для отдельных платежей

При проведении платежей через Gate можно задавать адреса доставки оповещений, их обязательность и время задержки при отправке. Для этого в запросах на проведение платежей могут использоваться следующие параметры:

• merchant_callback_url (в объекте general) — адрес доставки оповещений по этому запросу;
• force_disable (в объекте callback) — указатель запрета отправки оповещений (со значениями true для запрета отправки оповещений с информацией о данном платеже и false для разрешения их отправки);
• delay (в объекте callback) — задержка отправки оповещений, в секундах (от 0 до 600; например, 42).

Информацию о возможности использования этих параметров при запросах к конкретным конечным точкам можно найти в спецификации Gate API.

{
    "general":{
        "project_id":42,
        "payment_id":"456789",
        "merchant_callback_url":"https://example.com",
        "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "customer":{
        "ip_address":"192.0.2.32",
        "id":"17008"
    },
    "payment":{
        "amount":40000,
        "currency":"EUR",
        "callback":{
            "delay":42                // время задержки, равное 42 секундам
        }
    },
    "card":{
        "pan":"4314220000000056",
        "year":2025,
        "month":5,
        "card_holder":"SONYA KOVALEVSKY",
        "cvv":"123"
    }
}

Порядок работы

Технически оповещение представляет собой HTTP-POST-сообщение, отправляемое на предоставленный мерчантом URL. Порядок реагирования на каждое поступающее оповещение со стороны веб-сервиса сводится к следующим шагам:

Порядок реагирования на каждое поступающее оповещение со стороны веб-сервиса сводится к следующим шагам:

1. Принять и проверить оповещение.

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

   Чтобы подтверждать достоверность отправителя и целостность данных, необходимо проверять подпись, включаемую в состав каждого оповещения. Подробнее о такой проверке — в разделе Работа с подписью к данным.

   Оповещения следует принимать только с IP-адресов платёжной платформы, предоставленных ecommpay, и без ограничения времени ожидания. При этом для подтверждения целостности в каждом полученном оповещении необходимо проверять подпись.

2. Подтвердить получение оповещения.

   Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа 200 ОК, в остальных случаях — с кодами ответов, соответствующими ошибкам, например HTTP 400 Bad Request, если не удалось преобразовать строку параметров в массив, или HTTP 500 Internal Server Error, если оповещение поступило на некорректный URL веб-сервиса.

   Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа 200 ОК, в остальных случаях — с кодами ответов, соответствующими ошибкам, например HTTP 400 Bad Request.

   Если от веб-сервиса не поступило сообщение с кодом ответа 200 ОК, независимо от характера ошибки оповещение отправляется повторно.

3. Выполнить необходимые действия.

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

Повторные отправления

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

В общем случае отправка повторных оповещений выполняется в следующем порядке:

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

1. 6 попыток с нарастающим интервалом, от 10 до 60 секунд с увеличением на 10 секунд для каждой попытки.
2. 58 попыток с нарастающим интервалом, от 84 секунд до 2,5 часов с увеличением по формуле 70 + 10 × 1,12n − 4 (в секундах), где n — порядковый номер попытки.
3. 56 попыток каждые 4 часа до достижения в общей сложности 120 попыток, после чего отправка оповещений по этому событию прекращается.

Этот порядок может незначительно меняться с учётом загруженности серверов и каналов связи, но в целом автоматические попытки доставить оповещение укладываются в 11 суток. Для изменения этого порядка можно обращаться к специалистам технической поддержки ecommpay.

Для изменения этого порядка можно обращаться к специалистам технической поддержки ecommpay.

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

Устранение неисправностей

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

• Не приходят оповещения ни по одному из событий.

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

  В таких ситуациях рекомендуется:

  1. Убедиться, что со стороны веб-сервиса отправлялись корректные запросы (без запрета отправки оповещений) и они были приняты со стороны платформы. При необходимости отправить тестовый запрос, например на формирование токена платёжной карты.
  2. Если запросы принимаются в платформе, но оповещения по-прежнему не приходят — проверить работоспособность URL для приёма оповещений. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки ecommpay.
  3. Если по итогам предыдущих действий проблему не удалось решить — обратиться к специалистам технической поддержки ecommpay.
• Не приходят оповещения по событиям отдельных типов.

  Это может быть связано с отсутствием событий таких типов, с недействительностью URL веб-сервиса или с отключением отправки оповещений для событий этих типов.

  В таких ситуациях рекомендуется:

  1. Убедиться в наличии событий тех типов, по которым не приходят оповещения, используя карточки платежей в интерфейсе Dashboard.
  2. Если такие события выполнялись, но оповещения по-прежнему не приходят — проверить работоспособность URL для приёма оповещений по событиям соответствующих типов. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки ecommpay.
  3. Если проблему не удалось решить — обратиться к специалистам технической поддержки ecommpay.
• Не приходит оповещение по конкретной операции.

  Это может быть связано с тем, что в объекте callback запроса на выполнение операции был передан параметр force_disable со значением true.

  В такой ситуации уточнять состояние операции можно через Gate, используя запросы на получение соответствующей информации (подробнее), Dashboard и Telegram-бота.

Оповещения могут не приходить на требуемые адреса по различным причинам: например, из-за отсутствия в платёжной платформе целевых запросов и событий, наличия проблем в каналах связи или недействительности заданных URL веб-сервиса. Со стороны мерчанта реагирование на такие ситуации можно свести к следующим действиям:

1. Убедиться, что для используемого проекта или для событий отдельных типов по этому проекту не отключена отправка оповещений.
2. Убедиться, что со стороны веб-сервиса отправляются корректные запросы (без запрета отправки оповещений) и они принимаются на стороне платформы. При необходимости отправить тестовый запрос.
3. Проверить работоспособность URL для приёма оповещений. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки ecommpay.
4. Если проблему не удалось решить — обратиться к специалистам технической поддержки ecommpay.

Параметры оповещений о платежах и операциях

Состав и названия параметров, передаваемых в оповещенияx о платежах и операциях, могут быть базовыми или индивидуально настроенными для отдельных проектов. К базовым относятся следующие параметры.

Параметры оповещений о токенах