Поступил заказ на интеграцию CRM клиента с банком Тинькофф. Клиент хотел осуществлять платежи по одному клику мыши в своей CRM ClientBase. На первый взгляд ничего сложного ...
100 строк кода за час, несколько дней возни с документами и переписка/созвон с ТП банка ... Но прошло 2 года и ситуация изменилась.
У банка Тинкофф для юридических лиц есть специальное Бизнес API с документацией и песочницей где можно проводить тестовые запросы, так же есть телеграм канал, в котором разработчики пишут об обновлениях и получают обратную связь от пользователей 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.
В инструкции по выпуску сертификата подробно расписано что нужно сделать. Коротко:
request.csr
на openapi@tinkoff.ruUPDATE 4.07.2023:
Банк Тинькофф значительно улучшили процедуру выпуска сертификата, теперь его можно выпустить в течении ~10 минут, если есть ЭЦП и навыки ее использования.
Банк может в любой момент отозвать токен если есть подозрения на нелигитимность действий.
Сотрудники банка связались с моим клиентом для уточнения совершаемых операций. Детали звонка не знаю, не присустствовал, но после этого токен был отозван банком и нам пришлось выпускать новый токен и новый сертификат.
Это была самая простая часть интеграции :)
Формируем тело в соответствовании с требованиями документации, в названии платежа обязательно нужно указать информацию НДС:
$body = [
'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
];
$json = json_encode($body, JSON_UNESCAPED_UNICODE);
Теперь используя сертификат и приватный ключ отправляем запрос через curl:
// test
//$url = 'https://business.tinkoff.ru/openapi/sandbox/secured/api/v1/payment/ruble-transfer/pay';
//$token = 'TinkoffOpenApiSandboxSecretTokenss';
// real
$url = 'https://secured-openapi.business.tinkoff.ru/api/v1/payment/ruble-transfer/pay';
$token = *;
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSLCERT, "open-api-cert.pem");
curl_setopt($ch, CURLOPT_SSLKEY, "private.key");
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt(
$ch,
CURLOPT_HTTPHEADER,
[
"Authorization: Bearer $token",
"Content-type: application/json; charset=utf-8",
]
);
$responseBody = curl_exec($ch);
$responseCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
exit(print_r([$responseCode, $responseBody], true));
В случае успеха код ответа будет 201
.
После подключения следует помнить что есть лимиты на проведение платежей (об этом говорит документация API и поддержка openapi). На старте получили дефолтные значения:
Если сразу кинуться осуществлять платежи (как было в моем случае, клиенту очень срочно нужно было выплачивать деньги контрагентам), то можно уперется в лимит, точнее в любой из них.
Изначально сервер банка ответит 201
- поставлено в очередь, но потом может вылезти стена лимитов ... чтобы этого не произошло:
Сразу после подключения Бизнес API (а именно раздела платежей), необходимо подкорректировать лимиты отправив письмо на почту openapi@tinkoff.ru указав ИНН компании и список новых лимитов.
Все попытки узнать у менеджеров про API для перевода по номеру карты в другой банк, закончились провалом. Только переписка с openapi@tinkoff.ru помогла:
Нет, метода перевода с карты на карту нет. Только с расчетного счета на карты Тинькофф, либо через СБП.
Поддержка клиентов в такой узкой теме как API на приемлемом уровне только через openapi@tinkoff.ru.
UPDATE 4.07.2023:
2 года назад, когда я написал эту статью, уровень документации и поддержки мне не очень понравился, однако сейчас ситуация изменилась в лучшую сторону: перевыпуск токена и сертификата заняла ~30 минут.
Mutual Tls как дополнительная мера защиты аккаунта клиента понравилась.