Массовые выплаты (1.46)

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

Выплаты на токенизированные карты и отмены выплат не предусмотрены.

Термин	Определение
Клиент	Физлицо, которому бизнес выплачивает деньги на карту или счет
Мерчант	Бизнес, который выплачивает физлицам деньги за оказанную услугу или товар со своего расчетного счета юрлица
Т‑Бизнес	Сервис, помогающий проводить выплату клиенту-физлицу
Эмитент	Банк, выпустивший карту клиента-физлица
А2С	Массовые выплаты физлицам
PCI DSS	Международный стандарт безопасности, созданный для защиты данных банковских карт

Текущие TLS-сертификаты банка могут быть отозваны — в таком случае банк переключится на сертификат Минцифры. Если не выполнить настройку заранее, в момент переключения сертификатов запросы к API будут возвращать ошибку проверки TLS-сертификата (certificate verify failed, unable to get local issuer certificate, PKIX path building failed), и интеграция перестанет работать.

Зачем это нужно

CA/Browser Forum — международная организация, в которую входят крупнейшие центры сертификации и компании, разрабатывающие браузеры, например Google, Apple, Microsoft, Mozilla. CA/Browser Forum ужесточила правила проверки организаций — сертификаты GlobalSign, которые банк использует сейчас, пока действительны, но могут быть отозваны.

Когда это произойдет, банк перейдет на сертификаты Национального удостоверяющего центра Минцифры России (Russian Trusted CA). Рекомендуем выполнить настройку заранее, чтобы переключение прошло для вас незаметно.

Сертификаты Минцифры не входят в доверенные хранилища большинства операционных систем, языковых рантаймов и HTTP-библиотек по умолчанию. Поскольку ваш код обращается к API программно, а не через браузер, добавьте сертификаты в trust store серверного окружения, из которого выполняются запросы.

Вам нужно установить два сертификата:

• Russian Trusted Root CA — корневой;
• Russian Trusted Sub CA — промежуточный.

Шаг 1. Скачайте сертификаты

Скачайте сертификаты с портала Госуслуг. На странице перейдите в раздел для вашей операционной системы и скачайте два файла:

1. russian_trusted_root_ca.cer — корневой сертификат;
2. russian_trusted_sub_ca.cer — промежуточный сертификат.

Проверьте формат файла сертификата. Файлы .cer бывают двух форматов:

• текстового — PEM, который начинается с -----BEGIN CERTIFICATE-----;
• бинарного — DER.

Утилиты update-ca-certificates и keytool принимают только PEM.

DER-файл нужно сконвертировать в PEM:

# Проверить формат
openssl x509 -in cert.cer -noout -text >/dev/null 2>&1 && echo "PEM" || echo "DER (нужна конвертация)"

# Конвертировать DER в PEM
openssl x509 -inform DER -in cert.cer -out cert.pem

Шаг 2. Установите сертификаты

Установите сертификаты для вашего окружения. Если окружений несколько — например, JVM-приложение в Docker, выполните настройку для каждого из них.

Linux (Debian / Ubuntu)

sudo cp russian_trusted_root_ca.pem /usr/local/share/ca-certificates/russian_trusted_root_ca.crt
sudo cp russian_trusted_sub_ca.pem  /usr/local/share/ca-certificates/russian_trusted_sub_ca.crt
sudo update-ca-certificates

Linux (RHEL / CentOS / Alma / Rocky)

sudo cp russian_trusted_*.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Java / JVM

JVM не использует системное хранилище ОС. Рекомендуем создать отдельный truststore, а не изменять cacerts внутри JRE. Изменения в cacerts сбрасываются при обновлении JDK, а в prod-среде на запись в этот файл часто нет прав.

# Создать отдельный truststore и импортировать оба сертификата
keytool -importcert -alias russian_trusted_root \
  -file russian_trusted_root_ca.pem \
  -keystore russian_truststore.jks \
  -storepass <пароль> -noprompt

keytool -importcert -alias russian_trusted_sub \
  -file russian_trusted_sub_ca.pem \
  -keystore russian_truststore.jks \
  -storepass <пароль> -noprompt

Укажите truststore при запуске приложения:

java -Djavax.net.ssl.trustStore=/path/to/russian_truststore.jks \
     -Djavax.net.ssl.trustStorePassword=<пароль> \
     -jar app.jar

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

Путь к стандартному хранилищу зависит от версии JDK:

• Java 8 — $JAVA_HOME/jre/lib/security/cacerts;
• Java 9+ — $JAVA_HOME/lib/security/cacerts.

Python (requests / httpx / aiohttp)

Эти библиотеки используют bundle certifi, а не системное хранилище. Доступны два варианта:

# Через переменные окружения (действуют на весь процесс)
export REQUESTS_CA_BUNDLE=/path/to/russian-trusted-ca-bundle.pem
export SSL_CERT_FILE=/path/to/russian-trusted-ca-bundle.pem

# Или явно в коде
import requests
requests.get("https://securepay.tinkoff.ru/...", verify="/path/to/russian-trusted-ca-bundle.pem")

Node.js

Node.js по умолчанию игнорирует системное хранилище:

NODE_EXTRA_CA_CERTS=/path/to/russian-trusted-ca-bundle.pem node app.js

Docker

Добавляйте сертификаты на этапе сборки образа, а не в рантайме:

COPY russian-trusted-ca-bundle.pem /usr/local/share/ca-certificates/russian-trusted-ca.crt
RUN update-ca-certificates

# Для Node.js и Python внутри контейнера задайте переменные окружения:
ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Windows / .NET / IIS

.NET использует системное хранилище сертификатов Windows. Для установки в хранилище LocalMachine, которое используется сервисами и приложениями, работающими не от имени текущего пользователя, выполните команды:

# PowerShell с правами администратора
Import-Certificate -FilePath "C:\certs\russian_trusted_root_ca.cer" `
  -CertStoreLocation Cert:\LocalMachine\Root

Import-Certificate -FilePath "C:\certs\russian_trusted_sub_ca.cer" `
  -CertStoreLocation Cert:\LocalMachine\CA

Корневой сертификат устанавливается в хранилище Root (доверенные корневые CA), промежуточный — в CA (промежуточные CA). То же самое можно сделать через GUI в certlm.msc. После установки перезапустите пул приложений или сервис.

Шаг 3. Проверьте установку

curl -v https://securepay.tinkoff.ru/
# Ожидаемый результат: SSL certificate verify ok

openssl s_client -connect securepay.tinkoff.ru:443 -servername securepay.tinkoff.ru -showcerts </dev/null
# Флаг -servername (SNI) обязателен: без него на shared-хостинге может вернуться не тот сертификат.
# В цепочке должны присутствовать Russian Trusted Root CA и Russian Trusted Sub CA.

# Проверить срок действия установленного сертификата
echo | openssl s_client -connect securepay.tinkoff.ru:443 -servername securepay.tinkoff.ru 2>/dev/null \
  | openssl x509 -noout -dates

Если в выводе команд сейчас отображается сертификат GlobalSign — переключения еще не было, и банк использует действующий сертификат. Цепочка сменится автоматически в момент перехода. Убедитесь, что в выводе есть SSL certificate verify ok и сертификаты Минцифры уже установлены в вашем окружении.

После установки сертификатов пересоберите и перезапустите сервисы в контейнерах, чтобы изменения вступили в силу.

Частые проблемы

Проблема	Причина	Решение
unable to get local issuer certificate	Не установлен промежуточный сертификат (Sub CA)	Установить оба сертификата
Ошибка сохраняется после update-ca-certificates	Python/Node.js используют собственный bundle	Задать переменные REQUESTS_CA_BUNDLE / NODE_EXTRA_CA_CERTS
В Docker всё падает в рантайме	Сертификат добавлен после сборки	Добавить сертификат на этапе build и пересобрать образ
Работает локально, падает в production	Разные окружения или разные truststore	Выполнить настройку в каждом окружении
update-ca-certificates отработал, но CA не доверяется	Файл в формате DER вместо PEM	Сконвертировать: openssl x509 -inform DER -in cert.cer -out cert.pem
Соединение отклонено при корректно установленном CA	Включён certificate pinning	Обновить pin на новый сертификат
При проверке возвращается не тот сертификат	Не передан SNI	Добавить флаг -servername <домен> в команду openssl s_client
При проверке возвращается сертификат GlobalSign / другой УЦ	Переключение ещё не произошло	Это нормально — сейчас используется действующий сертификат GlobalSign. Цепочка сменится автоматически в момент переключения. Убедитесь, что сертификаты Минцифры уже установлены

Откатить изменения

Если после установки возникли проблемы, удалите добавленные сертификаты:

# Debian / Ubuntu
sudo rm /usr/local/share/ca-certificates/russian_trusted_*.crt && sudo update-ca-certificates --fresh

# RHEL / CentOS
sudo rm /etc/pki/ca-trust/source/anchors/russian_trusted_*.pem && sudo update-ca-trust

# Java — уберите флаги -Djavax.net.ssl.trustStore и -Djavax.net.ssl.trustStorePassword при запуске

# Windows
# Remove-Item Cert:\LocalMachine\Root\<thumbprint>

В целях безопасности запросы на выплаты нужно подписывать электронной цифровой подписью. Можете выбрать удобный для себя вариант – КриптоПро или RSA.

Чтобы сформировать подпись запроса:

1. Соберите массив всех передаваемых параметров в виде пар Ключ-Значение (кроме параметров DigestValue, SignatureValue, X509SerialNumber). Объект DATA также не учитывается. Например:

   [{"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}, {"PaymentId","20150"}]
   

2. Отсортируйте по Ключам с учетом регистра:

   [{"PaymentId","20150"}, {"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}]
   

3. Конкатенируйте значения:

   20150123456789000E2Ctrue
   

4. Вычислите хэш-сумму по алгоритму SHA256 и получите результат в бинарном виде.
5. Закодируйте получившееся в пункте 4 бинарное значение в Base64 и запишите значение в DigestValue.
6. Подпишите получившееся в пункте 4 бинарное значение c помощью RSA-ключа (закрытая часть ключа)* алгоритмом RSA, закодируйте результат в BASE64 и запишите в SignatureValue.

*Инструкция по получению RSA-ключа доступна по ссылке.

Ниже представлены примеры реализации работы с библиотекой:

Язык	Ссылка
Java	https://cdn.tbank.ru/static/documents/rsa-crypto-lib-java-mapi.zip

Чтобы сформировать подпись запроса:

1. Соберите массив всех передаваемых параметров в виде пар Ключ-Значение (кроме параметров DigestValue, SignatureValue, X509SerialNumber). Объект DATA также не учитывается. Например:

   [{"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}, {"PaymentId","20150"}] 
   

2. Отсортируйте по Ключам с учетом регистра:

   [{"PaymentId","20150"}, {"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}]
   

3. Конкатенируйте значения:

   20150123456789000E2Ctrue
   

4. Вычислите хэш-сумму по ГОСТ Р 34.11-2012 256 и получите результат в бинарном виде.

5. Закодируйте получившееся в пункте 4 бинарное значение в Base64 и запишите значение в DigestValue.

6. Подпишите получившееся в пункте 4 бинарное значение по ГОСТ Р 34.11-2012 256, закодируйте результат в Base64 и запишите в SignatureValue.

Инструкция по получению сертификата доступна по ссылке.

Ниже представлены примеры реализации работы с библиотекой КриптоПро (CryptoPro).

Язык	Ссылка	Версия Крипто Про
С#	Поддержка 2012 ГОСТ	КриптоПРО CSP
Java	Поддержка 2012 ГОСТ	КриптоПРО JCP
PHP	Поддержка 2012 ГОСТ	КриптоПРО CSP

Используйте подпись с помощью токена только при работе с 3DS-методами при привязке карт и получении справки по операции

Чтобы сгенерировать подпись запроса, потребуется пароль (параметр Password) от терминала A2C.

1. Соберите массив всех передаваемых параметров в виде пар Ключ-Значение:

   Добавьте в массив только параметры корневого объекта. Объект DATA не участвует в расчете токена.

   [{"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}, {"PaymentId","20150"}]
   

2. Добавьте в массив пару (Password, значение):

   [{"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}, {"PaymentId","20150"}, {"Password","Dfsfh56dgKl"}]
   

3. Отсортируйте массив по Ключам по алфавиту с учетом регистра:

   [{"Password", "Dfsfh56dgKl"}, {"PaymentId","20150"}, {"TerminalKey","123456789000E2C"}, {"isNeedRrn",true}]
   

4. Конкатенируйте значения всех пар:

   Dfsfh56dgKl20150123456789000E2Ctrue
   

5. Вычислите SHA-256 от полученного в предыдущем пункте значения и запишите значение в Token.

Формирование подписи запроса Token завершено.

Для проведения выплат необходимо сохранять данные банковской карты, чтобы клиенту не приходилось заново их вводить. Безопасность нашей формы привязки соответствует стандарту PCI DSS.

Срок жизни формы привязки ограничен и составляет 2 суток.

Статусная схема привязки карт через банковскую форму

Схема отображает порядок вызова методов и статусы привязки карты при использовании формы привязки Банка.

Описание статусов:

• NEW — новая сессия,
• 3DS_CHECKING — отправка клиента на проверку 3DS,
• 3DS_CHECKED — клиент успешно прошел проверку 3DS,
• AUTHORIZING — отправка списания на 0 руб,
• AUTHORIZED — списание на 0 руб прошло успешно,
• COMPLETED — привязка успешно завершена,
• REJECTED — привязка отклонена.

Статусная схема привязки карт через свою форму

Данная схема позволяет использовать вашу форму привязки. В процессе привязки создается идентификатор карты CardId, который привязывается к параметру CustomerKey.

Описание статусов:

• NEW — новая сессия,
• 3DS_CHECKING — отправка клиента на проверку 3DS,
• 3DS_CHECKED — клиент успешно прошел проверку 3DS,
• AUTHORIZING — отправка списания на 0 руб,
• AUTHORIZED — списание на 0 руб прошло успешно,
• COMPLETED — привязка успешно завершена,
• REJECTED — привязка отклонена.

Используйте разные сценарии работы с картами: проверка, привязка, удаление

Получайте уведомления о статусе выполнения метода привязки карты AddCard (успех/неуспех)

Нотификации по http(s)

Результат привязки карты высылается на адрес Notification URL POST-запросом. При использовании формы привязки карты на стороне Т‑Бизнес нотификация отправляется на сайт Мерчанта на адрес Notification URL синхронно и ожидает ответа в течение 10 секунд. После получения ответа или неполучения его за заданное время сервис переадресует Клиента на Success AddCard URL или Fail AddCard URL в зависимости от результата привязки карты.

Если в Notification URL используются порты, допустимо использование порта 443 (HTTPS). Актуальный список внешних сетей, используемых Т‑Банком, для отправки нотификаций:

• 91.194.226.0/23,
• 91.218.132.0/24,
• 91.218.133.0/24,
• 91.218.134.0/24,
• 91.218.135.0/24,
• 212.49.24.0/24,
• 212.233.80.0/24,
• 212.233.81.0/24,
• 212.233.82.0/24,
• 212.233.83.0/24,
• 91.194.226.181 (тестовая среда).

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

URL: Notification URL

Наименование	Тип	Описание
TerminalKey	String	Идентификатор терминала. Выдается мерчанту в Т‑Бизнес при заведении терминала
CustomerKey	String	Идентификатор клиента в системе Мерчанта
RequestKey	String	Идентификатор запроса на привязку карты
Success	bool	Успешность прохождения запроса
Status	String	Статус привязки
PaymentId	Number	Идентификатор транзакции в системе Т‑Бизнес
ErrorCode	String	Код ошибки. «0» в случае успеха
CardId	Number	Идентификатор привязанной карты
Pan	String	Маскированный номер карты
ExpDate	String	Срок действия карты. Параметр возвращается пустым для привязок с "CheckType": "NO".
NotificationType	String	Тип нотификации, всегда константа «LINKCARD»
RebillId	String	Идентификатор рекуррентного платежа
Token	String	Подпись запроса. Формируется по такому же принципу, как и в случае запросов в Т‑Бизнес

Статусы привязок, по которым приходят http(s)-нотификации:

Status	Описание
COMPLETED	Карта успешно привязана
REJECTED	Привязка карты неуспешна

Пример http(s)-нотификации:

{
  "TerminalKey":"123456789000E2C",
  "CustomerKey":"5b718a19-2abe-1147-a7d9-b43b198ceee3",
  "RequestKey":"acdad9d1-1847-4bdcb743-db86d75253f8",
  "Success":true,
  "Status":"COMPLETED",
  "PaymentId":"700000198023",
  "ErrorCode":"0",
  "CardId":70000000707,
  "Pan":"532130******1359",
  "ExpDate":"1122",
  "NotificationType":"LINKCARD",
  "RebillId":"700000004090",
  "Token":"f2fdd7fec8225872590e1558b7ea258c75df8f300d808006c41ab540dd7514d9"
}

Проверить токен нотификации

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

Параметры, которые используются Т‑Бизнес при формировании токена нотификации о результате привязки карты:

• TerminalKey,
• CustomerKey,
• RequestKey,
• Success,
• Status,
• PaymentId,
• ErrorCode,
• CardId,
• Pan,
• ExpDate,
• NotificationType,
• RebillId – параметр передается, если был присвоен во время привязки.

Ответ на HTTP(s)-нотификацию

Для успешной обработки нотификации Мерчанту необходимо вернуть ответ HTTP CODE = 200 и с телом сообщения: OK (без тегов и заглавными английскими буквами)

Если ответ «OK» не получен, нотификация считается неуспешной, и сервис будет повторно отправлять данную нотификацию раз в час в течение 24 часов.
Если нотификация за это время не доставлена, она будет сложена в архив

PHP. Пример ответа на http(s)-нотификацию

<?php echo «OK»;?>

Java. Пример ответа на http(s)-нотификацию

@POST
@Path("/ok")
public Response NotifyResponse() {
return Response.status(200).entity("OK").build();
}

Уведомляет об успешных/ошибочных выплатах по номеру телефона получателя по http(s)*

*Отправка нотификаций о привязке счета по номеру телефона выполняется аналогично Нотификациям о привязке карты

URL: Notification URL

Наименование	Тип	Описание
TerminalKey	String	Идентификатор терминала, выдается Мерчанту в Т‑Бизнес
OrderId	String	Уникальный номер заказа в системе Мерчанта
Success	bool	Успешность прохождения запроса
Status	String	Статус операции
PaymentId	Number	Идентификатор транзакции в системе Т‑Бизнес
ErrorCode	String	Код ошибки. «0» в случае успеха
Amount	Number	Сумма в копейках.
Token	String	Подпись запроса
SbpId	String	Идентификатор транзакции в СБП
Phone	String	Маскированный номер телефона

Статусы привязок, по которым приходят http(s)-нотификации:

Status	Описание
COMPLETED	Выплата успешно проведена
REJECTED	Выплата неуспешна

Пример http(s)-нотификации:

{
  "TerminalKey": "123456789000E2C",
  "OrderId": "39724",
  "Success": true,
  "Status": "COMPLETED",
  "PaymentId": "5149251283",
  "ErrorCode": "0",
  "Amount": "350190",
  "Token": "3b12c92c0f09dbf1da20f951e8bd0c5d2a39986a2cfc964624d37aae82ce4713",
  "SbpId": "B4163074446157090000120011270501",
  "Phone": "+7(999)*--99"
}

Проверить токен нотификации

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

Параметры, которые используются Т‑Бизнес при формировании токена нотификации о результате выплаты:

• TerminalKey,
• OrderId,
• Success,
• Status,
• PaymentId,
• ErrorCode,
• Amount.

Ответ на HTTP(s)-нотификацию

Для успешной обработки нотификации Мерчанту необходимо вернуть ответ HTTP CODE = 200 и с телом сообщения: OK (без тегов и заглавными английскими буквами).

Если ответ «OK» не получен, нотификация считается неуспешной, и сервис будет повторно отправлять данную нотификацию раз в час в течение 24 часов.
Если нотификация за это время не доставлена, она будет сложена в архив.

PHP. Пример ответа на http(s)-нотификацию

<?php echo «OK»;?>

Java. Пример ответа на http(s)-нотификацию

@POST
@Path("/ok")
public Response NotifyResponse() {
return Response.status(200).entity("OK").build();
}

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

Выплата осуществляется вызовом методов с передачей параметров в GET или POST запросах, в зависимости от сценария. Все методы и передаваемые параметры чувствительны к регистру. Порядок передачи параметров в запросе значения не имеет.

Для POST-запроса в заголовке должен присутствовать Content-Type: application/json.

На схеме показаны статусы операции и возможные методы, которые могут быть вызваны, в зависимости от статуса

Полный список возможных статусов операции:

• NEW — новая сессия,
• AUTHORIZING — авторизация,
• UNKNOWN — статус не определен,
• CHECKING — проверка данных,
• CREDIT_CHECKING — на стадии обработки,
• COMPLETING — операция выполняется,
• REJECTED — операция отклонена. См. Коды ошибок (конечный статус для Init/Payment),
• CHECKED — проверка прошла успешно (конечный статус для Init),
• COMPLETED — операция успешно выполнена (конечный статус для Payment).

Выплата осуществляется вызовом методов с передачей параметров POST запросах. Все методы и передаваемые параметры чувствительны к регистру. Порядок передачи параметров в запросе значения не имеет.

Для POST-запроса в заголовке должен присутствовать Content-Type: application/json.

Чтобы совершить выплату по номеру телефона:

1. Вызовите метод Иниицировать выплату.
2. Вызовите метод Пополнить счет по номеру телефона.
3. При успешном сценарии операция перейдет в статус COMPLETED.
4. При неуспешном — перейдет в статус REJECTED. Список кодов ошибок.

Особенности выплат через СБП:

• вызов метода Пополнить счет по номеру телефона до перехода выплаты в статус CHECKED вернет ошибку;
• метод Пополнить счет по номеру телефона вызывается в течение 180 секунд после перехода операции в статус CHECKED. По истечении этого срока операция сменит статус на REJECTED.

Поддержка методов из этой коллекции прекратится в 2027 году. Используйте новые методы.

Выплата осуществляется вызовом методов с передачей параметров POST запросах. Все методы и передаваемые параметры чувствительны к регистру. Порядок передачи параметров в запросе значения не имеет.

Для POST-запроса в заголовке должен присутствовать Content-Type: application/json.

Поддержка методов из этой коллекции прекратится в 2027 году. Используйте новые методы.