Инструкция Тинькофф Бизнес API на примере платежей

• Платеж через API со счета на счет
  • Выпуск токена
  • Выпуск/перевыпуск сертификата
  • Код осуществления платежа
  • Лимиты
• API для перевода с карты на карту
• Резюме

Поступил заказ на интеграцию CRM клиента с банком Тинькофф. Клиент хотел осуществлять платежи по одному клику мыши в своей CRM. На первый взгляд ничего сложного ...

100 строк кода за час, несколько дней возни с документами и переписка/созвон с ТП банка ...

Эта инструкция позволит облегчить путь интеграции.

У банка Тинкофф для организаций есть специальное Бизнес API (малоинформативная ссылка) с документацией и песочницей где можно проводить тестовые запросы, так же есть телеграм канал, в котором разработчики пишут об обновлениях и получают обратную связь от пользователей API.

Кстати, за время интеграции клиента Бизнес API успело обновиться и поле executionOrder в запросе платежа более не используется.

#Платеж через API со счета на счет

#Выпуск токена

Сначала нужно выпустить токен.

Токен нужно выпускать от лица уполномоченного на осуществление платежей в компании.

Для этого нужно получить право подписи, детали можно просмотреть в профиле сотрудника в разделе Право подписи.

Без права подписи можно через API осуществлять платежи, как бы странно это не показалось, и на первый взгляд будет казаться что все нормально, запрос успешно пройдет, будет получен 201 код ответа, в течении некоторого времени статус платежа будет IN_PROGRESS, а потом:

{
	"status":"FAILED",
	"errorMessage":"Произошла техническая ошибка. Обратитесь в службу поддержки Tinkoff API или к персональному менеджеру"
}

Говорить на эту тему с менеджером бесполезно, внятный ответ намек на ответ удалось получить только при переписке с openapi@tinkoff.ru:

Проверьте, пожалуйста, в ЛК лимиты на переводы по пользователям.

А причина проблемы в отсутсвии права подписи!

В моем случае права подписи не было, и в общем-то не нужно было, потому что я лишь осуществлял интеграцию. Специалист поддержки банка по Бизнес продуктам посоветовал выпускать токен директору (кстати это был один из немногих полезных советов для скорейшего завершения интеграции).

Внимательный читатель задаст вопрос: как мне удалось выпустить токен без права подписи с правом осуществления платежей пусть и не успешных если на осуществление платежей нужно право подписи?

Да, ситуация мутная, это меня сбило с толку ...

С самого начала у меня не было доступа к разделу интеграций, через менеджера и заказчика удалось получить доступ (пожалуй это было единственная быстрая помощь со стороны поддержки клиентов банка).

При генерации токена также требуется участие менеджера, так как нельзя просто так взять и отметить разрешение на осуществление платежей токену.

Но без права подписи это бесполезно и даже запутывает, так как даже если и удастся отправить запрос на осуществление платежа, платеж не пройдет.

#Выпуск/перевыпуск сертификата

Для некоторых методов (платежи как раз в этой категории) Бизнес API Тинькофф использует Mutual TLS (аутентификацию клиента с использованием ssl) в качестве дополнительной меры безопасности. При этом сертификат выпускается всего-лишь на 1 год.

Если сделать запрос без сертификата то будет такой ответ:

400 no required ssl certificate was sent.

В инструкции по выпуску сертификата подробно расписано что нужно сделать. Коротко:

• сгенерировать CSR (с приватным ключом),
• заполнить заявление
• отправить заявление и request.csr на openapi@tinkoff.ru

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

Если сделать наоборот, то при запросе платежа через API будет такой ответ:

403 Неправильный Tls сертификат.

Но если все-таки сначала был выпущен сертикат, а затем токен, то необходимо запросить новый сертифкат. Для этого нужно пройти все шаги выпуска сертификата заного, старый request.csr не пройдет, нужен новый.

Так случилось у меня. Точнее изначально был сгенерирован токен с моего аккаунта сотрудника, но так как у меня нет права подписи, то платежи не удавалось провести. Лишь потом удалось выяснить что проще сгенерировать токен от генерального директора и использовать его. Но убедить банк в перевыпуске сертификата было не просто, для чего потребовалось 3 письма:

• первый раз был отправлен старый request.csr, но в заявлении был указан перевыпуск, на что получил ответ:

Если вам нужен новый сертификат, тогда нужно идти повторить все шаги для выпуска сертификата.

• затем я сгенерировал новый request.csr на что банк ответил:

По этим данным уже был выпущен сертификат. Прикладываю его к письму.

• мне пришлось расписать всю ситуацию в деталях, после чего банк выслал новый сертифкат

#Код осуществления платежа

Это была самая простая часть интеграции :)

Формируем тело в соответствовании с требованиями документации, в названии платежа обязательно нужно указать информацию НДС:

$aBody = [
  'id' => '579314',
  'from' => [
    'accountNumber' => '42801810101102626221'
  ],
  'to' => [
    'name' => 'Фамилия Имя Отчество',
    'inn' => '0000000000', 
    'bik' => '0000000000',
    'bankName' => 'Тинькофф',
    'corrAccountNumber' => '0',
    'accountNumber' => '0'
  ],
  'purpose' => 'Название платежа. НДС не облагается',
  'dueDate' => date(DATE_ATOM, time() + 60*60*24*10),
  'amount' => 10000
];

$sBody = json_encode($aBody, JSON_UNESCAPED_UNICODE);

Теперь используя сертификат и приватный ключ отправляем запрос через curl:

// test
//$sURL = 'https://business.tinkoff.ru/openapi/sandbox/secured/api/v1/payment/ruble-transfer/pay';
//$sToken = 'TinkoffOpenApiSandboxSecretTokenss';

// real
$sURL = 'https://secured-openapi.business.tinkoff.ru/api/v1/payment/ruble-transfer/pay';
$sToken = *;

$hCurl = curl_init();
curl_setopt($hCurl, CURLOPT_SSLCERT, "open-api-cert.pem");
curl_setopt($hCurl, CURLOPT_SSLKEY, "private.key");
curl_setopt($hCurl, CURLOPT_HEADER, 1);
curl_setopt($hCurl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($hCurl, CURLOPT_TIMEOUT, 10);
curl_setopt($hCurl, CURLOPT_URL, $sURL);
curl_setopt($hCurl, CURLOPT_POST, 1);
curl_setopt($hCurl, CURLOPT_POSTFIELDS, $sBody);

curl_setopt(
  $hCurl, 
  CURLOPT_HTTPHEADER, 
  [
    "Authorization: Bearer $sToken",
    "Content-type: application/json; charset=utf-8",
  ]
);

$sResponse = curl_exec($hCurl);
$iCode = curl_getinfo($hCurl, CURLINFO_HTTP_CODE);

exit(print_r([$iCode, $sResponse], true));

В случае успеха код ответа будет 201.

#Лимиты

После подключения следует помнить что есть лимиты на проведение платежей (об этом говорит документация API и поддержка openapi):

• максимальная сумма одного платежа - 100 000 рублей
• максимальная сумма платежей в день - 100 000 рублей
• максимальная сумма платежей в месяц - 1 000 000 рублей
• максимальное количество платежей в день на одного контрагента – 3

Если сразу кинуться осуществлять платежи (как было в моем случае, клиенту очень срочно нужно была выплачивать деньги контрагентам), то можно уперется в лимит, точнее в любой из них.

Изначально сервер банка ответит 201 - поставлено в очередь, но потом может вылезти стена лимитов ... чтобы этого не произошло:

Сразу после подключения Бизнес API (а именно раздела платежей), необходимо подкорректировать лимиты отправив письмо на почту openapi@tinkoff.ru со списком новых лимитов.

#API для перевода с карты на карту

Все попытки узнать у менеджеров про API для перевода в с карты на карту любого банка по номеру карты, закончились провалом. Только переписка с openapi@tinkoff.ru помогла:

Нет, метода перевода с карты на карту нет. Только с расчетного счета на карты Тинькофф, либо через СБП.

#Резюме

Поддержка клиентов в такой узкой теме как API на приемлемом уровне только через openapi@tinkoff.ru.

Нет исчерпывающего руководства для интеграции. В документации Бизнес API не хватает краткой инструкции по токенам и последовательного согласования с сертификатом. Возможно что-то исправят в будущем.

Mutual Tls как дополнительная мера защиты аккаунта клиента понравилась.