Методы

Для работы с заявкой используется четыре основных метода. Они помогут создать заявку, подтвердить, отменить ее и получить актуальный статус

Вы можете отправлять не более 25 запросов в секунду, иначе вернется ошибка. В ответе в заголовке будет Retry-After, количество секунд ожидания и статус — код 429

Статус ответа

200 — в случае успешного сценария
400 — в случае некорректного формата запроса
401 — аутентификация не пройдена: введены неверные логин и/или пароль
403 — авторизация не пройдена: пытаетесь работать с чужой заявкой
422 — ошибка бизнес-логики: в текущем состоянии заявки нельзя выполнить это действие
500 — внутренняя ошибка сервера

Create — создание заявки

POST
https://forma.tinkoff.ru/api/partners/v2/orders/create

Используется для создания реальных заявок. Если вы случайно вызовете этот метод с одинаковым составом заказа, включая его номер в вашей системе orderNumber, новая заявка не будет создана. Вам вернется ссылка на уже созданную заявку

Параметры заявки

Основные
Items
Сontact
Fio

Описание	Параметр
shopId string(50), required	Идентификатор компании
showcaseId string(50), required	Идентификатор магазина, сайта
sum number, required	Общая сумма заказа
items Items[], required	Список товаров Описано в таблице Items
orderNumber string(64), optional	Номер заказа в системе партнера. Обязательный, если используются вебхуки и методы API Commit, Cancel и Info
promoCode string(64), optional	Идентификатор продукта: кредит или рассрочка По умолчанию default
webhookURL string, optional	Ссылка для отправки вебхуков Ссылка на раздел вебхуков
successURL string, optional	Ссылка для возврата в случае успешного завершения заявки — подписания Ссылки возврата
failURL string, optional	Ссылка для возврата в случае неуспешного завершения заявки — отказа банка Ссылки возврата
returnURL string, optional	Ссылка для возврата в случае отмены заявки Ссылки возврата
values object, optional	Данные покупателя для предзаполнения формы
values.contact Contact, optional	Данные покупателя Описано в таблице Contact

Описание	Параметр
name string(255), required	Название товарной позиции
quantity integer, required	Количество единиц товара указанной позиции
price number, required	Цена одной единицы товара
category string(255), optional	Категория товара
vendorCode string(64), optional	Артикул

Описание	Параметр
values.contact.fio FIO, optional	ФИО покупателя Описано в таблице FIO
values.contact.mobilePhone string, optional	Телефон покупателя. Подходит строка с номером телефона РФ в любом формате
values.contact.email string, optional	E-mail покупателя

Описание	Параметр
values.contact.fio.lastName string, optional	Фамилия покупателя
values.contact.fio.firstName string, optional	Имя покупателя
values.contact.fio.middleName string, optional	Отчество покупателя

Параметры ответа

Описание	Параметр
id string, required	ID заявки в TCB
link string, required	Ссылка на заявку в TCB

Пример

BASH

curl -v -XPOST -H 'Content-type: application/json' -d '{
  "shopId": "SHOP_ID",
  "showcaseId": "SHOWCASE_ID",
  "sum": 100000,
  "items": [
    {
      "name": "iPhone",
      "quantity": 1,
      "price": 100000,
      "category": "mobile",
      "vendorCode": "12345"
    }
  ],
  "orderNumber": "1234567890",
  "promoCode": "default",
  "demoFlow": "sms",
  "values": {
    "contact": {
      "fio": {
        "lastName": "Иванов",
        "firstName": "Иван",
        "middleName": "Иванович"
      },
      "mobilePhone": "9998887766",
      "email": "ivan@example.com"
    }
  }
}' 'https://forma.tinkoff.ru/api/partners/v2/orders/create'

Commit — подтверждение заявки

POST
https://forma.tinkoff.ru/api/partners/v2/orders/{orderNumber}/commit

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

Метод должен быть вызван в течение 14 дней после подписания покупателем заявки. Если у вас подключено автоподтверждение заказов, вызывать метод не нужно — заявка подтвердится автоматически

Параметры запроса

Описание	Параметр
orderNumber string, required	Номер заказа
Authorization header, required	Basic Auth

Параметры ответа

Описание	Параметр
id string(64), required	Номер заказа. Соответствует orderNumber, если передается при создании
status enum, required	Статус заявки new — заявка создана, покупатель еще не подтвердил свои данные кодом из СМС inprogress — покупатель подтвердил свои данные вводом кода из СМС (ФИО, номер телефона, e-mail) и находится на шаге ввода данных паспорта либо ожидает одобрения заявки хотя бы от одного банка approved — заявка одобрена хотя бы одним банком signed — заявка подписана покупателем при помощи СМС-кода, Self id или на встрече canceled — заявка отменена покупателем rejected — по заявке пришел отказ от всех банков
created_at string dateTime, required	Дата и время создания заявки
demo boolean, required	Флаг, является ли заявка тестовой
committed boolean, required	Флаг, является ли заявка подтвержденной
first_payment number double	Первоначальный взнос
order_amount number double, required	Сумма заказа
credit_amount number double	Сумма выдаваемого покупателю кредита
transfer_amount number double	Сумма для перевода партнеру
product enum	Тип продукта: кредит — credit. рассрочка — installment_credit
term integer int32	Срок кредита в месяцах
monthly_payment number double	Ежемесячный платеж
first_name string	Имя покупателя
last_name string	Фамилия покупателя
middle_name string	Отчество покупателя
phone string	Телефон покупателя
loan_number string	Номер кредитного договора
email string	E-mail покупателя
appropriate_signing_types string[], required	Доступные покупателю способы подписания: bank — подписание на встрече. sms — подписание через СМС для повторных клиентов банка. ses — подписание по Self id
signing_type string	Актуальный способ подписания заявки. Входит в appropriate_signing_types
chosenBank string	Банк, выдавший кредит. ОТП Банк, Т-Банк или МТС Банк
expected_overdue_at string dateTime, required	Дата и время окончания срока действия заявки
items Items[]	Состав заказа покупателя. Описано в таблице Items

Пример

BASH

curl -v -XPOST -H 'Authorization: Basic <TOKEN>' -H 'Content-type: application/json' 'https://forma.tinkoff.ru/api/partners/v2/orders/{orderNumber}/commit'

Cancel — отмена заявки

POST
https://forma.tinkoff.ru/api/partners/v2/orders/{orderNumber}/cancel

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

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

Параметры запроса

Описание	Параметр
orderNumber string, required	Номер заказа
Authorization header, required	Basic Auth

Параметры ответа

Описание	Параметр
id string(64), required	Номер заказа. Соответствует orderNumber, если передается при создании
status enum, required	Статус заявки new — заявка создана, покупатель еще не подтвердил свои данные кодом из СМС inprogress — покупатель подтвердил свои данные вводом кода из СМС (ФИО, номер телефона, e-mail) и находится на шаге ввода данных паспорта либо ожидает одобрения заявки хотя бы от одного банка approved — заявка одобрена хотя бы одним банком signed — заявка подписана покупателем при помощи СМС-кода, Self id или на встрече canceled — заявка отменена покупателем rejected — по заявке пришел отказ от всех банков
created_at string dateTime, required	Дата и время создания заявки
demo boolean, required	Флаг, является ли заявка тестовой
committed boolean, required	Флаг, является ли заявка подтвержденной
first_payment number double	Первоначальный взнос
order_amount number double, required	Сумма заказа
credit_amount number double	Сумма выдаваемого покупателю кредита
transfer_amount number double	Сумма для перевода партнеру
product enum	Тип продукта: кредит — credit. рассрочка — installment_credit
term integer int32	Срок кредита в месяцах
monthly_payment number double	Ежемесячный платеж
first_name string	Имя покупателя
last_name string	Фамилия покупателя
middle_name string	Отчество покупателя
phone string	Телефон покупателя
loan_number string	Номер кредитного договора
email string	E-mail покупателя
appropriate_signing_types string[], required	Доступные покупателю способы подписания: bank — подписание на встрече. sms — подписание через СМС для повторных клиентов банка. ses — подписание по Self id
signing_type string	Актуальный способ подписания заявки. Входит в appropriate_signing_types
chosenBank string	Банк, выдавший кредит. ОТП Банк, Т-Банк или МТС Банк
expected_overdue_at string dateTime, required	Дата и время окончания срока действия заявки
items Items[]	Состав заказа покупателя. Описано в таблице Items

Пример

BASH

curl -v -XPOST -H 'Authorization: Basic <TOKEN>' -H 'Content-type: application/json' 'https://forma.tinkoff.ru/api/partners/v2/orders/{orderNumber}/cancel'

Info — текущее состояние заявки

GET
https://forma.tinkoff.ru/api/partners/v2/orders/{orderNumber}/info

Метод помогает узнавать актуальный статус заявки. Вы можете использовать его отдельно или в комбинации с HTTP-нотификациями. Тогда обработка заказа с вашей стороны ускорится. Мы рекомендуем всегда проверять актуальный статус заказа методом Info. Делайте это после получения вебхуков от нашей системы или если вебхук не пришел в течение часа после создания заявки.

Параметры запроса

Описание	Параметр
orderNumber string, required	Номер заказа
Authorization header, required	Basic Auth

Параметры ответа

Описание	Параметр
id string(64), required	Номер заказа. Соответствует orderNumber, если передается при создании
status enum, required	Статус заявки new — заявка создана, покупатель еще не подтвердил свои данные кодом из СМС inprogress — покупатель подтвердил свои данные вводом кода из СМС (ФИО, номер телефона, e-mail) и находится на шаге ввода данных паспорта либо ожидает одобрения заявки хотя бы от одного банка approved — заявка одобрена хотя бы одним банком signed — заявка подписана покупателем при помощи СМС-кода, Self id или на встрече canceled — заявка отменена покупателем rejected — по заявке пришел отказ от всех банков
created_at string dateTime, required	Дата и время создания заявки
demo boolean, required	Флаг, является ли заявка тестовой
committed boolean, required	Флаг, является ли заявка подтвержденной
first_payment number double	Первоначальный взнос
order_amount number double, required	Сумма заказа
credit_amount number double	Сумма выдаваемого покупателю кредита
transfer_amount number double	Сумма для перевода партнеру
product enum	Тип продукта: кредит — credit. рассрочка — installment_credit
term integer int32	Срок кредита в месяцах
monthly_payment number double	Ежемесячный платеж
first_name string	Имя покупателя
last_name string	Фамилия покупателя
middle_name string	Отчество покупателя
phone string	Телефон покупателя
loan_number string	Номер кредитного договора
email string	E-mail покупателя
appropriate_signing_types string[], required	Доступные покупателю способы подписания: bank — подписание на встрече. sms — подписание через СМС для повторных клиентов банка. ses — подписание по Self id
signing_type string	Актуальный способ подписания заявки. Входит в appropriate_signing_types
chosenBank string	Банк, выдавший кредит. ОТП Банк, Т-Банк или МТС Банк
expected_overdue_at string dateTime, required	Дата и время окончания срока действия заявки
items Items[]	Состав заказа покупателя. Описано в таблице Items

Пример

BASH

curl -v -H 'Authorization: Basic <TOKEN>' -H 'Content-type: application/json' 'https://forma.tinkoff.ru/api/partners/v2/orders/{orderNumber}/info'

Методы

Статус ответа​

Create — создание заявки​

Параметры заявки​

Параметры ответа​

Пример​

Commit — подтверждение заявки​

Параметры запроса​

Параметры ответа​

Пример​

Cancel — отмена заявки​

Параметры запроса​

Параметры ответа​

Пример​

Info — текущее состояние заявки​

Параметры запроса​

Параметры ответа​

Пример​

Статус ответа

Create — создание заявки

Параметры заявки

Параметры ответа

Пример

Commit — подтверждение заявки

Параметры запроса

Параметры ответа

Пример

Cancel — отмена заявки

Параметры запроса

Параметры ответа

Пример

Info — текущее состояние заявки

Параметры запроса

Параметры ответа

Пример