TACAP API | T-Bank Dev Portal

Version: 1.0

TACAP API

Для всех методов требуется формирование и проверка подписи запроса.

Request. Логика расчета подписи

Формируется stringToSign с конкатенацией параметров соответствующего интеграционного JSON-запроса, которые входят в перечень участвующих в расчёте подписи атрибутов и значения которых не пустые (!= null || != Ø), через разделитель &: param1=value1&param2=value2&…&paramM=valueM, где:

param – атрибут JSON-сообщения.
value – значение атрибута.

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

agentId, body, currency, mchId, merchantAddress, merchantName, method, notifyUrl, oriTransactionNo, outTransactionNo, qrcId, signType, subject, terId, timeStart, totalAmount, tradeType, version

Замечания относительно поля method:

поле в любом случае участвует в формировании строки, даже если не передано в явном виде в теле запроса;
используется одно из возможных значений поля в нижнем регистре: qrpay, query, refund, cancel, auto_cancel, register, 'pay'.

Замечания относительно поля totalAmount:

при формировании stringToSign, значение поля totalAmount всегда указывается с дробной частью (2 знака после запятой)
если в теле запроса totalAmount: "1500.5", то в stringToSign будет так: ...&totalAmount=1500.50&...
если в теле запроса totalAmount: "1000", то в stringToSign будет так: ...&totalAmount=1000.00&...

К итоговой строке применяется hash-функция HMAC_SHA256 и ее результат используется в качестве цифровой подписи запроса: sign = HMAC_SHA256(stringToSign, signKey), где:

signKey – уникальный ключ POS-устройства, загрузка которого осуществляется при первичной подготовке в рамках взаимодействия с сервисом параметризации (TMS).
Перед шифрованием ключ переводится в массив байтов (base64).
Строка кодируется в формате HEX.

Response. Логика расчета подписи

Формируется stringToSign с конкатенацией параметров соответствующего интеграционного JSON-сообщения с ответом от QRPAY, которые входят в перечень участвующих в расчёте подписи атрибутов и значения которых не пустые (!= null || != Ø), через разделитель &: param1=value1&param2=value2&…&paramM=valueM, где:

param – атрибут JSON-сообщения.
value – значение атрибута.

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

activeUntil, agentId, code, codeUrl, currency, mchId, merchantAddress, merchantName, method, msg, outTradeNo, outTransactionNo, qrcId, signType, terId, timeStart, totalAmount, tradeTime, tradeType, transactionNo, version

Замечания относительно поля method:

поле в любом случае участвует в формировании строки, даже если не передано в явном виде в теле запроса;
используется одно из возможных значений поля в нижнем регистре: qrpay, query, refund, cancel, auto_cancel, register

Замечания относительно поля totalAmount:

при формировании stringToSign, значение поля totalAmount всегда указывается с дробной частью (2 знака после запятой)
если в теле запроса totalAmount: "1500.5", то в stringToSign будет так: ...&totalAmount=1500.50&...
если в теле запроса totalAmount: "1000", то в stringToSign будет так: ...&totalAmount=1000.00&...

signKey – уникальный ключ POS-устройства (base64), загрузка которого осуществляется при первичной подготовке в рамках взаимодействия с сервисом параметризации (TMS).
Перед шифрованием ключ переводится в массив байтов (base64).
Строка кодируется в формате HEX.

Особенности расчёта подписи с вложенным списком.

При создании подписи для json, содержащего список объектов, необходимо сначала произвести отдельно приведение к отсортированной строке вида param1=value1&param2=value2 каждого объекта, а затем всего сообщения целиком.

Для сообщения вида:

{
  "operations": [
    {
      "paymentId": 228049970,
      "source": QRPAY_SBP,
    },
    {
      "paymentId": 209904593,
      "source": POSAPI,
    }
  ],
  "success": true,
  "code": 0,
  "message": "ok"
}

Сначала приводится к строке каждый объект списка operations:

paymentId=228049970&source=QRPAY_SBP и paymentId=209904593&source=POSAPI,

формируется список operations с префиксом «[», постфиксом «]» и разделителем «,»

operations=[paymentId=228049970& source=QRPAY_SBP,paymentId=209904593& source=POSAPI]

и получившийся param=value параметр

stringToSign = 'code=0&message=ok&operations=[paymentId=228049970&source=QRPAY_SBP,paymentId=209904593&source=POSAPI]&success=true'

сортируется и хэшируется с остальным сообщением HMAC_SHA256(stringToSign, signKey)

Как подготовить уникальный ключ (signKey) к подписанию

Ключ выдается в виде строки в формате base64, пример: x0s9dqRQRK0kVoUhjfJzb4r7nexjS9XGxsZsXvQD2LQ=

Нужно перевести ключ из строкового представления в массив байтов
Далее массив байтов нужно перекодировать в HEX формат (шестнадцатеричное представление массива байтов)
После проделанных действий получится строка в HEX формате, именно эту строку надо использовать в signKey для подписи запроса или проверки подписи ответа

Перечень возможных кодов в ответе от хоста

Список возможных значений параметра code в ответе от хоста

SUCCESS - Транзакция одобрена
USINGPAY - В обработке (требуется повторить запрос статуса транзакции)
UNKNOWN - Неизвестный статус (требуется повторить запрос статуса транзакции). Может означать ошибку одного из сторонних сервисов, с которыми взаимодействует хост. Если код получен после вызова /query, то нужно повторить запрос.
SIGNERROR - Ошибка расчета подписи
TOKENINVALIDATE - Ошибка валидации токена
ATTESTATIONEXPIRED - Ошибка времени проведения аттестации
UNKNOWNCODE - Не удается идентифицировать источник штрих-кода
AMOUNTEXCEED - Сумма превышает ограничение
TRANSCLOSE - Транзакция закрыта. При вызове метода /refund такой статус означает, что для операции уже есть незавершённый возврат. При вызове метода /query статус означает, что платеж отклонён системой (то есть платёж не был проведён).
MERNOBLOCKED - Номер продавца заморожен
INVALIDSTORE - Неверный номер терминала
INVALIDMERNO - Неверный номер продавца
PARAMETERERROR - Один из параметров передан неправильно или обязательный параметр не передан
FAIL - Ошибка, невозможно провести операцию с заданными параметрами

Если после вызова метода /qrpay не вернулся успешный статус SUCCESS, то отмена платежа не требуется