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

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

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

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

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

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

[{"TerminalKey","TinkoffBankTest"}, {"isNeedRrn",true}, {"PaymentId","20150"}]

2. Сортировать по Ключам с учетом регистра:

[{"PaymentId","20150"}, {"TerminalKey","TinkoffBankTest"}, {"isNeedRrn",true}]

3. Конкатенировать значения:

20150TinkoffBankTesttrue

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

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

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

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

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

   [{"TerminalKey","TinkoffBankTest"}, {"isNeedRrn",true}, {"PaymentId","20150"}] 
   

2. Сортировать по Ключам с учетом регистра:

   [{"PaymentId","20150"}, {"TerminalKey","TinkoffBankTest"}, {"isNeedRrn",true}]
   

3. Конкатенировать значения:

   20150TinkoffBankTesttrue
   

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

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

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

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

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

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

Для генерации подписи используется пароль (параметр Password) от терминала A2C

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

   В массив нужно добавить только параметры корневого объекта. Вложенные объекты и массивы не участвуют в расчете токена

[{"TerminalKey","TestB"}, {"isNeedRrn",true}, {"PaymentId","20150"}]

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

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

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

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

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

Dfsfh56dgKl20150TestBtrue

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

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

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

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

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

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

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

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

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

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

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

• NEW — новая сессия,
• FORM_SHOWED — показ формы привязки карты,
• 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 в зависимости от результата привязки карты.

Если в NotificationURL используются порты, допустимо использование порта 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

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

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

{
  "TerminalKey":"TinkoffBankTest",
  "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"
}

Ответ на 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

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

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

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

Ответ на 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

Перед запуском интеграции важно провести тестирование. Для этого используйте терминал с приставкой E2CDEMO. Запросы по данному терминалу необходимо отправлять на URL: https://securepay.tinkoff.ru/e2c/v2/

Сценарии, доступные для тестирования на E2CDEMO терминале:

1. Добавить клиента (методом AddCustomer).
2. Удалить клиента (методом RemoveCustomer).
3. Привязать карту к клиенту (AddCard).
4. Удалить карту (RemoveCard).
5. Показать списков всех карт клиента (GetCardList).
6. Проверить нотификации после привязки.
7. Провести успешную выдачу на привязанную карту (Payment).
8. Проверить статус операции.
9. Провести выдачу с ошибкой.
10. Проверить статус выдачи с ошибкой.

Данные карты необходимо использовать на DEMO-терминале

Выполняется при передаче номера 79012345678 в параметре PhoneNumber метода Init
Последовательность вызовов:
1. Init возвращает Status «CHECKED».
2. Payment возвращает Status «COMPLETING».
3. GetState возвращает Status «COMPLETED».

Выполняется при передаче номера 79021234567 в параметре PhoneNumber метода Init
Последовательность вызовов:
1. Init возвращает Status «CHECKED».
2. Payment возвращает Status «COMPLETING».
3. GetState возвращает Status «COMPLETED».

Выполняется при передаче номера 79031234567 в параметре PhoneNumber метода Init. Эмулирует ошибку «Недостаточно средств на счете»
Последовательность вызовов:
1. Init возвращает Success:false.

Выполняется при передаче номера 79041234567 в параметре PhoneNumber метода Init. Эмулирует ошибку «Недостаточно средств на счете»
Последовательность вызовов:
1. Init возвращает Status «CHECKED».
2. Payment возвращает Status «COMPLETING».
3. GetState возвращает Status «REJECTED».

Для выплат по картам

Для выплат по СБП