Работа с подписью к данным

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

Для обеспечения защищённого обмена данными при работе с платёжной платформой Benker используется криптографический протокол TLS (Transport Layer Security; протокол защиты транспортного уровня) версии не ниже 1.2, а для подтверждения авторства и целостности передаваемых данных дополнительно применяется цифровая подпись.

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

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

Подписывание данных

Описание алгоритма

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

  1. Данные, которые требуется подписать.

    Как правило, это заполненное тело запроса, все параметры запроса за исключением подписи или JavaScript-объект configObj с параметрами без включения параметра signature.

  2. Ключ, используемый для подписывания.
    Прим.: Для работы с Data API должны использоваться ключи, получаемые через интерфейс Dashboard в связке с токенами. (Подробнее в разделе Порядок доступа к данным.)

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

В качестве выходных данных подписывания в зависимости от реализации алгоритма могут выступать либо подпись, либо подписанные данные — как правило, это итоговый объект или итоговое тело запроса в формате JSON с параметром signature, включённым в его состав.

Далее в описании, примерах и формах для тестирования представлен наиболее показательный вариант реализации алгоритма, актуальный при работе с интерфейсами Payment Page API, Gate API и Data API.

В состав алгоритма в этом случае включаются следующие шаги:

  1. Проверка входных данных на соблюдение заданных требований:

    1. Структура данных для подписывания должна соответствовать формату JSON. При работе с Payment Page также можно использовать JavaScript-объекты.
    2. В составе данных для подписывания не должен присутствовать параметр signature (даже с пустым значением).
    3. Должен быть задан ключ.
  2. Приведение структуры проверяемых данных к требуемой глубине вложенности.

    В зависимости от интерфейса платёжной платформы, к которому должен отправляться запрос, на этом шаге могут выполняться разные действия:

    • При работе через Payment Page отдельные параметры, представленные вложенными объектами, кодируются в строки с применением алгоритма Base64 или преобразования URL-encoding — в соответствии с требованиями, представленными в статье Параметры вызова платёжной формы.
    • При работе через Gate API ограничений по вложенности не применяется и действий по преобразованию или исключению данных не требуется.
    • При работе через Data API значения всех параметров, расположенных на четвёртом и более глубоких уровнях вложенности, заменяются пустыми строками.

  3. Преобразование данных в строку UTF-8 с сортировкой параметров в естественном порядке. В рамках этого шага выполняются следующие действия:

    1. Логические (булевы) значения кодируются следующим образом: false заменяется на 0, а true — на 1. Но это относится только к булевым значениям — в строковых параметрах, даже если они содержат значения false или true, замены на 0 или 1 не используются.
    2. Каждый параметр преобразуется в строку, содержащую полный путь к параметру, название параметра и его значение:
      <родительский_узел_1>:...:<родительский_узел_N>:<название_параметра>:<значение_параметра>

      где родительские узлы — это названия объектов и (или) массивов, в состав которых включена пара «название параметра — значение параметра». Родительские узлы располагаются в порядке их вложения, начиная с самого верхнего уровня. В качестве разделителя при этом используется двоеточие (:), между парами «название параметра — значение параметра» удаляются запятые, а у строковых значений параметров удаляются обрамляющие кавычки.

    3. Параметры с нулевыми, а также пустыми значениями остаются в строке, например запись "payment_description":"" представляется в виде payment_description:. Замены пустых значений на пробелы или null не применяются.
    4. Элементы массивов записываются отдельными строками, с указанием номера каждого элемента, начиная с нуля. Например, массив ["alpha", "beta", "gamma"] представляется в виде трёх строк: 0:alpha, 1:beta и 2:gamma.
    5. Пустые массивы полностью игнорируются и не включаются в набор строк для создания подписи.
    6. Кодировка всех строк приводится к формату UTF-8.
    7. Полученные строки упорядочиваются в естественном порядке и объединяются в одну строку с использованием в качестве разделителя точки с запятой (;).
  4. Получение двоичного кода HMAC с использованием ключа и функции SHA-512. На этом шаге для полученной строки с параметрами вычисляется HMAC (Hash-based Message Authentication Code; код аутентификации сообщений с использованием хеш-функции) с использованием функции хеширования SHA‑512 (Secure Hash Algorithm; безопасный алгоритм хеширования) и применяемого ключа. И этот HMAC представляется в виде необработанных двоичных данных.
  5. Кодирование двоичного кода HMAC с применением алгоритма Base64. На этом шаге полученный двоичный код HMAC кодируется с использованием алгоритма Base64. Получаемая при этом строка является подписью к исходным данным.
  6. Добавление подписи к данным. На этом шаге к исходным данным для подписывания добавляется параметр signature с полученной подписью в качестве его значения.

Пример для запроса на оплату через Payment Page

Допустим, что надо подписать запрос на открытие Payment Page при следующих условиях:

  • Используемый ключ — secret
  • Предварительная версия объекта configObj, в котором еще нет значения параметра с подписью, выглядит так:
    {
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "<подпись, которую нужно создать>" 
}

Задача заключается в том, чтобы вычислить подпись, то есть определить значение параметра signature. Для этого необходимо:

  1. Убедиться, что в теле запроса нет параметра signature, даже с пустым значением. Если такой параметр есть, его нужно удалить:
    {
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "<подпись, которую нужно создать>" 
}
  2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма:
    project_id:120
payment_id:580
payment_amount:1000
payment_currency:EUR
customer_id:customer1
customer_first_name:John
customer_last_name:Doe
merchant_return_url:http://example.com/return
  3. Отсортировать полученные строки в естественном порядке:
    customer_first_name:John
customer_id:customer1
customer_last_name:Doe
merchant_return_url:http://example.com/return
payment_amount:1000
payment_currency:EUR
payment_id:580
project_id:120
  4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой:
    customer_first_name:John;customer_id:customer1;customer_last_name:Doe;merchant_return_url:http://example.com/return;payment_amount:1000;payment_currency:EUR;payment_id:580;project_id:120
  5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64:
    rgA1gh7M3LQBSJn1UiCkjIRWkO39c5xMyI5gwCdI/AgLJ1wYkw0clL8Zm89CGHZo6dp9E6YOLa870GH4GkMmZA==
  6. Добавить полученную подпись в объект configObj:
    {
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "merchant_return_url": "http://example.com/return",
   "signature": "rgA1gh7M3LQBSJn1UiCkjIRWkO39c5xMyI5gwCdI/AgLJ1wYkw0clL8Zm89CGHZo6dp9E6YOLa870GH4GkMmZA==" 
}

Форма тестирования для Payment Page

Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписью при отправке запросов на открытие Payment Page.

Прим.:

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

Пример для запроса на оплату через Gate

Допустим, что надо подписать запрос в Gate при следующих условиях:

  • Используемый ключ — secret
  • Предварительная версия тела запроса, в котором еще нет значения параметра с подписью, выглядит так:
    {
    "general": {
      "project_id": 2990,
      "payment_id": "payment_id",
      "signature": "<signature that needs to be generated>" 
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}

Задача заключается в том, чтобы вычислить подпись, то есть рассчитать значение параметра signature и добавить его в запрос. Для этого необходимо:

  1. Убедиться, что в теле запроса нет параметра signature, даже с пустым значением. Если такой параметр есть, его нужно удалить.
    {
    "general": {
      "project_id": 2990,
      "payment_id": "payment_id",
      "signature": "<signature that needs to be generated>"
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}
  2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма:
    general:project_id:2990
general:payment_id:payment_id
payment:amount:1000
payment:currency:EUR
customer:id:customer1
customer:ip_address:66.249.64.45
customer:first_name:John
customer:last_name:Doe
account:bank_id:22731
return_url:return:http://example.com/return
  3. Отсортировать полученные строки в естественном порядке:
    account:bank_id:22731
customer:first_name:John
customer:id:customer1
customer:ip_address:66.249.64.45
customer:last_name:Doe
general:payment_id:payment_id
general:project_id:2990
payment:amount:1000
payment:currency:EUR
return_url:return:http://example.com/return
  4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой:
    account:bank_id:22731;customer:first_name:John;customer:id:customer1;customer:ip_address:66.249.64.45;customer:last_name:Doe;general:payment_id:payment_id;general:project_id:2990;payment:amount:1000;payment:currency:EUR;return_url:return:http://example.com/return
  5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64:
    bywiqOm5qhxOdslsXGgH1pJIkxzkJfeDsLYn2wzaDK4ZjHjgCRXN1M1fz3jrhI5CYUFwzSUqf8QLQ3xJ6wKEfw==
  6. Добавить полученную подпись в тело запроса:
    {
    "general": {
      "project_id": 2990,
      "payment_id": "payment_id",
     "signature": "bywiqOm5qhxOdslsXGgH1pJIkxzkJfeDsLYn2wzaDK4ZjHjgCRXN1M1fz3jrhI5CYUFwzSUqf8QLQ3xJ6wKEfw=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 22731
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}

Форма тестирования для Gate API

Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписью при отправке запросов к Gate API.

Пример для запроса на получение данных через Data API

Допустим, что надо подписать запрос в Dashboard при следующих условиях:

  • Используемый ключ — secret
  • Предварительная версия тела запроса, в котором еще нет значения параметра с подписью, выглядит так:
    {
  "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl",
  "interval": {
    "from": "2025-01-01 14:53:55",
    "to": "2025-01-30 13:53:59"
  },
  "project_id": [
    183
  ],
  "limit": 3,
  "offset": 0,
  "tz": "Europe/Athens",
 "signature": "<подпись, которую нужно создать>"
}

Задача заключается в том, чтобы вычислить подпись, то есть рассчитать значение параметра signature и добавить его в запрос. Для этого необходимо:

  1. Убедиться, что в теле запроса нет параметра signature, даже с пустым значением. Если такой параметр есть, его нужно удалить.
    {
  "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl",
  "interval": {
    "from": "2025-01-01 14:53:55",
    "to": "2025-01-30 13:53:59"
  },
  "project_id": [
    183
  ],
  "limit": 3,
  "offset": 0,
  "tz": "Europe/Athens",
  "signature": "<подпись, которую нужно создать>"
}
  2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма:
    token:WKiarERJ5pcceNerpM9R5TNnyPTQMl
interval:from:2025-01-01 14:53:55
interval:to:2025-01-30 13:53:59
project_id:0:183
limit:3
offset:0
tz:Europe/Athens
  3. Отсортировать полученные строки в естественном порядке:
    interval:from:2025-01-01 14:53:55
interval:to:2025-01-30 13:53:59
limit:3
offset:0
project_id:0:183
token:WKiarERJ5pcceNerpM9R5TNnyPTQMl
tz:Europe/Athens
  4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой:
    interval:from:2025-01-01 14:53:55;interval:to:2025-01-30 13:53:59;limit:3;offset:0;project_id:0:183;token:WKiarERJ5pcceNerpM9R5TNnyPTQMl;tz:Europe/Athens
  5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64:
    OR3xug58e9lpzT30E9Hc8/nBRCaXYH//pGcFP66bOlI7QZ8oiRuKlMR0aYIugo2GGxjVzmULzHqwjgcg9iM6iQ==
  6. Добавить полученную подпись в тело запроса:
    {
  "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl",
  "interval": {
    "from": "2025-01-01 14:53:55",
    "to": "2025-01-30 13:53:59"
  },
  "project_id": [
    183
  ],
  "limit": 3,
  "offset": 0,
  "tz": "Europe/Athens",
 "signature": "OR3xug58e9lpzT30E9Hc8/nBRCaXYH//pGcFP66bOlI7QZ8oiRuKlMR0aYIugo2GGxjVzmULzHqwjgcg9iM6iQ=="
}

Форма тестирования для Data API

Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписью при отправке запросов к Data API.

Прим.: При работе с запросами, отправляемыми к платформе через Data API, и ответами на такие запросы необходимо учитывать, что расчётная подпись составляется с ограничением на 3 уровня вложенности и данные на более глубоких уровнях вложенности не принимаются в расчёт.

Проверка данных

Описание алгоритма

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

  1. Подписанные данные, которые требуется проверить. Как правило, это тело оповещения или ответа в формате JSON с параметром signature в его составе.
  2. Ключ, используемый для проверки. Это должен быть ровно тот ключ, который был использован для подписывания проверяемых данных.

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

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

В состав алгоритма в этом случае включаются следующие шаги:

  1. Проверка входных данных на соблюдение заданных требований:
    1. Структура проверяемых данных должна соответствовать формату JSON.
    2. В составе проверяемых данных должен присутствовать параметр signature с подписью.
    3. Должен быть задан проверочный ключ.
  2. Извлечение подписи из проверяемых данных. На этом шаге из проверяемых данных исключается параметр signature, а его значение фиксируется для последующего сличения с расчётной подписью.

  3. При работе с ответами, получаемыми от платформы через Data API, на этом шаге значения всех параметров, расположенных на четвёртом и более глубоких уровнях вложенности, заменяются пустыми строками (например, в ответе с информацией о выполнении операций за заданный период для объекта "sum_initial": {"amount": 2000, "currency": "EUR"} необходимо исключить значение и учитывать при расчёте подписи запись вида "sum_initial": ""). При работе с ответами и оповещениями, получаемыми через другие интерфейсы платформы, ограничений по вложенности не применяется и действий по исключению данных не требуется.

  4. Формирование расчётной подписи для проверяемых данных:
    1. Преобразование данных в строку UTF-8 с сортировкой параметров в естественном порядке. В рамках этого шага выполняются следующие действия:
      1. Логические (булевы) значения кодируются следующим образом: false заменяется на 0, а true — на 1. Но это относится только к булевым значениям — в строковых параметрах, даже если они содержат значения false или true, замены на 0 или 1 не используются.
      2. Каждый параметр преобразуется в строку, содержащую полный путь к параметру, название параметра и его значение: <родительский_узел_1>:...:<родительский_узел_N>:<название_параметра>:<значение_параметра>, где родительские узлы — это названия объектов и (или) массивов, в состав которых включена пара «название параметра — значение параметра». Родительские узлы располагаются в порядке их вложения, начиная с самого верхнего уровня. В качестве разделителя при этом используется двоеточие (:), между парами «название параметра — значение параметра» удаляются запятые, а у строковых значений параметров удаляются обрамляющие кавычки.
      3. Параметры с нулевыми, а также пустыми значениями остаются в строке, например запись "payment_description":"" представляется в виде payment_description:. Замены пустых значений на пробелы или null не применяются.
      4. Элементы массивов записываются отдельными строками, с указанием номера каждого элемента, начиная с нуля. Например, массив ["alpha", "beta", "gamma"] представляется в виде трёх строк: 0:alpha, 1:beta и 2:gamma.
      5. Пустые массивы полностью игнорируются и не включаются в набор строк для создания подписи.
      6. Кодировка всех строк приводится к формату UTF-8.
      7. Полученные строки упорядочиваются в естественном порядке и объединяются в одну строку с использованием в качестве разделителя точки с запятой (;).
    2. Получение двоичного кода HMAC с использованием ключа и функции SHA‑512. На этом шаге для полученной строки с параметрами вычисляется HMAC (Hash-based Message Authentication Code; код аутентификации сообщений с использованием хеш-функции) с использованием функции хеширования SHA‑512 (Secure Hash Algorithm; безопасный алгоритм хеширования) и применяемого ключа. И этот HMAC представляется в виде необработанных двоичных данных.
    3. Кодирование двоичного кода HMAC с применением алгоритма Base64. На этом шаге полученный двоичный код HMAC кодируется с использованием алгоритма Base64. Получаемая при этом строка является подписью к исходным данным.
  5. Сопоставление подписей. На этом шаге расчётная подпись сопоставляется с проверяемой. Если подписи совпадают, данные признаются целостными и достоверными. При несовпадении подписей данные не могут считаться достоверными и не должны использоваться в качестве рабочих.

Пример для оповещения

Допустим, что надо проверить подпись оповещения при следующих условиях:

  • Используемый ключ — secret
  • Тело полученного оповещения выглядит так:
    Рис. 1. Тело оповещения
    {
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}

Для проверки подписи необходимо:

  1. Удалить из тела оповещения параметр signature вместе с его значением: 
    {
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}

  2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма:

    project_id:200
payment:id:abc12345
payment:type:purchase
payment:status:success
payment:date:2025-03-20T14:22:06+0000
payment:method:Greek Banks
payment:sum:amount:1000
payment:sum:currency:EUR
payment:description:Success
customer:id:123
operation:id:9529253065607
operation:type:sale
operation:status:success
operation:date:2025-03-20T14:22:06+0000
operation:created_date:2025-03-20T14:22:00+0000
operation:request_id:f1de353331a01fd14163fe4226-00009530
operation:sum_initial:amount:1000
operation:sum_initial:currency:EUR
operation:sum_converted:amount:1000
operation:sum_converted:currency:EUR
operation:code:0
operation:message:Success
operation:provider:id:1914
operation:provider:payment_id:
operation:provider:auth_code:
  3. Отсортировать полученные строки в естественном порядке:
    customer:id:123
operation:code:0
operation:created_date:2025-03-20T14:22:00+0000
operation:date:2025-03-20T14:22:06+0000
operation:id:9529253065607
operation:message:Success
operation:provider:auth_code:
operation:provider:id:1914
operation:provider:payment_id:
operation:request_id:f1de353331a01fd14163fe4226-00009530
operation:status:success
operation:sum_converted:amount:1000
operation:sum_converted:currency:EUR
operation:sum_initial:amount:1000
operation:sum_initial:currency:EUR
operation:type:sale
payment:date:2025-03-20T14:22:06+0000
payment:description:Success
payment:id:abc12345
payment:method:Greek Banks
payment:status:success
payment:sum:amount:1000
payment:sum:currency:EUR
payment:type:purchase
project_id:200
  4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой:
    customer:id:123;operation:code:0;operation:created_date:2025-03-20T14:22:00+0000;operation:date:2025-03-20T14:22:06+0000;operation:id:9529253065607;operation:message:Success;operation:provider:auth_code:;operation:provider:id:1914;operation:provider:payment_id:;operation:request_id:f1de353331a01fd14163fe4226-00009530;operation:status:success;operation:sum_converted:amount:1000;operation:sum_converted:currency:EUR;operation:sum_initial:amount:1000;operation:sum_initial:currency:EUR;operation:type:sale;payment:date:2025-03-20T14:22:06+0000;payment:description:Success;payment:id:abc12345;payment:method:Greek Banks;payment:status:success;payment:sum:amount:1000;payment:sum:currency:EUR;payment:type:purchase;project_id:200
  5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64:
    jOBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw==
  6. Сравнить полученную подпись с проверяемой.

    В данном случае подписи не совпадают, а это значит, что такое оповещение недостоверно или ошибочно и должно быть отброшено.

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

Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписанными данными.

Пример для ответа через Gate API

Допустим, что надо проверить подпись ответа при следующих условиях:

  • Используемый ключ — secret
  • Тело полученного ответа выглядит так:
    Рис. 2. Тело ответа
    {
    "project_id": 131221,
    "payment": {
        "id": "abc12345",
        "type": "purchase",
        "status": "awaiting confirmation",
        "date": "2025-04-11T05:22:03+0000",
        "method": "Austrian Banks",
        "sum": {
            "amount": 22500,
            "currency": "EUR"
        },
        "description": ""
    },
    "account": {
        "number": "AT0000******2000"
    },
    "customer": {
        "id": "test@testmail.mail"
    },
    "operations": [
        {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2025-04-11T05:22:03+0000",
            "created_date": "2025-04-11T05:19:57+0000",
            "request_id": "a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd-00002000",
            "sum_initial": {
                "amount": 22500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 22500,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1234,
                "payment_id": "X1E6D23319ETBXT",
                "auth_code": ""
            }
        },
        {
            "id": 9529253065608,
            "type": "payment confirmation",
            "status": "processing",
            "date": "2025-04-11T05:22:03+0000",
            "created_date": "2025-04-11T05:22:03+0000",
            "request_id": "9kLmga7BQwP2X8rT-EyuV3Hn6Zc1Rbd-00002000",
            "sum_initial": {
                "amount": 22500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 22500,
                "currency": "EUR"
            },
            "code": "29999",
            "message": "Awaiting processing",
            "provider": {
                "id": 10001,
                "payment_id": "",
                "auth_code": ""
            }
        }
    ],
  "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="
}

Для проверки подписи необходимо:

  1. Удалить из тела ответа параметр signature вместе с его значением:
    {
    "project_id": 131221,
    "payment": {
        "id": "abc12345",
        "type": "purchase",
        "status": "awaiting confirmation",
        "date": "2025-04-11T05:22:03+0000",
        "method": "Austrian Banks",
        "sum": {
            "amount": 22500,
            "currency": "EUR"
        },
        "description": ""
    },
    "account": {
        "number": "AT0000******2000"
    },
    "customer": {
        "id": "test@testmail.mail"
    },
    "operations": [
        {
            "id": 9529253065607,
            "type": "sale",
            "status": "success",
            "date": "2025-04-11T05:22:03+0000",
            "created_date": "2025-04-11T05:19:57+0000",
            "request_id": "a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd-00002000",
            "sum_initial": {
                "amount": 22500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 22500,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1234,
                "payment_id": "X1E6D23319ETBXT",
                "auth_code": ""
            }
        },
        {
            "id": 9529253065608,
            "type": "payment confirmation",
            "status": "processing",
            "date": "2025-04-11T05:22:03+0000",
            "created_date": "2025-04-11T05:22:03+0000",
            "request_id": "9kLmga7BQwP2X8rT-EyuV3Hn6Zc1Rbd-00002000",
            "sum_initial": {
                "amount": 22500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 22500,
                "currency": "EUR"
            },
            "code": "29999",
            "message": "Awaiting processing",
            "provider": {
                "id": 10001,
                "payment_id": "",
                "auth_code": ""
            }
        }
    ],
  "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="
}

  2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма:

    project_id:131221
payment:id:abc12345
payment:type:purchase
payment:status:awaiting confirmation
payment:date:2025-04-11T05:22:03+0000
payment:method:Austrian Banks
payment:sum:amount:22500
payment:sum:currency:EUR
payment:description:
account:number:AT0000******2000
customer:id:test@testmail.mail
operations:0:id:9529253065607
operations:0:type:sale
operations:0:status:success
operations:0:date:2025-04-11T05:22:03+0000
operations:0:created_date:2025-04-11T05:19:57+0000
operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd-00002000
operations:0:sum_initial:amount:22500
operations:0:sum_initial:currency:EUR
operations:0:sum_converted:amount:22500
operations:0:sum_converted:currency:EUR
operations:0:code:0
operations:0:message:Success
operations:0:provider:id:1234
operations:0:provider:payment_id:X1E6D23319ETBXT
operations:0:provider:auth_code:
operations:1:id:9529253065608;
operations:1:type:payment confirmation
operations:1:status:processing
operations:1:date:2025-04-11T05:22:03+0000
operations:1:created_date:2025-04-11T05:22:03+0000
operations:1:request_id:9kLmga7BQwP2X8rT-EyuV3Hn6Zc1Rbd-00002000
operations:1:sum_initial:amount:22500
operations:1:sum_initial:currency:EUR
operations:1:sum_converted:amount:22500
operations:1:sum_converted:currency:EUR
operations:1:code:29999
operations:1:message:Awaiting processing
operations:1:provider:id:10001
operations:1:provider:payment_id:
operations:1:provider:auth_code:
  3. Отсортировать полученные строки в естественном порядке:
    account:number:AT0000******2000
customer:id:test@testmail.mail
operations:0:code:0
operations:0:created_date:2025-04-11T05:19:57+0000
operations:0:date:2025-04-11T05:22:03+0000
operations:0:id:9529253065607
operations:0:message:Success
operations:0:provider:auth_code:
operations:0:provider:id:1234
operations:0:provider:payment_id:X1E6D23319ETBXT
operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd-00002000
operations:0:status:success
operations:0:sum_converted:amount:22500
operations:0:sum_converted:currency:EUR
operations:0:sum_initial:amount:22500
operations:0:sum_initial:currency:EUR
operations:0:type:sale
operations:1:code:29999
operations:1:created_date:2025-04-11T05:22:03+0000
operations:1:date:2025-04-11T05:22:03+0000
operations:1:id:9529253065608
operations:1:message:Awaiting processing
operations:1:provider:auth_code:
operations:1:provider:id:10001
operations:1:provider:payment_id:
operations:1:request_id:9kLmga7BQwP2X8rT-EyuV3Hn6Zc1Rbd-00002000
operations:1:status:processing
operations:1:sum_converted:amount:22500
operations:1:sum_converted:currency:EUR
operations:1:sum_initial:amount:22500
operations:1:sum_initial:currency:EUR
operations:1:type:payment confirmation
payment:date:2025-04-11T05:22:03+0000
payment:description:
payment:id:abc12345
payment:method:Austrian Banks
payment:status:awaiting confirmation
payment:sum:amount:22500
payment:sum:currency:EUR
payment:type:purchase
project_id:131221
  4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой:
    account:number:AT0000******2000;customer:id:test@testmail.mail;operations:0:code:0;operations:0:created_date:2025-04-11T05:19:57+0000;operations:0:date:2025-04-11T05:22:03+0000;operations:0:id:9529253065607;operations:0:message:Success;operations:0:provider:auth_code:;operations:0:provider:id:1234;operations:0:provider:payment_id:X1E6D23319ETBXT;operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd-00002000;operations:0:status:success;operations:0:sum_converted:amount:22500;operations:0:sum_converted:currency:EUR;operations:0:sum_initial:amount:22500;operations:0:sum_initial:currency:EUR;operations:0:type:sale;operations:1:code:29999;operations:1:created_date:2025-04-11T05:22:03+0000;operations:1:date:2025-04-11T05:22:03+0000;operations:1:id:9529253065608;operations:1:message:Awaiting processing;operations:1:provider:auth_code:;operations:1:provider:id:10001;operations:1:provider:payment_id:;operations:1:request_id:9kLmga7BQwP2X8rT-EyuV3Hn6Zc1Rbd-00002000;operations:1:status:processing;operations:1:sum_converted:amount:22500;operations:1:sum_converted:currency:EUR;operations:1:sum_initial:amount:22500;operations:1:sum_initial:currency:EUR;operations:1:type:payment confirmation;payment:date:2025-04-11T05:22:03+0000;payment:description:;payment:id:abc12345;payment:method:Austrian Banks;payment:status:awaiting confirmation;payment:sum:amount:22500;payment:sum:currency:EUR;payment:type:purchase;project_id:131221
  5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64:
    BpEgi+OOOWeuwoQjEEz6CP3Cwp5UxkxnkibOQSoBDYdcb8ab4CCm4yGxM05A6VK3XUi2hQMXIZGfVm7JLJ0pKw==
  6. Сравнить полученную подпись с проверяемой.

    В данном случае подписи не совпадают, а это значит, что такой ответ недостоверен или ошибочен и должен быть отброшен.

Форма тестирования для ответов через Gate API

Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписанными данными.

Пример для ответа через Data API

Допустим, что надо проверить подпись ответа при следующих условиях:

  • Используемый ключ — secret
  • Тело полученного ответа выглядит так:
    Рис. 3. Тело ответа
    {
  "operations": [
    {
      "project_id": "200",
      "operation_id": "9529253065607",
      "payment_id": "abc12345",
      "operation_type": "sale",
      "operation_status": "success",
      "payment_method_name": "Greek Banks",
      "payment_description": null,
      "operation_created_at": "2025-03-20T14:22:00+0000",
      "operation_completed_at": "2025-03-20T14:22:06+0000",
      "sum_initial": {
        "amount": 1000,
        "currency": "EUR"
      },
      "sum_converted": {
        "amount": 1000,
        "currency": "EUR"
      }
    }
  ],
  "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="
}

Для проверки подписи необходимо:

  1. Удалить из тела ответа параметр signature вместе с его значением:
    {
  "operations": [
    {
      "project_id": "200",
      "operation_id": "9529253065607",
      "payment_id": "abc12345",
      "operation_type": "sale",
      "operation_status": "success",
      "payment_method_name": "Greek Banks",
      "payment_description": null,
      "operation_created_at": "2025-03-20T14:22:00+0000",
      "operation_completed_at": "2025-03-20T14:22:06+0000",
      "sum_initial": {
        "amount": 1000,
        "currency": "EUR"
      },
      "sum_converted": {
        "amount": 1000,
        "currency": "EUR"
      }
    }
  ],
  "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="
}
  2. Заменить пустой строкой данные на четвёртом уровне вложенности:
    {
  "operations": [
    {
      "project_id": "200",
      "operation_id": "9529253065607",
      "payment_id": "abc12345",
      "operation_type": "sale",
      "operation_status": "success",
      "payment_method_name": "Greek Banks",
      "payment_description": null,
      "operation_created_at": "2025-03-20T14:22:00+0000",
      "operation_completed_at": "2025-03-20T14:22:06+0000",
      "sum_initial": {
        "amount": 1000,
        "currency": "EUR"
      },
      "sum_initial":"",
      "sum_converted": {
        "amount": 1000,
        "currency": "EUR"
      }
      "sum_converted":""
    }
  ]
}

  3. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма:

    operations:0:project_id:200
operations:0:operation_id:9529253065607
operations:0:payment_id:abc12345
operations:0:operation_type:sale
operations:0:operation_status:success
operations:0:payment_method_name:Greek Banks
operations:0:payment_description:
operations:0:operation_created_at:2025-03-20T14:22:00+0000
operations:0:operation_completed_at:2025-03-20T14:22:00+0000
operations:0:sum_initial:
operations:0:sum_converted:
  4. Отсортировать полученные строки в естественном порядке:
    operations:0:operation_completed_at:2025-03-20T14:22:00+0000
operations:0:operation_created_at:2025-03-20T14:22:00+0000
operations:0:operation_id:9529253065607
operations:0:operation_status:success
operations:0:operation_type:sale
operations:0:payment_description:
operations:0:payment_id:abc12345
operations:0:payment_method_name:Greek Banks
operations:0:project_id:200
operations:0:sum_converted:
operations:0:sum_initial:
  5. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой:
    operations:0:operation_completed_at:2025-03-20T14:22:06+0000;operations:0:operation_created_at:2025-03-20T14:22:00+0000;operations:0:operation_id:9529253065607;operations:0:operation_status:success;operations:0:operation_type:sale;operations:0:payment_description:;operations:0:payment_id:abc12345;operations:0:payment_method_name:Greek Banks;operations:0:project_id:200;operations:0:sum_converted:;operations:0:sum_initial:
  6. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64:
    Jc57w8OfFEF/FOjemn/3rRp+4U1Krx8AmLhPUW4+MEVJ+hE9ffspLT+NLAjGjVSweLYkOdzFG6xx6O6EFsmyIw==
  7. Сравнить полученную подпись с проверяемой.

    В данном случае подписи не совпадают, а это значит, что такой ответ недостоверен или ошибочен и должен быть отброшен.

Форма тестирования для ответов через Data API

Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписанными данными.

Прим.: При работе с запросами, отправляемыми к платформе через Data API, и ответами на такие запросы необходимо учитывать, что расчётная подпись составляется с ограничением на 3 уровня вложенности и данные на более глубоких уровнях вложенности не принимаются в расчёт.