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

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

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

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

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

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

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

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

   20150TinkoffBankTest
   

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

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

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

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

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

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

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

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

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

   20150TinkoffBankTest
   

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

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

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

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

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

Подпись с помощью токена возможно использовать только при работе с методами выплат через СБП.

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

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

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

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

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

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

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

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

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

   Dfsfh56dgKl20150TestB
   

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

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

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

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

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

Статусная схема привязки карт (PCI DSS)

Данная схема позволяет использовать вашу форму привязки (при наличии сертификации PCI DSS). В процессе привязки создается идентификатор карты 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.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

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

Выплата осуществляется вызовом методов с передачей параметров в 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 возвращает Status «REJECTED»

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

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

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

По техническим вопросам обратитесь на почту acq_help@tinkoff.ru.
Для предоставления обратной связи и по вопросам улучшения обслуживания и предоставляемого сервиса обратитесь к вашему личному менеджеру