Skip to main content

Инициировать платеж

/v2/Init

POST

https://securepay.tinkoff.ru/v2/Init

Метод инициирует платеж.

Авторизация

Security

Bearer API Token

Запрос

Request body schema application/json

Required

TerminalKey

String

Requirements: <= 20 characters

Идентификатор терминала. Выдается мерчанту в Т‑Бизнес при заведении терминала.

Required

Amount

Number

Requirements: <= 10 characters

  • Сумма в копейках. Например, 3 руб. 12коп. — это число 312.
  • Параметр должен быть равен сумме всех параметров Amount, переданных в объекте Items.
  • Минимальная сумма операции с помощью СБП составляет 10 руб.

Required

OrderId

String

Requirements: <= 36 characters

Идентификатор заказа в системе мерчанта. Должен быть уникальным для каждой операции.

Required

Token

String

Подпись запроса. Формируется по инструкции.

Description

String

Requirements: <= 140 characters

Описание заказа. Значение параметра будет отображено на платежной форме.

Для привязки и одновременной оплаты по СБП поле обязательное. При оплате через СБП эта информация отобразится в мобильном банке покупателя.

CustomerKey

String

Requirements: <= 36 characters

Идентификатор клиента в системе мерчанта.

  • Параметр обязательный, если передан параметр Recurrent.
  • Если был передан в запросе, в нотификации будет указан CustomerKey и его CardId. Подробнее — в методе Получить список карт клиента.
  • Нужен для сохранения карт на платежной форме — платежи в один клик.
  • Необязателен при рекуррентных платежах через СБП.

Recurrent

String

Requirements: <= 1 characters

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

Если передается и установлен в Y, регистрирует платеж как рекуррентный. В этом случае после оплаты в нотификации на AUTHORIZED будет передан параметр RebillId для использования в методе Автоплатеж. Для привязки и одновременной оплаты по CБП передавайте Y.

Значение зависит от параметров OperationInitiatorType и Recurrent в методе Инициировать платеж.

PayType

String

Requirements: [O, T]

Определяет тип проведения платежа — двухстадийная или одностадийная оплата:

  • O — одностадийная оплата;
  • T — двухстадийная оплата.

Если параметр передан — используется его значение, если нет — значение из настроек терминала.

Language

String

Requirements: <= 2 characters

Язык платежной формы:

  • ru — русский;
  • en — английский.

Если параметр не передан, форма откроется на русском языке.

NotificationURL

String<uri>

URL на веб-сайте мерчанта, куда будет отправлен POST-запрос о статусе выполнения вызываемых методов — настраивается в личном кабинете.
Если параметр:

  • передан — используется его значение;
  • не передан — значение из настроек терминала.

Подробнее в разделе Уведомления об операциях.

SuccessURL

String<uri>

URL на веб-сайте мерчанта, куда будет переведен клиент в случае успешной оплаты — настраивается в личном кабинете.
Если параметр:

  • передан — используется его значение;
  • не передан — значение из настроек терминала.

FailURL

String<uri>

URL на веб-сайте мерчанта, куда будет переведен клиент в случае неуспешной оплаты — настраивается в личном кабинете.
Если параметр:

  • передан — используется его значение;
  • не передан — значение из настроек терминала.

RedirectDueDate

<date-time>

Срок жизни ссылки или динамического QR-кода СБП, если выбран этот способ оплаты.

Если текущая дата превышает дату, которая передана в этом параметре, ссылка для оплаты или возможность платежа по QR-коду становятся недоступными и платеж выполнить нельзя.

  • Минимальное значение — 1 минута от текущей даты.
  • Максимальное значение — 90 дней от текущей даты.
  • Формат даты — YYYY-MM-DDTHH24:MI:SS+GMT.

Пример даты: 2016-08-31T12:28:00+03:00.

Если параметр не передан, принимает значение 24 часа для платежа и 30 дней для счета.

Выставление счета через личный кабинет
Если параметр RedirectDueDate не был передан, проверяется настроечный параметр платежного терминала REDIRECT_TIMEOUT, который может содержать значение срока жизни ссылки в часах.
Если его значение:

  • больше нуля — оно будет установлено в качестве срока жизни ссылки или динамического QR-кода;
  • меньше нуля — устанавливается значение по умолчанию: 1440 мин. (1 сутки).

DATA

Object

JSON-объект, который позволяет передавать дополнительные параметры по операции и задавать определенные настройки в формате ключ:значение.

Максимальная длина для каждого передаваемого параметра:

  • ключ — 20 знаков;
  • значение — 100 знаков.

Максимальное количество пар ключ:значение — 20.

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

  1. Параметр notificationEnableSource позволяет отправлять нотификации, только если Source платежа входит в перечень указанных в параметре — он также есть в параметрах сессии. Возможные значения — T‑Pay, sbpqr. Пример: notificationEnableSource=TinkoffPay
oneOf

additionalProperties

String

OperationInitiatorType

String

Requirements: [0, 1, 2, R, I]

Признак инициатора операции:

  • 0 — оплата без сохранения реквизитов карты для последующего использования. Сценарий «0 — CIT, Credential-Not-Captured».
  • 1 — используется, если мерчант сохраняет карту. Сценарий «1 — Consumer-Initiated, Credential-Captured».
  • 2 — операция по ранее сохранённой карте, инициирована клиентом. Сценарий «2 — Consumer-Initiated, Credential-on-File».
  • R — повторяющаяся операция по сохранённой карте без графика. Является Merchant Initiated сценарием — «R = Merchant-Initiated, Credential-on-File, Recurring».
  • I — повторяющаяся операция по сохраненной карте в соответствии с графиком платежей для погашения кредита. Является Merchant Initiated сценарием — «I = Merchant-Initiated, Credential-on-File, Installment».

При передаче в объекте DATA параметра OperationInitiatorType учитывайте взаимосвязь его значений:

  • со значением параметра Reccurent в методе Инициировать платеж;
  • со значением параметра RebillId в методе Автоплатеж;
  • с типом терминала, используемом для проведения операций — ECOM или AFT.

Подробная таблица — в разделе Передача признака инициатора операции

Если передавать значения параметров, которые не соответствуют таблице, MAPI вернет ошибку 1126 — несопоставимые значения rebillId или Recurrent с переданным значением OperationInitiatorType.

Receipt

Object

JSON-объект с данными чека. Параметр обязательный, если подключена онлайн-касса.

oneOf

Required

Items

Array of objects ()

Массив позиций чека с информацией о товарах. Количество товаров чеке не более 100.

Required

Name

String

Requirements: <= 128 characters

Тег ФФД: 1030

Наименование товара.

Required

Price

Number

Тег ФФД: 1078

Цена в копейках.

Required

Quantity

Number

Requirements: <= 8 characters

Тег ФФД: 1023

Количество или вес товара. Максимальное количество символов — 8, где:

  • целая часть — не больше 5 знаков;
  • дробная — не больше 3 знаков для Атол и 2 знаков для CloudPayments.

Required

Amount

Number

Requirements: <= 10 characters

Тег ФФД: 1043

Стоимость товара в копейках. Произведение Quantity и Price.

PaymentMethod

String

Requirements: [full_prepayment, prepayment, advance, full_payment, partial_payment, credit, credit_payment]

Default: full_payment

Тег ФФД: 1214

Признак способа расчета. Возможные значения:

  • full_prepayment — предоплата 100%;
  • prepayment — предоплата;
  • advance — аванс;
  • full_payment — полный расчет;
  • partial_payment — частичный расчет и кредит;
  • credit — передача в кредит;
  • credit_payment — оплата кредита.

Если значение не передано, по умолчанию в онлайн-кассу отправляется признак предмета расчета full_payment.

PaymentObject

String

Requirements: [commodity, excise, job, service, gambling_bet, gambling_prize, lottery, lottery_prize, intellectual_activity, payment, agent_commission, composite, another]

Default: commodity

Тег ФФД: 1212

Признак предмета расчета. Возможные значения:

  • commodity — товар;
  • excise — подакцизный товар;
  • job — работа;
  • service — услуга;
  • gambling_bet — ставка азартной игры;
  • gambling_prize — выигрыш азартной игры;
  • lottery — лотерейный билет;
  • lottery_prize — выигрыш лотереи;
  • intellectual_activity — предоставление результатов интеллектуальной деятельности;
  • payment — платеж;
  • agent_commission — агентское вознаграждение;
  • composite — составной предмет расчета;
  • another — иной предмет расчета.

Если значение не передано, по умолчанию в онлайн-кассу отправляется признак предмета расчета commodity.

Required

Tax

String

Requirements: [none, vat0, vat5, vat7, vat10, vat20, vat105, vat107, vat110, vat120]

Тег ФФД: 1199

Ставка НДС. Перечисление со значениями:

  • none — без НДС,
  • vat0 — НДС по ставке 0%;
  • vat5 — НДС по ставке 5%;
  • vat7 — НДС по ставке 7%;
  • vat10 — НДС по ставке 10%;
  • vat20 — НДС по ставке 20%;
  • vat105 — НДС чека по расчетной ставке 5/105;
  • vat107 — НДС чека по расчетной ставке 7/107;
  • vat110 — НДС чека по расчетной ставке 10/110;
  • vat120 — НДС чека по расчетной ставке 20/120.

Ean13

String

Requirements: <= 300 characters

Тег ФФД: 1162

Штрих-код. В зависимости от типа кассы требования к штрих-коду могут отличаться:

  • АТОЛ Онлайн — шестнадцатеричное представление с пробелами. Максимальная длина – 32 байта (^[a-fA-F0-9]{2}$)|(^([afA-F0-9]{2}\s){1,31}[a-fA-F0-9]{2}$).
    Пример: 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00

  • CloudKassir — длина строки: четная, от 8 до 150 байт. То есть от 16 до 300 ASCII символов ['0' - '9' , 'A' - 'F' ] шестнадцатеричного представления кода маркировки товара.
    Пример: 303130323930303030630333435

  • OrangeData — строка, содержащая base64- кодированный массив от 8 до 32 байт.
    Пример: igQVAAADMTIzNDU2Nzg5MDEyMwAAAAAAAQ==

Если в запросе передается параметр Ean13, который не прошел валидацию, то вернется неуспешный ответ с текстом ошибки в параметре message = Неверный параметр Ean13.

ShopCode

String

Код магазина. Для параметра ShopСode нужно использовать значение параметра Submerchant_ID, который возвращается в ответе при регистрации магазинов через XML. Если XML не используется, передавать поле не нужно.

AgentData

Object (AgentData)

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

AgentSign

String

Тег ФФД: 1222

Признак агента. Возможные значения:

  • bank_paying_agent — банковский платежный агент;
  • bank_paying_subagent — банковский платежный субагент;
  • paying_agent — платежный агент;
  • paying_subagent — платежный субагент;
  • attorney — поверенный;
  • commission_agent — комиссионер;
  • another — другой тип агента.

OperationName

String

Requirements: <= 64 characters

Тег ФФД: 1044

Наименование операции.

Параметр обязательный, если AgentSign передан в значениях bank_paying_agent или bank_paying_subagent.

Phones

Array

Requirements: <= 19 characters

Тег ФФД: 1073

Телефоны платежного агента в формате +{Ц}.

Параметр обязательный, если AgentSign передан в значениях:

  • bank_paying_agent;
  • bank_paying_subagent;
  • paying_agent;
  • paying_subagent.

ReceiverPhones

Requirements: <= 19 characters

Тег ФФД: 1074

Телефоны оператора по приему платежей в формате +{Ц}.

Параметр обязательный, если AgentSign передан в значениях paying_agent или paying_subagent.

TransferPhones

Requirements: <= 19 characters

Тег ФФД: 1075

Телефоны оператора перевода в формате +{Ц}.

Параметр обязательный, если AgentSign передан в значениях bank_paying_agent или bank_paying_subagent.

OperatorName

String

Requirements: <= 64 characters

Тег ФФД: 1026

Наименование оператора перевода.

Параметр обязательный, если AgentSign передан в значениях bank_paying_agent или bank_paying_subagent.

OperatorAddress

String

Requirements: <= 243 characters

Тег ФФД: 1005

Адрес оператора перевода.

Параметр обязательный, если AgentSign передан в значениях bank_paying_agent или bank_paying_subagent.

OperatorInn

String

Requirements: <= 12 characters

Тег ФФД: 1016

ИНН оператора перевода. Параметр обязательный, если AgentSign передан в значениях bank_paying_agent или bank_paying_subagent.

SupplierInfo

Object (SupplierInfo)

Данные поставщика платежного агента. Параметр обязательный, если передается значение AgentSign в объекте AgentData.

Phones

Array

Requirements: <= 19 characters

Тег ФФД: 1171

Телефон поставщика в формате +{Ц}. Параметр обязательный, если передается значение AgentSign в объекте AgentData.

Name

String

Requirements: <= 239 characters

Тег ФФД: 1225

Наименование поставщика. Параметр обязательный, если передается значение AgentSign в объекте AgentData. Состоит из 239 символов, в которые включаются телефоны поставщика — + 4 символа на каждый телефон.

Например, если передано два телефона поставщика длиной 12 и 14 символов, максимальная длина наименования поставщика будет 239 – (12 + 4) – (14 + 4) = 205 символов.

Inn

String

Requirements: >= 10 characters and <= 12 characters

Тег ФФД: 1226

ИНН поставщика в формате ЦЦЦЦЦЦЦЦЦЦ. Параметр обязательный, если передается значение AgentSign в объекте AgentData.

FfdVersion

String

Версия ФФД. Возможные значения: 1.2 или 1.05.

Версия ФФД по умолчанию — 1.05.

Email

String<email>

Requirements: <= 64 characters

Тег ФФД: 1008.

Электронная почта клиента. Параметр обязательный, если не передан Phone.

Phone

String

Requirements: <= 64 characters

Тег ФФД: 1008.

Телефон клиента в формате +{Ц}. Параметр обязательный, если не передан Email.

Required

Taxation

String

Requirements: [osn, usn_income, usn_income_outcome, esn, patent]

Тег ФФД: 1055.

Система налогообложения. Возможные значения:

  • osn — общая СН;
  • usn_income — упрощенная СН (доходы);
  • usn_income_outcome — упрощенная СН (доходы минус расходы);
  • esn — единый сельскохозяйственный налог;
  • patent — патентная СН.

Payments

Object (Payments)

Детали платежа.

Если объект не передан, автоматически указывается итоговая сумма чека с видом оплаты «Безналичный».

Если передан объект receipt.Payments, значение в Electronic должно быть равно итоговому значению Amount в методе Инициировать платеж. При этом сумма введенных значений по всем видам оплат, включая Electronic, должна быть равна сумме (Amount) всех товаров, которые были переданы в объекте receipt.Items.

Cash

Number

Requirements: <= 14 characters

Тег ФФД: 1031.

Вид оплаты «Наличные». Сумма к оплате в копейках.

Required

Electronic

Number

Requirements: <= 14 characters

Тег ФФД: 1081.

Вид оплаты «Безналичный».

AdvancePayment

Number

Requirements: <= 14 characters

Тег ФФД: 1215.

Вид оплаты «Предварительная оплата (Аванс)».

Credit

Number

Requirements: <= 14 characters

Тег ФФД: 1216.

Вид оплаты «Постоплата (Кредит)».

Provision

Number

Requirements: <= 14 characters

Тег ФФД: 1217.

Вид оплаты «Иная форма оплаты».

Shops

Array of objects ()

JSON-объект с данными маркетплейса. Параметр обязательный для маркетплейсов.

Required

ShopCode

String

Код магазина.

Required

Amount

Number

Cумма в копейках, которая относится к указанному ShopCode.

Name

String

Requirements: <= 128 characters

Наименование товара.

Fee

String

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

Descriptor

String

Динамический дескриптор точки.

Ответ

200

OK

Это полезный материал?

Обратиться в поддержку
Loading...

openapi@tbank.ru

APIСценарииПодключение
Все сервисы T-API

АО «ТБанк» использует файлы «cookie» с целью персонализации сервисов и повышения удобства пользования веб-сайтом. «Cookie» представляют собой небольшие файлы, содержащие информацию о предыдущих посещениях веб-сайта. Если вы не хотите использовать файлы «cookie», измените настройки браузера.