Skip to main content

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

/v2/Init

POST

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

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

Авторизация

Security

Запрос

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=Y и автоплатеж проводится по карте.

Если передан, в уведомлении будут указаны CustomerKey и его CardId. Подробнее — в методе Получить список карт клиента.

Recurrent

String

Requirements: <= 1 characters, [Y]

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

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

PayType

String

Requirements: [O, T]

Определяет тип проведения платежа:

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

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

Language

String

Requirements: <= 2 characters

Default: ru

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

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

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

NotificationURL

String<uri>

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

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

Подробнее

SuccessURL

String<uri>

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

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

FailURL

String<uri>

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

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

RedirectDueDate

<date-time>

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

Если дата в параметре меньше текущей, оплата по ссылке и QR будет недоступна.

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

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

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

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

DATA

Object

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

Максимальная длина ключа — 20 знаков, значения — 100 знаков.

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

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

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

Пример: notificationEnableSource=T‑Pay.

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

  • значение "none" оставляет форму пустой;
  • указание конкретного CardId (например, "894952") заполняет форму данными передаваемой карты;
  • если параметр отсутствует, передан некорректно или имеет значение null, форма автоматически заполняется данными последней сохранённой карты.

Пример: "DATA": {"DefaultCard":"none"}.

oneOf

additionalProperties

String

OperationInitiatorType

String

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

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

Подробнее о признаке инициатора операции.

  • 0 — обычный платеж;
  • 1 — CIT CC;
  • 2 — CIT COF;
  • R — MIT COF Recurring;
  • I — MIT COF Installment;
  • D — MIT COF Delayed-Charge;
  • N — MIT COF No-Show.

Если передавать значения параметров, которые не соответствуют таблице, 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

Requirements: [bank_paying_agent, bank_paying_subagent, paying_agent, paying_subagent, attorney, commission_agent, another]

Тег ФФД: 1222

Признак агента:

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

OperationName

String

Requirements: <= 24 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

Requirements: [1.2, 1.05]

Default: 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», измените настройки браузера.