Download OpenAPI specification:Download
Интернет-эквайринг помогает принимать онлайн-платежи так, как удобно вам и покупателю: на сайте, в мобильном приложении, соцсетях, мессенджерах, по e-mail или СМС. Вы можете принимать оплату разными способами, возвращать и замораживать выплаты и настраивать рекуррентные платежи.
Чтобы подключить интернет-эквайринг, оставьте заявку на сайте Т‑Банка и заполните анкету компании или ИП. Подробнее о подключении можно прочитать в Т-Помощи или узнать у персонального менеджера.
Интернет-эквайринг нужно интегрировать — настроить оплату на сайте или в приложении. Есть четыре способа интеграции:
Интегрироваться можно самостоятельно или с помощью разработчика.
Способ интеграции интернет-эквайринга с сайтом, который создан на основе CMS.
Модуль подходит, если ваш сайт собран на CMS — например, 1С-Битрикс, WordPress или Taplink. Т‑Касса поддерживает многие популярные CMS, в некоторые уже встроены модули — их устанавливать не нужно.
Принцип работы:
На этой странице представлен список систем управления контентом (CMS), для которых разработаны платежные модули. Если вашего решения нет в этом списке, мы рекомендуем настроить передачу объекта DATA
с параметром connection_type
. В этом параметре укажите название модуля, через который вы интегрируетесь. Более подробную информацию вы можете в описании метода Init. Если у вас возникнут вопросы или потребуется дополнительная настройка, пожалуйста, обратитесь в техническую поддержку вашего модуля.
Инструкции по интеграции с помощью платежного модуля
Способ интеграции интернет-эквайринга с самописным сайтом.
Виджет подходит, если:
Принцип работы:
Для интеграции виджета потребуется помощь программиста.
Инструкция по интеграции с помощью виджета
Способ интеграции интернет-эквайринга с мобильным приложением.
Подключение осуществляется через WebView ПФ.
Самый гибкий и сложный способ интеграции интернет-эквайринга. Например, API подходит, если у вас самописный сайт и вы хотите настроить оплату под запросы бизнеса — совмещать в платежной форме разные способы оплаты, принимать рекуррентные платежи или подключать другие сервисы Т‑Кассы.
Для интеграции понадобится помощь программиста.
Платежная форма — это готовый интерфейс с встроенными способами оплаты, который позволяет принимать платежи онлайн.
Для использования платежной формы нужно подключить интернет-эквайринг, настроить терминал и интегрировать платежную форму на ваш сайт одним из способов выше.
Некоторые WebView не умеют обрабатывать DeepLink-ссылки. Из-за этого способы оплаты, которые выполняют переход в мобильное приложение во время платежа, могут работать некорректно — например, СБП, Mir Pay, T‑Pay.
При использовании платежной формы в WebView нужно учесть особенности вашей интеграции и сделать доработки для поддержки DeepLink.
По результатам доработок нужно дополнительно протестировать корректную работу всех способов оплат. Если вы обнаружите проблемы, свяжитесь с разработчиками WebView модуля для их устранения или отключите неработающие способы оплаты.
Примеры решений:
Платформа IOS
Чтобы DeepLink работал в Web, есть два варианта решения:
Пример реализации обработки открытия диплинка Т‑Банка:
navigationDelegate = self
func webView(
_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
) {
if let url = navigationAction.request.url, let scheme = url.scheme {
if scheme != "https" && scheme != "http" {
UIApplication.shared.open(url)
}
}
decisionHandler(.allow)
}
Мы не рекомендуем использовать платежную форму в iframe для мобильных версий сайтов — у кнопочных способов оплаты могут возникать проблемы с открытием DeepLink и переходов в мобильное приложение для оплаты: СБП, Mir Pay, T‑Pay. Это связано с тем, что iframe — изолированный контейнер. Из-за этого переходы на сторонние ссылки не могут обрабатываться внутри iframe.
Если вам нужно использовать iframe в мобильной версии сайта, сделайте доработки по инструкции ниже, чтобы использовать кнопочные способы оплаты. Это позволит произвести переход в стороннее приложение. Доработки представляют собой скрипт «снаружи» iframe, который получит сообщение о переходе от iframe и вызовет его на основной странице.
После реализации доработок нужно протестировать корректную работу всех способов оплат. Если у вас возникнут проблемы или вопросы, обратитесь в нашу поддержку — acq_help@tbank.ru.
В десктопной версии iframe кнопочные способы оплаты будут работать без специальных доработок.
Если у вас подключены способы оплаты, которые используют DeepLink — T‑Pay, СБП или Mir Pay — в процессе оплаты может возникать ошибка.
Про скрипт
Скрипт общается с фреймом через window.postMessage().
Добавление скрипта помогает решить проблему передачи ссылки на ресурс платежного сервиса для способов оплаты, которые используют DeepLink.
Эта проблема может возникнуть при попытке передачи ссылки в браузер клиента из контейнера платежной формы, который расположен в теге <iframe>
.
Установка
Мы не рекомендуем полностью копировать скрипт в свою сборку. Интерфейс общения с платежной формой может измениться — поэтому всегда загружайте скрипт из файла.
Простая интеграция — если используется уже созданный iframe на странице
Добавьте ссылку на код скрипта iframe.js
в HTML-код страницы сайта, на которой располагается iframe c платежной формой.
Рекомендуем разместить его в конце body
после объявления тега iframe
.
<iframe id="payment-form"></iframe>
<script src="https://kassa.cdn-tinkoff.ru/integration/integration.js"></script>
<script>
const paymentForm = new PaymentForm.Integration({iframe: {element: document.getElementById('payment-form')}});
</script>
Динамическая интеграция — если iframe генерируется динамически
<div id="payment-form-container"></div>
<script>
// // Получите и присвойте переменной uuid значение уникального идентификатора платежа — передаётся в path параметра PaymentURL
const uuid = "";
// Получите элемент контейнера, в который будет встроен iframe
const contentContainer = document.getElementById('payment-form-container')
// Загрузите скрипт
const script = document.createElement("script");
script.type = "text/javascript";
script.async = false;
script.src = "https://kassa.cdn-tinkoff.ru/integration/integration.js";
script.onload = (): void => {
// Инициализируйте скрипт
const paymentForm = new PaymentForm.Integration({iframe: {element: document.getElementById('payment-form')}});
// Создайте iframe
const element = document.createElement("iframe");
element.src = "https://securepayments.tinkoff.ru/" + uuid;
if (contentContainer) {
contentContainer.appendChild(element);
}
};
document.getElementsByTagName("body")[0].appendChild(script);
</script>
Настройка
Класс Integration
принимает два аргумента:
HTMLIFrameElement
— iframe DOM-элемент.config
— необязательный аргумент с конфигурацией PaymentFormIntegrationConfig
.PaymentFormIntegrationConfig
:
interface PaymentFormIntegrationConfig {
iframe: {
element: HTMLIFrameElement;
/**
* Используется, если скрипт встраивается в промежуточный iframe
*/
proxy?: true;
/**
* Вызывается в момент получения deepLink из ПФ
* Стандартное значение: (url) => {window.location.href = url}
* @param url
*/
deepLinkRedirectCallback?: (url: string) => void;
/**
* Вызывается в момент получения exit из ПФ
* Например, при нажатии кнопки Вернуться в магазин
* Стандартное значение: (url) => {window.location.href = url}
* @param url
*/
exitRedirectCallback?: (url: string) => void;
};
}
Если вам нужно просто закрыть модальное окно с платежной формой, а не перенаправлять родительскую страницу на возврат в магазин — замените этот параметр конфигурации.
Пример инициализации скрипта с конфигурацией:
const paymentForm = new PaymentForm.Integration({
iframe: {
element: document.getElementById('payment-form'),
exitRedirectCallback: (url) => {
// Вызов закрытия модального окна
}
}
});
iframe внутри iframe
Иногда приложение работает внутри iframe, который находится внутри другого iframe. В этом случае нужно
встроить скрипт с ключом proxy: true
во все промежуточные iframe.
Пример инициализации скрипта для основной страницы:
<iframe id="payment-form"></iframe>
<script src="https://kassa.cdn-tinkoff.ru/integration/integration.js"></script>
<script>
const paymentForm = new PaymentForm.Integration({iframe: {element: document.getElementById('payment-form')}});
</script>
Пример инициализации скрипта для вложенного iframe:
<iframe id="payment-form"></iframe>
<script src="https://kassa.cdn-tinkoff.ru/integration/integration.js"></script>
<script>
const paymentForm = new PaymentForm.Integration({iframe: {element: document.getElementById('payment-form'), proxy: true}});
</script>
Промежуточный скрипт будет передавать сообщения в каждый следующий iframe.
Коллбеки событий будут срабатывать в промежуточных iframe только если они переопределены в конфигурации.
Как работает скрипт
Общение между формой и родителем происходит через window.postMessage().
loaded
.loaded
из платежной формы скрипт отправляет сообщение ready
на платежную форму. Таким образом происходит
рукопожатие, и платежная форма определяет, что может отобразить кнопочные методы оплаты.Платежную форму можно кастомизировать — настроить под себя и своих клиентов. Для установки кастомизации обратитесь к вашему персональному менеджеру и передайте пожелания по настройкам.
Возможности кастомизации | Дополнительное описание |
---|---|
Брендирование UI платежной формы | |
Управление блоком детализации (информация о заказе и магазине) | |
Управление светлой и темной темой |
Убедитесь, что вы используете последнюю версию интеграции и генерируете и передаете корректный токен при любом способе интеграции.
Если ваш сайт собран на CMS, нужно использовать новейшую версию платежного модуля, доступную на сайте Т‑Кассы — это источник актуальных версий. Современные модули для популярных CMS генерируют корректный токен автоматически.
Дополнительные обязательные меры, которые нужно соблюдать при интеграции с MAPI:
Для сверки параметров доступно несколько способов:
Получение уведомлений:
По электронной почте: когда платёж переходит в статус CONFIRMED
, на указанную почту будет отправлено письмо
По HTTP: MAPI отправляет POST-запрос на указанный URL при каждом изменении статуса платежа
Вызов метода GetState:
PaymentId
и Amount
. Особенно важно сравнивать сумму Amount, полученную в уведомлении или через метод GetState, с ожидаемой стоимостью заказа. Это поможет избежать ошибок при обработке платежей.Если вы не применяете эти меры безопасности на вашем сайте или используете программное обеспечение для интеграции не с сайта Т‑Кассы, вы сами отвечаете за возможные риски и неблагоприятные последствия, связанные с использованием такого программного обеспечения.
Платежные системы разработали требования к безопасности карточных данных клиентов — Payment Card Industry Data Security Standard (PCI DSS). Стандарт PCI DSS — это международный стандарт безопасности, созданный специально для защиты данных платежных карт. Он позволяет защитить организацию от инцидентов безопасности и обеспечить необходимый уровень защищенности во всей платежной системе. Соответствовать правилам стандарта PCI DSS должны все организации.
Если:
У вас нет сертификации PCI DSS, вы можете использовать платежную форму Т‑Кассы. В этом случае все операции, которые связаны с обработкой критичных данных, проводятся на стороне Т‑Кассы. Мерчанту достаточно настроить интеграцию с MerchantAPI и инициализировать платеж. Клиент будет перенаправлен на платежную форму, в которую он сможет ввести данные карты. Когда платеж завершится, клиент снова увидит сайт мерчанта.
Вы имеете сертификацию PCI DSS, то можете собирать и хранить карточные данные клиентов. В этом случае MerchantAPI получает зашифрованные карточные данные от мерчанта.
Платежные системы хотят понимать, кем была инициирована карточная операция. Это особенно важно при проведении операций без 3DS и по сохраненным данным.
Для выполнения требования регулятора мы добавили новый атрибут OperationInitiatorType
в метод Init. В значении этого
атрибута мы ожидаем получать признак того, кем была инициирована операция и какой способ предоставления реквизитов был использован.
Подробное описание сценариев проведения операций, значений OperationInitiatorType
, взаимосвязь с другими атрибутами и типами терминалов:
Тип операции и инициатор | Описание | Сценарий карточной операции | OperationInitiatorType | RebillId в /Charge | Recurrent в Init | AFT терминал | ECOM терминал |
---|---|---|---|---|---|---|---|
Сustomer Initiated Credential-Not-Captured (CIT CNC) | Инициированная покупателем оплата без сохранения реквизитов карты для последующего использования. | Стандартный платеж | 0 | null | N | Разрешено | Разрешено |
Сustomer Initiated Credential-Captured (CIT CC) | Инициированная покупателем оплата c сохранением реквизитов карты для последующего использования. | Стандартный платеж с созданием родительского рекуррентного платежа | 1 | null | Y | Разрешено | Разрешено |
Сustomer Initiated Credential-on-File (CIT COF) | Инициированная покупателем оплата по сохраненным реквизитам карты — ранее была проведена операция с сохранением реквизитов CIT CC. | Рекуррентный платеж, инициированный покупателем | 2 | not null | N | Запрещено | Разрешено |
Merchant Initiated Credential-on-File, Recurring (MIT COF R) | Инициированные торговым предприятием повторяющиеся платежи без графика — ранее была проведена операция с сохранением реквизитов CIT CC. Применяется для оплаты коммунальных услуг, платежей за услуги связи, кабельное/спутниковое телевидение и прочее. Сумма может быть определена заранее или становится известна непосредственно перед оплатой. | Рекуррентный платеж, инициированный торговым предприятием | R | not null | N | Запрещено | Разрешено |
Merchant Credential-on-File, Installment (MIT COF I) | Инициированные торговым предприятием повторяющиеся платежи по графику — ранее была проведена операция с сохранением реквизитов CIT CC. Применяется для платежей в рассрочку по товарному кредиту, для оплаты страховки в рассрочку, для погашения кредита в соответствии с графиком платежей. График платежей может быть изменен по соглашению сторон — суммы и даты платежей должны быть известны плательщику (держателю карты) до момента проведения операции. | Рекуррентный платеж, инициированный торговым предприятием | I | not null | N | Разрешено | Запрещено |
Термин | Определение |
---|---|
Клиент | Физлицо, производящее перевод с использованием банковской карты на сайте мерчанта. |
Мерчант | Бизнес, принимающий и осуществляющий переводы по банковским картам на своем сайте. |
Т‑Касса | Сервис, помогающий проводить выплату клиенту-физлицу. |
Эмитент | Банк, выпустивший карту клиента-физлица. |
PCI DSS | Международный стандарт безопасности, созданный для защиты данных банковских карт. |
3-D Secure | Протокол, который используется как дополнительный уровень безопасности для онлайн-кредитных и дебетовых карт. 3-D Secure добавляет ещё один шаг аутентификации для онлайн-платежей. |
Терминал | Точка приема платежей мерчанта. В общем случае привязывается к сайту, на котором осуществляется прием платежей. Далее в этой документации описан протокол для терминала мерчанта. Для проведения тестов используются данные тестового терминала TinkoffBankTest — пароль аналогичен. |
ККМ | Контрольно-кассовая машина. |
Личный кабинет мерчанта | Веб-приложение, в котором мерчант управляет интернет-эквайрингом — настраивает параметры терминалов, подтверждает или отменяет платежи, анализирует статистику. |
Каждый терминал обладает свойствами, которые влияют на те или иные аспекты приёма платежей. Эти свойства настраиваются при подключении интернет-эквайринга и могут быть изменены в личном кабинете мерчанта.
Основные параметры приёма платежей для терминала:
Название параметра | Формат | Описание |
---|---|---|
TerminalKey | 20 символов, чувствительно к регистру | Уникальный символьный ключ терминала. Устанавливается Т‑Кассой. |
Success URL | 250 символов, чувствительно к регистру | URL на веб-сайте мерчанта, куда будет переведен клиент в случае успешной оплаты • true — платеж завершился успешно; • false — платеж не завершился. * |
Fail URL | 250 символов, чувствительно к регистру | URL на веб-сайте мерчанта, куда будет переведен клиент в случае неуспешной оплаты. * |
Success Add Card URL | 250 символов, чувствительно к регистру | URL на веб-сайте мерчанта, куда будет переведен клиент после успешной привязки карты. * |
Fail Add Card URL | 250 символов, чувствительно к регистру | URL на веб-сайте мерчанта, куда будет переведен клиент после неуспешной привязки карты. * |
Notification URL | 250 символов, чувствительно к регистру | URL на веб-сайте мерчанта, куда будет отправлен POST запрос о статусе выполнения вызываемых методов. Только для методов Authorize, FinishAuthorize, Confirm, Cancel. |
Валюта терминала | 3 символа | Валюта, в которой будут происходить списания по данному терминалу, если иное не передано в запросе. |
Активность терминала | Рабочий/Неактивный/Тестовый | Определяет режим работы данного терминала. |
Password | 20 символов, чувствительно к регистру | Используется для подписи запросов/ответов. Является секретной информацией, известной только мерчанту и Т‑Кассе. Пароль находится в личном кабинете мерчанта. |
Отправлять нотификацию на FinishAuthorize | Да/Нет | Определяет, будет ли отправлена нотификация на выполнение метода FinishAuthorize. По умолчанию — да. |
Отправлять нотификацию на Completed | Да/Нет | Определяет, будет ли отправлена нотификация на выполнение метода AttachCard. По умолчанию — да. |
Отправлять нотификацию на Reversed | Да/Нет | Определяет, будет ли отправлена нотификация на выполнение метода Cancel. По умолчанию — да. |
* В URL можно указать нужные параметры в виде ${<параметр>}, которые будут переданы на URL через метод GET.
Перед выполнением запроса MAPI проверяет, можно ли доверять его инициатору. Для этого сервер проверяет подпись запроса. В MAPI используется механизм подписи с помощью токена. Мерчант должен добавлять токен к каждому запросу, где это требуется.
В описании входных параметров для каждого метода мы указали, нужно подписывать запрос или нет. Токен формируется на основании тех полей, которые есть в запросе, поэтому токены для каждого запроса уникальные и никогда не совпадают.
Токен в MAPI — это строка, в которой мерчант зашифровал данные своего запроса с помощью пароля. Для создания токена мерчант использует пароль из личного кабинета мерчанта.
Пример процесса шифрования тела запроса для метода Init:
{
"TerminalKey": "MerchantTerminalKey",
"Amount": 19200,
"OrderId": "21090",
"Description": "Подарочная карта на 1000 рублей",
"Token": "68711168852240a2f34b6a8b19d2cfbd296c7d2a6dff8b23eda6278985959346",
"DATA": {
"Phone": "+71234567890",
"Email": "a@test.com"
},
"Receipt": {
"Email": "a@test.ru",
"Phone": "+79031234567",
"Taxation": "osn",
"Items": [
{
"Name": "Наименование товара 1",
"Price": 10000,
"Quantity": 1,
"Amount": 10000,
"Tax": "vat10",
"Ean13": "303130323930303030630333435"
},
{
"Name": "Наименование товара 2",
"Price": 3500,
"Quantity": 2,
"Amount": 7000,
"Tax": "vat20"
},
{
"Name": "Наименование товара 3",
"Price": 550,
"Quantity": 4,
"Amount": 4200,
"Tax": "vat10"
}
]
}
}
Чтобы зашифровать данные запроса, мерчанту нужно:
TerminalKey
, Amount
, OrderId
, Description
и исключен объект Receipt
и DATA
.[{"TerminalKey": "MerchantTerminalKey"},{"Amount": "19200"},{"OrderId": "21090"},{"Description": "Подарочная карта на 1000 рублей"}]
Password
, Значение пароля}. Пароль можно найти в личном кабинете мерчанта.[{"TerminalKey": "MerchantTerminalKey"},{"Amount": "19200"},{"OrderId": "21090"},{"Description": "Подарочная карта на 1000 рублей"},{"Password": "usaf8fw8fsw21g"}]
[{"Amount": "19200"},{"Description": "Подарочная карта на 1000 рублей"},{"OrderId": "21090"},{"Password": "usaf8fw8fsw21g"},{"TerminalKey": "MerchantTerminalKey"}]
"19200Подарочная карта на 1000 рублей21090usaf8fw8fsw21gMerchantTerminalKey"
"0024a00af7c350a3a67ca168ce06502aa72772456662e38696d48b56ee9c97d9"
Token
в тело запроса и отправить запрос.{
"TerminalKey": "MerchantTerminalKey",
"Amount": 19200,
"OrderId": "21090",
"Description": "Подарочная карта на 1000 рублей",
"DATA": {
"Phone": "+71234567890",
"Email": "a@test.com"
},
"Receipt": {
"Email": "a@test.ru",
"Phone": "+79031234567",
"Taxation": "osn",
"Items": [
{
"Name": "Наименование товара 1",
"Price": 10000,
"Quantity": 1,
"Amount": 10000,
"Tax": "vat10",
"Ean13": "303130323930303030630333435"
},
{
"Name": "Наименование товара 2",
"Price": 20000,
"Quantity": 2,
"Amount": 40000,
"Tax": "vat20"
},
{
"Name": "Наименование товара 3",
"Price": 30000,
"Quantity": 3,
"Amount": 90000,
"Tax": "vat10"
}
]
},
"Token": "0024a00af7c350a3a67ca168ce06502aa72772456662e38696d48b56ee9c97d9"
}
Проверить корректность формирования токена можно через сервис https://tokentcs.web.app.
Информацию о корректности токена также можно проверить в личном кабинете интернет-эквайринга в разделе Операции. Выберите нужный заказ → Дополнительная информация о заказе → поле inittokenisvalid. Если значение в этом поле
true
— токен валидный,false
— некорректный.
Прием платежей происходит с помощью вызова методов — параметры передаются через метод POST в формате JSON. Все методы и передаваемые параметры чувствительны к регистру.
Для нашего интернет-эквайринга оплата проходит только в рублях.
Если мерчанту нужна оплата в валюте, он самостоятельно реализовывает логику конвертации суммы в запросе на своей стороне.
Для POST-запроса в заголовке должен быть Content Type: application/json
.
Основная сущность в интернет-эквайринге Т‑Кассы — платеж. В зависимости от настроек терминала, платеж может идти по двум сценариям:
Настроить способ приема на терминале можно в личном кабинете мерчанта или передать нужный тип в параметре
PayType
при вызове метода Init.
Чтобы создать платеж, мерчант должен инициировать его через метод Init — передать сумму платежа и номер заказа.
При вызове метода Init в объекте DATA
в атрибуте OperationInitiatorType
нужно передавать признак
инициатора операции. В ответ MAPI создаст новый платеж в статусе NEW
и вернёт его идентификатор в параметре PaymentId
.
После этого мерчант вызывает метод Check3DSVersion, в котором передает
зашифрованные карточные данные клиента и PaymentId
. Это нужно для проверки версии протокола 3D-Secure по карте. Она
может быть версии 1.0 или 2.0.
Если в ответе метода Check3DSVersion есть параметр ThreeDSMethodURL
,
браузер клиента должен вызывать ресурс, адрес которого пришел в параметре ThreeDSMethodURL
. В запросе нужно передать
строковый параметр threeDSMethodData
. Эта строка — закодированный в формате base64
JSON-объект с параметрами:
Название параметра |
Тип данных | Описание |
---|---|---|
threeDSMethodNotificationURL |
string | Обратный адрес, на который будет отправлен запрос после прохождения 3DS Method . |
threeDSServerTransID |
string | Идентификатор транзакции из ответа метода Check3DSVersion. |
Браузер должен вызвать 3DS Method
в скрытом iframe и передать данные в формате x-www-form-urlencoded
.
Пример запроса на ThreeDSMethodURL
:
<body onload="document.form.submit()">
<form name="form" action="{ThreeDSMethodURL}" method="post" >
<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU2ZTcxMmE1LTE5MGEtNDU4OC05MWJjLWUwODYyNmU3N2M0NCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3Jlc3QtYXBpLXRlc3QudGlua29mZi5ydS92Mi9Db21wbGV0ZTNEU01ldGhvZHYyIn0">
</form>
</body>
Пример декодированного значения threeDSMethodData
:
{
"threeDSServerTransID":"56e712a5-190a-4588-91bc-e08626e77c44",
"threeDSMethodNotificationURL":"https://rest-api-test.tinkoff.ru/v2/>Complete3DSMethodv2"
}
За проведение платежа отвечает метод FinishAuthorize. Через него мерчант передает в MAPI карточные данные клиента, продолжая обработку платежа.
Если платеж:
В ответ MAPI вернет один из статусов:
Статус |
Описание | Доступные действия |
---|---|---|
AUTH_FAIL |
Неуспешная авторизация | Провести платеж заново |
REJECTED |
Платеж отклонен | Провести платеж заново |
CONFIRMED |
Успешный одностадийный платеж | - |
AUTHORIZED |
Успешный двухстадийный платеж | Подтвердить платеж |
3DS_CHECKING |
Требуется подтверждение платежа по 3D-Secure |
|
Если по платежу не нужно проходить подтверждение 3DS, в ответе FinishAuthorize MAPI вернет один из трех конечных статусов платежа:
CONFIRMED
— при одностадийном платеже;AUTHORIZED
— при двухстадийном платеже;REJECTED
— при отказе в проведении платежа.Если в ответе метода FinishAuthorize вернулся статус
3DS_CHECKING
— значит, нужно пройти проверку 3D-Secure. Для этого мерчант должен сформировать
запрос в сервис аутентификации банка, выпустившего карту. Адрес сервиса возвращается в ответе FinishAuthorize в
параметре ACSUrl
. Вместе с этим нужно перенаправить клиента для прохождения 3DS на эту же страницу — ACSUrl
.
В заголовке запроса нужно передать параметр Content-Type
со значением application/x-www-form-urlencoded
.
Набор параметров в теле запросе зависит от версии протокола 3DS по карте.
Проводить тестовые платежи можно только на тестовом окружении.
Если версия 3DS — 1.0, в запросе передаются параметры:
Название параметра | Описание |
---|---|
MD |
Информация для идентификации платежной сессии на стороне торговой точки. Возвращается в ответе метода FinishAuthorize. |
PaReq |
Запрос на аутентификацию плательщика, который содержит разные детали транзакции. Возвращается в ответе метода FinishAuthorize. |
TermURL |
Адрес перенаправления после аутентификации 3DS. Должен содержать ссылку на обработчик на стороне мерчанта, принимающий результаты прохождения 3-D Secure. |
Если версия 3DS — 2.0, в запросе передаются параметры в зависимости от типа устройства клиента. Тип устройства передается
в запросе FinishAuthorize в параметре deviceChannel
. Возможны два
варианта — браузер (BRW, код 02
) и приложение (APP, код 01
).
Параметры для браузера:
Название параметра | Тип данных | Описание |
---|---|---|
creq |
string | JSON с параметрами threeDSServerTransID , acsTransID ,challengeWindowSize , messageType , messageVersion , закодированный в base64 . |
Строка creq
для браузера формируется из следующих параметров:
Название параметра |
Тип данных | Описание |
---|---|---|
threeDSServerTransID |
string | Идентификатор транзакции из ответа метода FinishAuthorize. |
acsTransID |
string | Идентификатор транзакции, присвоенный ACS, полученный из ответа метода FinishAuthorize. |
challengeWindowSize |
string | Размер экрана, на котором открыта страница ACS. Допустимые значения: |
messageType |
string | Передается фиксированное значение CReq . |
messageVersion |
string | Версия 3DS, полученная из ответа метода Check3DSVersion. |
Параметры для приложения:
Название параметра | Тип данных | Описание |
---|---|---|
creq |
string | JWE object с параметрами threeDSServerTransID , acsTransID , messageType , messageVersion , закодированный в PS256 . |
Строка creq
для приложения формируется из следующих параметров:
Название параметра |
Тип данных | Описание |
---|---|---|
threeDSServerTransID |
string | Идентификатор транзакции из ответа метода FinishAuthorize. |
acsTransID |
string | Идентификатор транзакции, присвоенный ACS, полученный из ответа метода FinishAuthorize. |
messageType |
string | Передается фиксированное значение CReq . |
messageVersion |
string | Версия 3DS, полученная из ответа метода Check3DSVersion. |
Когда сервис аутентификации банка, который выпустил карту, прислал результат прохождения 3D-Secure, мерчант должен передать эту информацию в MAPI. В зависимости от версии протокола 3DS нужно вызвать один из методов:
Чтобы создать платеж, мерчант должен инициировать его через метод Init — передать сумму платежа и номер заказа.
При успешном прохождении запроса в ответе метода Init вернется параметр PaymentURL
, на который нужно переадресовать клиента.
При переходе на PaymentURL
клиенту откроется платежная форма Т‑Кассы, где нужно ввести реквизиты карты, а после этого — этап прохождения 3DS.
Методы Authorize и FinishAuthorize вызываются системами Т‑Кассы при переадресации клиента на PaymentURL — параметр возвращается в ответе метода Init. Актуально для мерчантов, которые используют платежную форму Т-Банка.
При вызове метода Init в объекте DATA
в атрибуте OperationInitiatorType
нужно передавать признак инициатора операции.
Вызывается автоматически при переадресации клиента на страницу PaymentURL
, которая возвращается в ответе метода Init.
Статус платежа выставляется в FORM_SHOWED
.
Подтверждает инициированный платеж передачей карточных данных и списывает деньги с карты клиента.
Вызывается формой оплаты по адресу PaymentURL
, когда клиент вводит данные карты и нажимает кнопку Оплатить.
Статус перевода:
CONFIRMED
— при успешном сценарии;REJECTED
— при неуспешном.Клиент переадресовывается на:
Success URL
— при успешном переводе;Fail URL
— при неуспешном переводе.Если платёж завершился успешно, клиент будет перенаправлен на страницу Success URL
из настроек терминала.
Двухстадийный платеж включает два этапа:
Когда клиент оплачивает заказ, деньги за покупку замораживаются (холдируются) на его счете до семи дней. Если за это время клиент:
Если мерчант не подтвердит платеж вовремя, он может столкнуться с негативом от клиента — например, когда клиент может не вспомнить, за что списались деньги, и обратиться в свой банк для возврата средств.
Холдирование денег на карте покупателя зависит от его банка-эмитента и не всегда равно семи дням. Например, покупатель оплатил товар, и его банк заморозил средства на карте на 3 дня. 3 дня прошли, деньги разморозились и стали доступны на счете. Спустя день вы подтверждаете платеж, списывая сумму покупки. Фактически оплата прошла один раз.
Техническая реализация двухстадийных платежей
Если терминал настроен на прием двухстадийных платежей, после вызова метода FinishAuthorize деньги блокируются на карте
клиента, и платеж переходит в статус AUTHORIZED
.
Когда мерчант захочет списать деньги, он должен вызвать метод Confirm и передать PaymentId
в
запросе. После успешного списания платеж перейдет в статус CONFIRMED
. Если мерчант хочет отменить заказ — например, если товар закончился —
нужно вызвать метод Cancel.
Мерчант может сохранять платежные данные клиента и использовать их для повторных списаний. Такие платежи называются рекуррентными.
В этом случае клиент должен совершить хотя бы один платеж, который был настроен как рекуррентный. Для этого мерчанту нужно передать
параметр Recurrent
в методе Init.
После успешной оплаты MAPI отправит мерчанту уведомление об изменении статуса платежа на AUTHORIZED
или CONFIRMED
и
вернет параметр RebillId
. Следующие платежи этого клиента будут рекуррентными, если мерчант вызовет метод Init,
а затем без переадресации на PaymentURL
вызовет метод Charge и передаст параметр RebillId
.
Метод Charge работает как по одностадийной, так и по двухстадийной схеме оплаты. Чтобы перейти на двухстадийную схему, нужно переключить терминал в личном кабинете и написать на acq_help@tbank.ru с просьбой переключить схему рекуррентов, либо в последующих платежах передавать в методе Init параметр
Paytype
со значениемT
.
ВАЖНО: Параметры, которые передаются в методе Init приоритетнее установленных настроек на треминале.
Мерчант может отменить успешный платеж. В этом случае деньги вернутся на карту, которую клиент указывал при совершении платежа.
Успешный платеж — это платеж, который находится в статусе AUTHORIZED
или CONFIRMED
. Если мерчант отменяет платеж в статусе:
AUTHORIZED
— заблокированная сумма размораживается на карте клиента.CONFIRMED
— деньги списываются со счета мерчанта и возвращаются на карту клиента.Возврат может быть частичный или полный. Частичный возврат — отмена не на всю сумму платежа, полный — отмена на всю сумму платежа.
Чтобы отменить платеж, мерчант должен вызвать метод Cancel и в запросе передать идентификатор платежа — PaymentId
.
По умолчанию MAPI сделает полный возврат. Если нужна частичная отмена, в запросе в параметре Amount
мерчант передает сумму,
которая вернется клиенту.
Если при работе используется онлайн-касса, возврат можно делать только по позициям в чеке. Если нужно вернуть другую сумму,
сначала отключите онлайн-кассу, а затем выполните возврат через метод Cancel, передав в нем нужную сумму в параметре Amount
Если у клиента подключена онлайн-касса, в методе Cancel передаются:
Amount
— сумма к частичному возврату или анхолду. Формула расчета: Price * Quantity
= Amount
.Receipt
— параметры чека.Например, товар стоит 500.00 рублей, и нужно вернуть 50.00 рублей. В Cancel нужно передать Amount
= 5000
:
{
"Name": "Item12",
"Price": 50000,
"Quantity": 0.1,
"Amount": 5000,
"Tax": "none",
"PaymentObject": "service"
}
Если в чеке несколько товаров, нужно сделать то же самое для каждого из них.
Без активной онлайн-кассы достаточно передать нужную сумму в Amount
через метод Cancel. При частичном анхолде
остаток также остается в резерве, и его нужно подтвердить.
Мерчант может получить информацию об основных параметрах платежа в любой момент.
Если нужно получить данные по конкретному платежу, мерчанту нужно вызвать метод GetState
и передать PaymentId
в запросе.
Если по одному заказу было несколько платежей, получить историю платежей и их текущий статус можно через метод CheckOrder
— в запросе нужно передать OrderId
.
OrderId
не является уникальным параметром. Рекомендуем сверять дополнительные данные заказа —PaymentId
иAmount
.
В процессе обработки платеж меняет свое состояние. Основные статусы и условия перехода в них:
Статус |
Правило перехода |
---|---|
NEW |
MAPI получил запрос Init. После этого он создает новый платеж со статусом NEW и возвращает его идентификатор в параметре PaymentId , а также ссылку на платежную форму в параметре PaymentURL . |
FORM_SHOWED |
Мерчант перенаправил клиента на страницу платежной формы PaymentURL и страница загрузилась у клиента в браузере. |
AUTHORIZING |
Платеж обрабатывается MAPI и платежной системой. |
3DS_CHECKING |
Платеж проходит проверку 3D-Secure. |
3DS_CHECKED |
Платеж успешно прошел проверку 3D-Secure. |
AUTHORIZED |
Платеж авторизован, деньги заблокированы на карте клиента. |
CONFIRMING |
Подтверждение платежа обрабатывается MAPI и платежной системой. |
CONFIRMED |
Платеж подтвержден, деньги списаны с карты клиента. |
REVERSING |
Мерчант запросил отмену авторизованного, но еще неподтвержденного платежа. Возврат обрабатывается MAPI и платежной системой. |
PARTIAL_REVERSED |
Частичный возврат по авторизованному платежу завершился успешно. |
REVERSED |
Полный возврат по авторизованному платежу завершился успешно. |
REFUNDING |
Мерчант запросил отмену подтвержденного платежа. Возврат обрабатывается MAPI и платежной системой. |
PARTIAL_REFUNDED |
Частичный возврат по подтвержденному платежу завершился успешно. |
REFUNDED |
Полный возврат по подтвержденному платежу завершился успешно. |
CANCELED |
Мерчант отменил платеж. |
DEADLINE_EXPIRED |
1. Клиент не завершил платеж в срок жизни ссылки на платежную форму PaymentURL . Этот срок мерчант передает в методе Init в параметре RedirectDueDate . 2. Платеж не прошел проверку 3D-Secure в срок. |
REJECTED |
Банк отклонил платеж. |
AUTH_FAIL |
Платеж завершился ошибкой или не прошел проверку 3D-Secure. |
Метод инициирует платежную сессию.
TerminalKey required | string <= 20 characters Идентификатор терминала. |
Amount required | number <= 10 characters
|
OrderId required | string <= 36 characters Идентификатор заказа в системе мерчанта. Должен быть уникальным для каждой операции. |
Token required | string Подпись запроса. |
Description | string <= 140 characters Описание заказа. Значение параметра будет отображено на платежной форме. Для привязки и одновременной оплаты по СБП поле обязательное. При оплате через СБП эта информация отобразится в мобильном банке клиента. |
CustomerKey | string <= 36 characters Идентификатор клиента в системе мерчанта.
|
Recurrent | string <= 1 characters Признак родительского рекуррентного платежа. Обязателен для регистрации автоплатежа. Если передается и установлен в Значение зависит от атрибутов:
Подробнее — в описании методов Рекуррентный платёж и Инициализация платежа. |
PayType | string Enum: "O" "T" Определяет тип проведения платежа — двухстадийная или одностадийная оплата:
Если параметр передан — используется его значение, если нет — значение из настроек терминала. |
Language | string <= 2 characters Язык платежной формы:
Если не передан, форма откроется на русском языке. |
NotificationURL | string <uri> URL на веб-сайте мерчанта, куда будет отправлен POST-запрос о статусе выполнения вызываемых методов — настраивается в личном кабинете. Если параметр:
|
SuccessURL | string <uri> URL на веб-сайте мерчанта, куда будет переведен клиент в случае успешной оплаты — настраивается в личном кабинете. Если параметр:
|
FailURL | string <uri> URL на веб-сайте мерчанта, куда будет переведен клиент в случае неуспешной оплаты — настраивается в личном кабинете. Если параметр:
|
RedirectDueDate | any <date-time> Cрок жизни ссылки или динамического QR-кода
СБП, если выбран этот способ оплаты.
Пример даты: 2016-08-31T12:28:00+03:00. Если не передан, принимает значение 24 часа для платежа и 30 дней для счета. Выставление счета через личный кабинет
|
Common (object) or T-Pay (object) or LongPay (object) JSON-объект, который позволяет передавать дополнительные параметры по операции и задавать определенные настройки в
формате Максимальная длина для каждого передаваемого параметра:
Максимальное количество пар
Например, если указать Для МСС 4814 обязательно передать значение в параметре
Для МСС 6051 и 6050 обязательно передавать параметр Пример:
Рекомендации для заполнения поля
Рекомендации для заполнения поля
Рекомендации для заполнения поля
Подробная таблица — передача признака инициатора операции Если передавать значения атрибутов, которые не соответствуют таблице, MAPI вернет ошибку 1126 —
несопоставимые значения | |
Receipt_FFD_105 (object) or Receipt_FFD_12 (object) JSON-объект с данными чека. Обязателен, если подключена онлайн-касса. | |
Array of objects (Shops) JSON-объект с данными маркетплейса. Обязателен для маркетплейсов. | |
Descriptor | string Динамический дескриптор точки. |
{- "TerminalKey": "TinkoffBankTest",
- "Amount": 140000,
- "OrderId": "21090",
- "Description": "Подарочная карта на 1000 рублей",
- "Token": "68711168852240a2f34b6a8b19d2cfbd296c7d2a6dff8b23eda6278985959346",
- "DATA": {
- "Phone": "+71234567890",
- "Email": "a@test.com"
}, - "Receipt": {
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Taxation": "osn",
- "Items": [
- {
- "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "Tax": "vat10",
- "Ean13": "303130323930303030630333435"
}, - {
- "Name": "Наименование товара 2",
- "Price": 20000,
- "Quantity": 2,
- "Amount": 40000,
- "Tax": "vat20"
}, - {
- "Name": "Наименование товара 3",
- "Price": 30000,
- "Quantity": 3,
- "Amount": 90000,
- "Tax": "vat10"
}
]
}
}
{- "Success": true,
- "ErrorCode": "0",
- "TerminalKey": "TinkoffBankTest",
- "Status": "NEW",
- "PaymentId": "3093639567",
- "OrderId": "21090",
- "Amount": 140000,
}
Для мерчантов, использующих собственную платежную форму
Проверяет поддерживаемую версию 3DS-протокола по карточным данным из входящих
параметров.
При использовании второй версии можно получить данные для дополнительного метода 3DS Method
, который позволяет
эмитенту собрать данные браузера
клиента. Это может быть полезно при принятии решения в пользу Frictionless Flow —
аутентификации клиента без редиректа на страницу ACS.
PaymentId required | string <= 20 characters Идентификатор платежа в системе Т‑Кассы. |
TerminalKey required | string <= 20 characters Идентификатор терминала, выдается мерчанту Т‑Кассой. |
CardData required | string Зашифрованные данные карты в формате:
|
Token required | string Подпись запроса. |
{- "PaymentId": 13660,
- "TerminalKey": "testRegressBank",
- "CardData": "U5jDbwqOVx+2vDApxe/rfACMt+rfWXzPdJ8ZXxNFVIiZaLZrOW72bGe9cKZdIDnekW0nqm88YxRD↵jyfa5Ru0kY5cQV alU+juS1u1zpamSDtaGFeb8sRZfhj72yGw+io+qHGSBeorcfgoKStyKGuBPWfG↵d0PLHuyBE6QgZyIAM1XfdmNlV0UAxOnkTGDsskL pIt3AWhw2e8KOar0vwbgCTDjznDB1/DLgOW01↵Aj/bXyLJoG1BkOrPBm9JURs+f+uyFae0hkRicNKNgXoN5pJTSQxOEauOi6ylsVJ B3WK5MNYXtj6x↵GlxcmTk/LD9kvHcjTeojcAlDzRZ87GdWeY8wgg==",
- "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e"
}
{- "Version": "2.1.0",
- "TdsServerTransID": "17d3791b-5cfa-4318-bc23-3d949e8c4b7e",
- "PaymentSystem": "mir",
- "Success": true,
- "ErrorCode": "0",
- "Message": "None",
- "Details": "None"
}
Для Мерчантов с PCI DSS
Если в ответе метода был получен параметр ThreeDSMethodURL, то необходимо отправить запрос на стороне браузера по полученному ThreeDSMethodURL. Это необходимо для сбора информации ACS-ом о девайсе клиента. Отправка запроса 3DS Method в браузере должна происходить в скрытом frame.
Время ожидания выполнения метода не более 10 секунд
threeDSMethodData required | string JSON с параметрами threeDSMethodNotificationURL, threeDSServerTransID, закодированный в формат base-64
|
<body onload="document.form.submit()"> <form name="form" action="{ThreeDSMethodURL}" method="post"> <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU2ZTcxMmE1LTE5MGEtNDU4OC05MWJjLWUwODYyNmU3N2M0NCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3Jlc3QtYXBpLXRlc3QudGlua29mZi5ydS92Mi9Db21wbGV0ZTNEU01ldGhvZHYyIn0"> </form> </body>
{- "threeDSServerTransID": "string"
}
Для мерчантов, использующих собственную платежную форму
Метод подтверждает платеж передачей реквизитов. При одностадийной оплате — списывает средства
с карты клиента, при двухстадийной — блокирует указанную сумму. Используется, если у площадки есть сертификация PCI DSS и
собственная платежная форма.
TerminalKey required | string Идентификатор терминала. | ||||||||||||||||||||||||||||
PaymentId required | string <= 20 characters Уникальный идентификатор транзакции в системе Т‑Кассы. | ||||||||||||||||||||||||||||
Token required | string Подпись запроса. | ||||||||||||||||||||||||||||
IP | string IP-адрес клиента. Обязательный параметр для 3DS второй версии. DS платежной системы требует передавать данный адрес в полном формате, без каких-либо сокращений — 8 групп по 4 символа. Этот формат регламентируется на уровне
спецификации EMVCo. Пример правильного адреса — Пример неправильного адреса — | ||||||||||||||||||||||||||||
SendEmail | boolean
| ||||||||||||||||||||||||||||
Source | string Enum: "cards" "beeline" "mts" "tele2" "megafon" "einvoicing" "webmoney" Источник платежа.
Значение параметра зависит от параметра
| ||||||||||||||||||||||||||||
3DSv2 (object) or object JSON-объект, который содержит дополнительные
параметры в виде Максимальная длина для каждого передаваемого параметра:
Максимальное количество пар | |||||||||||||||||||||||||||||
InfoEmail | string <email> Электронная почта для отправки информации об оплате.
Обязателен при передаче | ||||||||||||||||||||||||||||
EncryptedPaymentData | string Данные карты. Используется и является обязательным только для ApplePay или GooglePay. | ||||||||||||||||||||||||||||
CardData required | string Объект
Пример значения элемента формы
Для MirPay, если интеграция с НСПК для получения платежного токена:
Если мерчант интегрируется только с банком для проведения платежа по MirPay,
метод не вызывается. Эквайер самостоятельно получает платежный токен и инициирует авторизацию
вместо мерчанта. При получении CAVV в CardData оплата будет проводиться как оплата токеном — иначе прохождение 3DS будет регулироваться стандартными настройками треминала или платежа. Не используется и не является обязательным, если передается | ||||||||||||||||||||||||||||
Amount | number <= 10 characters Сумма в копейках. | ||||||||||||||||||||||||||||
deviceChannel | string Канал устройства. Поддерживаются следующие каналы:
| ||||||||||||||||||||||||||||
Route | string Enum: "ACQ" "MC" "EINV" "WM" Способ платежа. Обязательный для ApplePay или GooglePay. |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "700001702044",
- "Token": "f5a3be479324a6d3a4d9efa0d02880b77d04a91758deddcbd9e752a6df97cab5",
- "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334",
- "SendEmail": true,
- "Source": "cards",
- "DATA": {
- "threeDSCompInd": "Y",
- "language": "RU",
- "timezone": "-300",
- "screen_height": "1024",
- "screen_width": "967",
- "cresCallbackUrl": "www.callbackurl.ru",
- "colorDepth": "48",
- "javaEnabled": "false"
}, - "InfoEmail": "qwerty@test.com",
- "EncryptedPaymentData": "string",
- "CardData": "eyJzaWduYXR1cmUiOiJNRVVDSVFEdjNJS1A5WG9nWml4RytUUm9zZWFDK0RGd3RKd2FtMHVEcm91RUVGZVB6Z0lnYXBFbHhxQ3AwQWtZcVVmTFVMaVNhUjBKWkVQNmg 4THFqYks5YkJKQnM5d1x1MDAzZCIsInByb3RvY29sVmVyc2lvbiI6IkVDdjEiLCJzaWduZWRNZXNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwiQW11dm5OYUIralBsa3VKTitrMUZLSDZFcm1VK2lTY052 L05rR3FFaXIxOHZmSWxkVFJ5L2U4cW5zMXkyanFtcm1acU1JSWNYMUhyTHBxRURpaXkvS3B6SUhNZFllcXRkSVVNOU1tRjNpejU2d2NTZUVVaXU2ODI3QThGcitaYm8xRWtWRjY1TUxRYVY3NlBOUFRndH UvQ1BodW5HUk0rN25KdVhDczVtbkVvOHFma0RNVk8xWktGWDQ4TnVEL2FKcDJQdVVIY2puSnBTZ0pTSDB4U21YSnAzU1MreXFDNm54N254WUEwN2h4YjYvSnp2R2s3ZExDU2hWWGU1Z2haUjNDaFQyV W8rRnpXTWJRRGZtSjBLQW9kc2VlR0xaaitqMzVqOUlKMkhJRFhIUUZZMWNuTW9YVUVoTjgvdEkvRkpqRnJiYVdFRkIzRDZwOFUzT2tkUmVaNHAyYi8yYURNZXVxR1ozSUtjc3R0R2lKMFhQQVhhZXYyQU8 o1M3RRQXVqQXRYdFlaekNTVjVBVXdXZS85T1VcXHUwMDNkXCJ9In0=",
- "Amount": 10000,
- "deviceChannel": "02",
- "Route": "ACQ"
}
{- "TerminalKey": "TinkoffBankTest",
- "Amount": 100000,
- "OrderId": "21050",
- "Success": true,
- "Status": "NEW",
- "PaymentId": "13660",
- "ErrorCode": "0",
- "Message": "Неверные параметры",
- "Details": "0",
- "RebillId": "21813157",
- "CardId": "string"
}
Метод возвращает статус платежа.
TerminalKey required | string <= 20 characters Идентификатор терминала. |
PaymentId required | string <= 20 characters Идентификатор платежа в системе Т‑Кассы. |
Token required | string Подпись запроса. |
IP | string IP-адрес клиента. |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "13660",
- "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96",
- "IP": "192.168.0.52"
}
{- "Success": true,
- "ErrorCode": "0",
- "Message": "OK",
- "TerminalKey": "TinkoffBankTest",
- "Status": "AUTHORIZED",
- "PaymentId": "13660",
- "OrderId": "21050",
- "Params": [
- {
- "Key": "Route",
- "Value": "ACQ"
}, - {
- "Key": "Source",
- "Value": "cards"
}, - {
- "Key": "CreditAmount",
- "Value": "100000"
}
], - "Amount": 1230
}
Метод возвращает статус заказа.
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
OrderId required | string Номер заказа в системе мерчанта. Не является уникальным идентификатором. |
Token required | string Подпись запроса |
{- "TerminalKey": "TinkoffBankTest",
- "OrderId": "21057",
- "Token": "4c4c36adf9936b011879fa26f60759e7b47e57f7968283129b0ae9ac457486ab"
}
{- "TerminalKey": "TinkoffBankTest",
- "OrderId": "21057",
- "Success": true,
- "ErrorCode": "0",
- "Message": "OK",
- "Details": "None",
- "Payments": [
- {
- "PaymentId": "124671934",
- "Amount": 13660,
- "Status": "NEW",
- "RRN": "12345678",
- "Success": "true",
- "ErrorCode": 0,
- "Message": "None"
}
]
}
Справку по конкретной операции можно получить на:
PASSWORD
и TERMINAL_KEY
.
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
CallbackUrl required | string URL сервиса получения справок. |
PaymentIdList required | Array of numbers JSON-массив, содержащий в себе перечень |
Token required | string Подпись запроса. |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentIdList": [
- 1201206437,
- 1201206442
], - "Token": "f2fdd7fec8225872590e1558b7ea258c75df8f300d808006c41ab540dd7514d9"
}
{- "Success": true,
- "ErrorCode": 0,
- "Message": "OK",
- "PaymentIdList": [
- {
- "Success": true,
- "ErrorCode": 0,
- "Message": "Запрос на отправку документа принят",
- "PaymentId": "1201206442"
}
]
}
Метод для списания заблокированных денежных средств. Используется при двухстадийном проведении платежа. Применим
только к платежам в статусе AUTHORIZED
. Статус транзакции перед разблокировкой
— CONFIRMING
. Сумма списания может быть меньше или равна сумме авторизации.
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
PaymentId required | string <= 20 characters Идентификатор платежа в системе Т‑Кассы. |
Token required | string Подпись запроса — хэш |
IP | string IP-адрес клиента. |
Amount | number Сумма в копейках. Если не передан, используется |
Receipt_FFD_12 (object) or Receipt_FFD_105 (object) JSON-объект с данными чека. Обязателен, если подключена онлайн-касса. | |
Array of objects (Shops) Обязательный для маркетплейсов. JSON-объект с данными маркетплейса. | |
Route | string Enum: "TCB" "BNPL" Способ платежа. |
Source | string Enum: "installment" "BNPL" Источник платежа. |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "2304882",
- "Token": "c0ad1dfc4e94ed44715c5ed0e84f8ec439695b9ac219a7a19555a075a3c3ed24",
- "IP": "192.168.255.255",
- "Amount": 19200,
- "Receipt": {
- "FfdVersion": "string",
- "ClientInfo": {
- "Birthdate": "string",
- "Citizenship": "string",
- "DocumentСode": "21",
- "DocumentData": "string",
- "Address": "string"
}, - "Taxation": "osn",
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Customer": "78894325",
- "CustomerInn": "788621292",
- "Items": [
- {
- "AgentData": {
- "AgentSign": "paying_agent",
- "OperationName": "Позиция чека",
- "Phones": [
- "+790912312398"
], - "ReceiverPhones": [
- "+79221210697",
- "+79098561231"
], - "TransferPhones": [
- "+79221210697"
], - "OperatorName": "Tinkoff",
- "OperatorAddress": "г. Тольятти",
- "OperatorInn": "7710140679"
}, - "SupplierInfo": {
- "Phones": [
- "+79221210697",
- "+79098561231"
], - "Name": "ООО Вендор товара",
- "Inn": "7710140679"
}, - "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "Tax": "vat10",
- "PaymentMethod": "full_payment",
- "PaymentObject": "goods_with_marking_code",
- "UserData": "Данные пользователя ext.test.qa@tinkoff.ru",
- "Excise": "12.2",
- "CountryCode": "056",
- "DeclarationNumber": "12345678901",
- "MeasurementUnit": "шт",
- "MarkProcessingMode": "string",
- "MarkCode": {
- "MarkCodeType": "EAN8",
- "Value": "12345678"
}, - "MarkQuantity": {
- "Numerator": 1,
- "Denominator": 2
}, - "SectoralItemProps": {
- "FederalId": "001",
- "Date": "21.11.2020",
- "Number": "123/43",
- "Value": "test value SectoralItemProps"
}
}
], - "Payments": {
- "Cash": 90000,
- "Electronic": 50000,
- "AdvancePayment": 0,
- "Credit": 0,
- "Provision": 0
}
}, - "Shops": [
- {
- "ShopCode": "700456",
- "Amount": 10000,
- "Name": "Товар",
- "Fee": "500"
}
], - "Route": "BNPL",
- "Source": "BNPL"
}
{- "TerminalKey": "TinkoffBankTest",
- "OrderId": "21057",
- "Success": true,
- "Status": "CONFIRMED",
- "PaymentId": "2304882",
- "ErrorCode": "0",
- "Message": "OK",
- "Details": "None",
- "Params": [
- {
- "Key": "Route",
- "Value": "ACQ"
}
]
}
ВАЖНО! Тестовый терминал (DEMO) не поддерживает проверку 3DS. Для тестирования 3DS нужно использовать боевой терминал в связке с тестовой средой (https://rest-api-test.tinkoff.ru/v2)
Для мерчантов, использующих собственную платежную форму
Проверяет результаты прохождения 3-D Secure и при успешном прохождении подтверждает инициированный платеж. При использовании:
Формат запроса — x-www-form-urlencoded
.
После того, как мерчант получит ответ ACS с результатами прохождения 3-D Secure на TermUrl
, нужно
отправить запрос через метод Submit3DSAuthorization.
MD required | string Уникальный идентификатор транзакции в системе. Возвращается в ответе от ACS. |
PaRes required | string Шифрованная строка, содержащая результаты 3-D Secure аутентификации. Возвращается в ответе от ACS. |
PaymentId | string Уникальный идентификатор транзакции в системе Т‑Кассы. |
TerminalKey | string <= 20 characters Идентификатор терминала, выдается мерчанту Т‑Кассой. |
Token | string Подпись запроса. |
<body onload="document.form.submit()"> <form name="form" action="https://rest-api-test.tinkoff.ru/v2/Submit3DSAuthorization" method="post"> <input type="hidden" name="MD" value="2561504"> <input type="hidden" name="PaRes" value="eJxVUttygjAU/BWG1w4mXKXOMY5WOrVTrOOtl7cAqeJI1AAO+vVNFKrlaffkZM9mD9Crsq12ZCJPd7yrmy2sa4zHuyTlq66+mD8bvt4jMF8LxoYzFpeCEQhZntMV09JE3vC8Hx9j27A8LzEcN7aNCPu24VIrihKXetiPdAKT/pQdCNSDiJzTsgA1VCqKeE15QYDGh8FoTBy73fZtQDWFjInRkFi4+Uz82JbH1zJwmjEyHcwAXRDEu5IX4kQ8R/Y0BEqxJeui2HcQOlGesKolSkCqCuhmYFIqlEuVKk3IDL8uPwI3jDaBGZ4XeLxZVeFw5I7nX11AqgMSWjDpzPSxb/ma6XRct4Pl4y51oJkar5zLx1wx7NWI/t3BfQFkxkKuoHHfMGDVfseZugLoDwO6+X16UfHFhUyk/32OMH3vZ5+nYBu/2d4xcMTDsn04j19VqJcmpZjKYKT3q6QigJQMqveF6lVL9O8X+AWMIbbt"> <input type="hidden" name="PaymentId" value="10063"> <input type="hidden" name="TerminalKey" value="TinkoffBankTest"> <input type="hidden" name="Token" value="871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6" > </form>
{- "TerminalKey": "TinkoffBankTest",
- "OrderId": "21050",
- "Success": true,
- "Status": "CONFIRMED",
- "PaymentId": "10063",
- "ErrorCode": "0",
- "Message": "string",
- "Details": "string"
}
Для мерчантов, использующих собственную платежную форму
Проверяет результаты прохождения 3-D Secure и при успешном прохождении подтверждает инициированный платеж. При использовании:
Формат запроса — x-www-form-urlencoded
.
После того, как мерчант получит ответ ACS с результатами прохождения 3-D Secure на cresCallbackUrl
, нужно
отправить запрос через метод Submit3DSAuthorizationV2.
PaymentId required | string Уникальный идентификатор транзакции в системе Т‑Кассы. |
TerminalKey required | string <= 20 characters Идентификатор терминала, выдается мерчанту Т‑Кассой. |
Token required | string Подпись запроса. |
<body onload="document.form.submit()"> <form name="form" action="https://rest-api-test.tinkoff.ru/v2/Submit3DSAuthorizationV2" method="post"> <input type="hidden" name="PaymentId" value="10063"> <input type="hidden" name="TerminalKey" value="TinkoffBankTest"> <input type="hidden" name="Token" value="871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6" > </form>
{- "OrderId": "21050",
- "TerminalKey": "TinkoffBankTest",
- "Status": "CONFIRMED",
- "PaymentId": "10063",
- "Success": true,
- "ErrorCode": "0",
- "Message": "string",
- "Details": "string"
}
Метод проводит рекуррентный (повторный) платеж — безакцептное списание денежных средств со счета банковской карты клиента.
Чтобы его использовать, клиент должен совершить хотя бы один платеж в пользу мерчанта, который должен быть указан как рекуррентный
(параметр Recurrent
методе Init), но фактически являющийся первичным.
После завершения оплаты в уведомлении на AUTHORIZED
или CONFIRMED
будет передан параметр RebillId
.
В дальнейшем для проведения рекуррентного платежа мерчант должен вызвать метод Init, указать нужную сумму для списания
в параметре Amount
, а затем без переадресации на PaymentURL
вызвать метод Charge для оплаты по тем же реквизитам
и передать параметр RebillId
, полученный при совершении первичного платежа.
Метод Charge работает по одностадийной и двухстадийной схеме оплаты. Чтобы перейти на двухстадийную схему, нужно переключить терминал в личном кабинете и написать на acq_help@tbank.ru с просьбой переключить схему рекуррентов.
По умолчанию метод Charge отключен. Чтобы его включить:
- на DEMO-терминале — напишите на acq_help@tbank.ru;
- на боевом терминале — обратитесь к своему персональному менеджеру.
При проведении рекуррентного платежа учитывайте взаимосвязь атрибута RebillId
метода Charge:
OperationInitiatorType
и Recurrent
метода Init;Допустимые сценарии взаимосвязи:
CIT/MIT | Тип операции | OperationInitiator в Init |
RebillId в Charge |
Recurrent в Init |
AFT-терминал | ECOM-терминал |
---|---|---|---|---|---|---|
CIT | Credential-Not-Captured | 0 | null | N | Разрешено | Разрешено |
CIT | Credential-Captured | 1 | null | Y | Разрешено | Разрешено |
CIT | Credential-on-File | 2 | not null | N | Запрещено | Разрешено |
MIT | Credential-on-File, Recurring | R | not null | N | Запрещено | Разрешено |
MIT | Credential-on-File, Installment | I | not null | N | Разрешено | Запрещено |
Если передавать значения атрибутов, которые не соответствуют значениям в таблице, MAPI вернет ошибку 1126
—
несопоставимые значения RebillId
или Recurrent
с переданным значением OperationInitiatorType
.
Recurrent=Y
и CustomerKey
. мерчантов без PCI DSS
— переадресуйте клиента на PaymentUrl
.AUTHORIZED
или CONFIRMED
будет передан параметр RebillId
.
Сохраните его.Recurrent
и CustomerKey
в этом случае не нужны. Вернется параметр PaymentId
— сохраните его.RebillId
из пункта 3 и PaymentId
из пункта 4.
При успешном сценарии операция перейдет в статус CONFIRMED
.Recurrent=Y
и CustomerKey
.мерчантов без PCI DSS
— переадресуйте клиента на PaymentUrl
.AUTHORIZED
или CONFIRMED
будет передан параметр RebillId
.
Сохраните его.Recurrent
и CustomerKey
в этом случае не нужны. Вернется параметр PaymentId
— сохраните его.RebillId
из пункта 3 и PaymentId
из пункта 4. TerminalKey required | string <= 20 characters Идентификатор терминала. |
PaymentId required | string <= 20 characters Уникальный идентификатор транзакции в системе Т‑Кассы. |
RebillId required | string Идентификатор рекуррентного платежа. Значение зависит от атрибутов:
Подробнее — в описаниях Рекуррентный платёж и Инициализация платежа |
Token required | string Подпись запроса. |
IP | string IP-адрес клиента. |
SendEmail | boolean
|
InfoEmail | string <email> Адрес почты клиента.
Обязателен при передаче |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "700001702044",
- "RebillId": "145919",
- "Token": "f5a3be479324a6d3a4d9efa0d02880b77d04a91758deddcbd9e752a6df97cab5",
- "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334",
- "SendEmail": true,
- "InfoEmail": "customer@test.com"
}
{- "TerminalKey": "TinkoffBankTest",
- "Amount": 100000,
- "OrderId": "21050",
- "Success": true,
- "Status": "NEW",
- "PaymentId": "13660",
- "ErrorCode": "0"
}
Отменяет платежную сессию. В зависимости от статуса платежа, переводит его в следующие состояния:
NEW
— CANCELED
;AUTHORIZED
— PARTIAL_REVERSED
, если отмена не на полную сумму;AUTHORIZED
— REVERSED
, если отмена на полную сумму;CONFIRMED
— PARTIAL_REFUNDED
, если возврат не на полную сумму;CONFIRMED
— REFUNDED
, если возврат на полную сумму.При оплате в рассрочку платеж можно отменить только в статусе AUTHORIZED
.
При оплате «Долями» делается частичный или полный возврат, если операция в статусе CONFIRMED
или PARTIAL_REFUNDED
.
Если платеж находился в статусе AUTHORIZED
, холдирование средств на карте
клиента отменяется. При переходе из статуса CONFIRMED
денежные средства возвращаются на карту клиента.
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
PaymentId required | string Идентификатор платежа в системе Т‑Кассы. |
Token required | string Подпись запроса — хэш |
IP | string IP-адрес клиента. |
Amount | number Сумма в копейках. Если не передан, используется При отмене статуса |
Receipt_FFD_12 (object) or Receipt_FFD_105 (object) JSON-объект с данными чека. Обязателен, если подключена онлайн-касса. Если отмена делается только по части товаров, данные, переданные в этом запросе, могут отличаться данных, переданных в Init. При полной отмене структура чека не передается, при частичной — передаются товары, которые нужно отменить. | |
Array of objects (ShopsCancel) Обязательный для маркетплейсов. JSON-объект с данными маркетплейса. | |
QrMemberId | string Код банка в классификации СБП, в который нужно выполнить возврат. Смотрите параметр |
Route | string Enum: "TCB" "BNPL" Способ платежа. |
Source | string Enum: "installment" "BNPL" Источник платежа. |
ExternalRequestId | string <= 256 characters Идентификатор операции на стороне мерчанта. Параметр не работает для операций по СБП. Обязателен для операций «Долями» и в рассрочку.
|
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "2304882",
- "Token": "c0ad1dfc4e94ed44715c5ed0e84f8ec439695b9ac219a7a19555a075a3c3ed24",
- "IP": "192.168.255.255",
- "Amount": 19200,
- "Receipt": {
- "FfdVersion": "string",
- "ClientInfo": {
- "Birthdate": "string",
- "Citizenship": "string",
- "DocumentСode": "21",
- "DocumentData": "string",
- "Address": "string"
}, - "Taxation": "osn",
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Customer": "78894325",
- "CustomerInn": "788621292",
- "Items": [
- {
- "AgentData": {
- "AgentSign": "paying_agent",
- "OperationName": "Позиция чека",
- "Phones": [
- "+790912312398"
], - "ReceiverPhones": [
- "+79221210697",
- "+79098561231"
], - "TransferPhones": [
- "+79221210697"
], - "OperatorName": "Tinkoff",
- "OperatorAddress": "г. Тольятти",
- "OperatorInn": "7710140679"
}, - "SupplierInfo": {
- "Phones": [
- "+79221210697",
- "+79098561231"
], - "Name": "ООО Вендор товара",
- "Inn": "7710140679"
}, - "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "Tax": "vat10",
- "PaymentMethod": "full_payment",
- "PaymentObject": "goods_with_marking_code",
- "UserData": "Данные пользователя ext.test.qa@tinkoff.ru",
- "Excise": "12.2",
- "CountryCode": "056",
- "DeclarationNumber": "12345678901",
- "MeasurementUnit": "шт",
- "MarkProcessingMode": "string",
- "MarkCode": {
- "MarkCodeType": "EAN8",
- "Value": "12345678"
}, - "MarkQuantity": {
- "Numerator": 1,
- "Denominator": 2
}, - "SectoralItemProps": {
- "FederalId": "001",
- "Date": "21.11.2020",
- "Number": "123/43",
- "Value": "test value SectoralItemProps"
}
}
], - "Payments": {
- "Cash": 90000,
- "Electronic": 50000,
- "AdvancePayment": 0,
- "Credit": 0,
- "Provision": 0
}
}, - "Shops": [
- {
- "ShopCode": "700456",
- "Amount": 10000,
- "Name": "Товар"
}
], - "QrMemberId": "77892",
- "Route": "BNPL",
- "Source": "BNPL",
- "ExternalRequestId": "1234556"
}
{- "TerminalKey": "TinkoffBankTest",
- "OrderId": "21057",
- "Success": true,
- "Status": "REVERSED",
- "OriginalAmount": 13000,
- "NewAmount": 5000,
- "PaymentId": "2304882",
- "ErrorCode": "0",
- "Message": "OK",
- "Details": "None",
- "ExternalRequestId": "756478567845678436"
}
СБП
отображается QR-код с текстом «Отсканируйте в приложении Т-Банка».
Мы указываем только информацию о Т-Банке, потому что не можем гарантировать, что другие банки позволяют сканировать QR-коды в своих приложениях.В процессе обработки платеж меняет свое состояние. Основные статусы и условия перехода в них:
Статус |
Правило перехода |
---|---|
NEW |
MAPI получил запрос Init. После этого он создает новый платеж со статусом NEW и возвращает его идентификатор в параметре PaymentId , а также ссылку на платежную форму в параметре PaymentURL . |
FORM_SHOWED |
Мерчант перенаправил клиента на страницу платежной формы PaymentURL и страница загрузилась у клиента в браузере. |
AUTHORIZING |
Платеж обрабатывается MAPI и платежной системой. |
AUTHORIZED |
Платеж авторизован, деньги заблокированы на карте клиента. |
CONFIRMING |
Подтверждение платежа обрабатывается MAPI и платежной системой. |
CONFIRMED |
Платеж подтвержден, деньги списаны с карты клиента. |
REFUNDING |
Мерчант запросил отмену подтвержденного платежа. Возврат обрабатывается MAPI и платежной системой. |
ASYNC_REFUNDING |
Обработка возврата денежных средств по QR. |
PARTIAL_REFUNDED |
Частичный возврат по подтвержденному платежу завершился успешно. |
REFUNDED |
Полный возврат по подтвержденному платежу завершился успешно. |
CANCELED |
Мерчант отменил платеж. |
DEADLINE_EXPIRED |
1. Клиент не завершил платеж в срок жизни ссылки на платежную форму PaymentURL . Этот срок мерчант передает в методе Init в параметре RedirectDueDate . 2. Платеж не прошел проверку 3D-Secure в срок. |
ATTEMPTS_EXPIRED |
Клиент превысил количество попыток открытия формы. |
REJECTED |
Банк отклонил платеж. |
AUTH_FAIL |
Платеж завершился ошибкой или не прошел проверку 3D-Secure. |
Статус |
Правило перехода |
---|---|
NEW |
MAPI получил запрос AddAccountQr или GetQr для сессии с рекуррентным платежом. |
PROCESSING |
QR сформирован и отправлен мерчанту. |
ACTIVE |
Привяза счета прошла успешно. |
INACTIVE |
Банк отклонил привязку счета. |
Изменения статуса платежа в этой операции показаны на схеме полного цикла платежа.
Статус |
Правило перехода |
---|---|
NEW |
MAPI получил запрос Init. После этого он создает новый платеж в статусе NEW и возвращает его идентификатор в параметре PaymentId . |
FORM_SHOWED |
MAPI принял запрос на обработку платежа. Ожидается подтверждение от НСПК о проведении оплаты по привязке. |
AUTHORIZING |
MAPI принял запрос от НСПК на авторизацию платежа. |
AUTHORIZED |
Платеж авторизован, деньги заблокированы на карте клиента. |
CONFIRMING |
Подтверждение платежа обрабатывается MAPI и платежной системой. |
CONFIRMED |
Платеж подтвержден, деньги списаны с карты клиента. |
REFUNDING |
Мерчант запросил отмену подтвержденного платежа. Возврат обрабатывается MAPI и платежной системой. |
ASYNC_REFUNDING |
Обработка возврата денежных средств по QR. |
PARTIAL_REFUNDED |
Частичный возврат по подтвержденному платежу завершился успешно. |
REFUNDED |
Полный возврат по подтвержденному платежу завершился успешно. |
CANCELED |
Мерчант отменил платеж. |
REJECTED |
Банк отклонил платеж. |
Если клиент привязывает счет к терминалу мерчанта, у которого есть несколько терминалов, клиент может выполнять рекуррентные платежи на всех терминалах мерчанта.
Процесс выглядит так:
А
и Б
, покупатель ранее проводил оплату только по терминалу А
.Б
.Б
.А
и разрешает проведение рекуррентного платежа.Откройте расчетный счёт в Т‑Банке — для этого заполните заявку.
Для подключения СБП клиент должен быть резидентом. Если клиент нерезидент, СБП работать не будет.
Подключите интернет-эквайринг — подайте заявку на подключение интернет-эквайринга и заполните данные об организации и магазине.
Выберите доступные типы интеграций.
СБП доступен для следующих типов интеграций:
Настройте интеграцию на сайте, в мобильном приложении или любом другом интерфейсе.
Расчётный счёт в Т‑Банке должен быть установлен в магазине как счёт для выплат.
СПБ включается в личном кабинете:
Войдите в свой личный кабинет и откройте страницу магазина, для которого вы хотите подключить оплату через СБП. Перейдите на вкладку Способы оплаты.
На плашке Система быстрых платежей нажмите Настроить.
Выберите способ интеграции, который планируете использовать:
Выберите вкладку Платежная форма Т‑Банка и нажмите Включить.
После подключения на экране появится сообщение «Система быстрых платежей включена».
Если у вас уже есть собственная платежная форма или вы хотите подключить виджет СБП, нажмите Включить на вкладке Своя платежная форма. После включения останется настроить интеграцию по API.
После подключения на экране появится сообщение «Система быстрых платежей включена».
Если вы планируете использовать СБП в своём приложении, нажмите Включить на вкладке Приложение и следуете инструкции из этого раздела в личном кабинете.
После подключения на экране появится сообщение «Система быстрых платежей включена».
Вне зависимости от того, какой способ интеграции вы используете, вы всегда можете скачать статический QR-код в разделе Статический QR-код.
После подключения СБП в личном кабинете, QR код автоматически отобразится на платежной форме — дополнительно ничего интегрировать не нужно.
Как интегрировать платежную форму на сайт
Платёжные формы Т‑Банка:
Способ
Оплата картой
обязательный — отключить его нельзя. Все остальные способы опциональные — их можно отключить в личном кабинете.
Если вы интегрируетесь по API, вы самостоятельно отображаете полученный QR-код или кнопку на вашем сайте или любом другом интерфейсе.
Если ваша интеграция настроена с Агентом ТСП:
Стикер со статичным QR кодом — платежный QR-код, который размещается в кассовой зоне магазина. Его можно скачать в личном кабинете после создания магазина.
Чтобы получить стикер с QR-кодом:
Покупателю будет нужно отсканировать стикер с QR-кодом, ввести сумму и подтвердить оплату.
При использовании стикера с QR-кодом операции не фискализируются через онлайн-кассы, даже если они подключены в личном кабинете.
После оплаты вам придет уведомление на электронную почту или по HTTP на ваш сервер — в зависимости от настроек.
Магазин — Выставление счетов
Уведомления настраиваются по почте — acq_help@tbank.ru.
Магазин — Интернет-магазин
Если у вас уже есть интернет-магазин, уведомления можно настроить самостоятельно в разделе Терминал.
Если вы интегрировались по API, можно настроить выбор банка при оплате по СБП. Для этого нужно создать прямую ссылку, которая перенаправит клиента в конкретное приложение банка при нажатии на нее.
Чтобы сформировать прямую ссылку на переход в приложение банка, замените
HTTPS из функциональной ссылки на значение параметра schema
из списка банков.
Пример
Функциональная ссылка — https://qr.nspk.ru/AS10004UVOQ9J4I489A8SG8NIA6P3F8B. Меняем HTTPS на соответствующую schema
Т‑Банка —
bank100000000004://qr.nspk.ru/AS10004UVOQ9J4I489A8SG8NIA6P3F8B
.
Для каждого из банков нужно сделать такую прямую ссылку и отобразить список банков
на вашей платёжной форме.
Вставьте код на ваш сайт туда, где должна располагаться кнопка Оплатить через СБП:
<html lang="ru">
<head>
<script defer src="https://securepay.tinkoff.ru/html/payForm/js/tinkoff_v2.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<style>.tinkoffPayRow{display:block;margin:1%;width:160px;}</style>
<!-- tinkoffWidgetContainer – уникальный id, задается произвольно-->
<div id="tinkoffWidgetContainer1"></div>
<form name="TinkoffPayForm">
<input class="tinkoffPayRow" type="hidden" name="terminalkey" value=""/>
<input class="tinkoffPayRow" type="hidden" name="language" value="ru" />
<input class="tinkoffPayRow" type="text" placeholder="Сумма заказа" name="amount" value="111" required min="10.00"/> <input class="tinkoffPayRow" type="text" placeholder="Номер заказа" name="order"/>
<input class="tinkoffPayRow" type="text" placeholder="Описание заказа" name="description"/>
<input class="tinkoffPayRow" type="text" placeholder="ФИО плательщика" name="name"/>
<input class="tinkoffPayRow" type="text" placeholder="E-mail" name="email"/>
<input class="tinkoffPayRow" type="text" placeholder="Контактный телефон" name="phone"/>
</form>
</body>
Сумма заказа amount
указывается в рублях, копейки — через точку.
Добавьте в код поле ввода receipt
:
<input class="tinkoffPayRow" type="hidden" name="receipt" value="">
В значении атрибута value
поля receipt
указываются параметры чека. Пример добавленного код:
const form = document.forms.TinkoffPayForm;
// Данные для чека
Object.defineProperty(form.receipt, 'value', {
get: function () {
return JSON.stringify({
Email: form.email.value,
Phone: form.phone.value,
EmailCompany: 'mail@mail.com',
Taxation: 'patent',
Items: [
{
Name: form.description.value || 'Оплата',
Price: form.amount.value + '00',
Quantity: 1.0,
Amount: form.amount.value + '00',
PaymentMethod: 'full_prepayment',
PaymentObject: 'service',
Tax: 'none',
},
],
});
},
});
Для подключения оплаты по СБП для одного и более товаров в методе InitPayments
нужно передавать массив paymentItems
— это настройки, которые определяют размещение платёжных кнопок и информацию о платеже.
Пример кода:
const terminalkey = document.forms.TinkoffPayForm.terminalkey;
const widgetParameters = {
terminalKey: terminalkey.value,
paymentItems: [
{
container: document.getElementById("tinkoffWidgetContainer1"),
paymentInfo: function () {
return {
paymentData: document.forms.TinkoffPayForm,
};
},
},
],
paymentSystems: { TinkoffFps: {} },
};
window.addEventListener("load", function () {
initPayments(widgetParameters);
});
Структура объекта массива paymentItems
:
Наименование | Обязательный | Тип данных | Описание |
---|---|---|---|
container |
Да | HTMLFormElement | Элемент, в который вставляют кнопки |
paymentInfo |
Да | Function/Object | Информация о платеже |
Вставьте идентификатор магазина в код платежного виджета в значение параметра terminalkey
. Идентификатор магазина выдаётся банком —
его можно получить в личном кабинете: раздел Магазины → вкладка Терминалы:
Если вам нужно изменить состав полей платежного виджета, у полей, которые хотите скрыть, укажите type
= hidden
:
<input class="tinkoffPayRow" type="hidden" placeholder="ФИО клиента" name="name">
Если вам нужно сделать поле обязательным для заполнения, добавьте к нему параметр required
:
<input class="tinkoffPayRow" type="text" placeholder="E-mail" name="email" required>
Платежный виджет стилизует магазин. Ограничений на стилизацию со стороны Т‑Банка нет:
<meta name="viewport" content="width=device-width, initial-scale=1">
<input class="tinkoffPayRow" type="hidden" placeholder="ФИО плательщика" name="name">
<input class="tinkoffPayRow" type="text" placeholder="E-mail" name="email" required>
<input class="tinkoffPayRow" type="hidden" name="terminalkey" value="Идентификатор вашего магазина">
Проверить статус платежа можно:
Протестировать оплату через СБП можно только на PROD-окружении и DEMO-терминале
Сценарий «Платеж — успех»
PaymentId
.CONFIRMED
.Сценарий «Платеж — отказ по таймауту»
PaymentId
) и параметр IsDeadlineExpired
= true
.DEADLINE_EXPIRED
.Сценарий «Платеж — отказ, отклонен Т‑Кассой»
PaymentId
) и параметр IsRejected
= true
.REJECTED
.Сценарий «Возврат — успех»
REFUNDED
.container | string ID элемента или элемент, в который вставляются кнопки. |
TerminalKey required | string Идентификатор вашего магазина. |
object (PaymentInfos) Информация о платеже. | |
Array of items Список объектов с информацией о размещаемых кнопках. | |
T-Payweb (object) or TbankFps (object) Объект с информацией о платежных системах. |
{- "container": "string",
- "TerminalKey": "string",
- "paymentInfo": {
- "InfoEmail": "string",
- "PaymentData": {
- "TerminalKey": "TinkoffBankTest",
- "Amount": 1751,
- "OrderId": "autoOrd1615285401068DELb",
- "Description": "string",
- "DATA": { },
- "Receipt": {
- "Items": [
- {
- "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "PaymentMethod": "full_prepayment",
- "PaymentObject": "commodity",
- "Tax": "vat10",
- "Ean13": "0123456789",
- "ShopCode": "12345",
- "AgentData": {
- "AgentSign": "paying_agent",
- "OperationName": "Позиция чека",
- "Phones": [
- "+790912312398"
], - "ReceiverPhones": [
- "+79221210697",
- "+79098561231"
], - "TransferPhones": [
- "+79221210697"
], - "OperatorName": "Tinkoff",
- "OperatorAddress": "г. Тольятти",
- "OperatorInn": "7710140679"
}, - "SupplierInfo": {
- "Phones": [
- "+79221210697",
- "+79098561231"
], - "Name": "ООО Вендор товара",
- "Inn": "7710140679"
}, - "FfdVersion": "1.05",
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Taxation": "osn",
- "Payments": {
- "Cash": 90000,
- "Electronic": 50000,
- "AdvancePayment": 0,
- "Credit": 0,
- "Provision": 0
}
}
]
}
}
}, - "paymentItems": [
- {
- "container": "string",
- "paymentInfo": {
- "InfoEmail": "string",
- "PaymentData": {
- "TerminalKey": "TinkoffBankTest",
- "Amount": 1751,
- "OrderId": "autoOrd1615285401068DELb",
- "Description": "string",
- "DATA": { },
- "Receipt": {
- "Items": [
- {
- "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "PaymentMethod": "full_prepayment",
- "PaymentObject": "commodity",
- "Tax": "vat10",
- "Ean13": "0123456789",
- "ShopCode": "12345",
- "AgentData": {
- "AgentSign": "paying_agent",
- "OperationName": "Позиция чека",
- "Phones": [
- "+790912312398"
], - "ReceiverPhones": [
- "+79221210697",
- "+79098561231"
], - "TransferPhones": [
- "+79221210697"
], - "OperatorName": "Tinkoff",
- "OperatorAddress": "г. Тольятти",
- "OperatorInn": "7710140679"
}, - "SupplierInfo": {
- "Phones": [
- "+79221210697",
- "+79098561231"
], - "Name": "ООО Вендор товара",
- "Inn": "7710140679"
}
}
]
}, - "FfdVersion": "1.05",
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Taxation": "osn",
- "Payments": {
- "Cash": 90000,
- "Electronic": 50000,
- "AdvancePayment": 0,
- "Credit": 0,
- "Provision": 0
}
}
}
}
], - "paymentSystems": {
- "TinkoffPay": { }
}
}
{- "Success": true
}
Метод регистрирует QR и возвращает информацию о нем. Вызывается после метода Init.
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
PaymentId required | number Уникальный идентификатор транзакции в системе Т‑Кассы. Запрос будет работать, даже если указать значение в формате |
DataType | string Default: "PAYLOAD" Enum: "PAYLOAD" "IMAGE" Тип возвращаемых данных:
|
Token required | string Подпись запроса. |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": 10063,
- "DataType": "PAYLOAD",
- "Token": "871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
}
{- "TerminalKey": "TinkoffBankTest",
- "OrderId": "21057",
- "Success": true,
- "PaymentId": 10063,
- "ErrorCode": "0",
- "Message": "Неверные параметры",
- "Details": "Подробное описание ошибки",
- "RequestKey": "Идентификатор запроса"
}
Метод возвращает список участников куда может быть осуществлен возврат платежа, совершенного по QR.
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
PaymentId required | string Уникальный идентификатор транзакции в системе. Т‑Кассы |
Token required | string Подпись запроса. |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "10063",
- "Token": "871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
}
{- "Members": [
- {
- "MemberId": "1000000",
- "MemberName": "T-Банк",
- "IsPayee": true
}
], - "OrderId": "21050",
- "Success": true,
- "ErrorCode": "0",
- "Message": "OK"
}
Метод инициирует привязку счета клиента к магазину и возвращает информацию о нем
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой. |
Description required | string Подробное описание деталей заказа. |
DataType | string Default: "PAYLOAD" Enum: "PAYLOAD" "IMAGE" Тип возвращаемых данных:
|
object JSON-объект, содержащий
дополнительные параметры в виде
Максимальное количество пар | |
RedirectDueDate | string <datatime> Cрок жизни ссылки или динамического QR-кода СБП, если выбран этот способ
оплаты. Если параметр Если текущая дата превышает дату, переданную в этом параметре, ссылка для оплаты или возможность платежа по QR-коду становятся недоступными и платёж выполнить нельзя.
|
Token required | string Подпись запроса. |
{- "TerminalKey": "TinkoffBankTest",
- "Description": "string",
- "DataType": "PAYLOAD",
- "Data": {
- "property1": "string",
- "property2": "string"
}, - "RedirectDueDate"": "2016-08-31T12:28:00+03:00",
- "Token": "871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
}
{- "TerminalKey": "TinkoffBankTest",
- "Description": "string",
- "DataType": "PAYLOAD",
- "RequestKey": "ed989549-d3be-4758-95c7-22647e03f9ec",
- "ErrorCode"": "0",
- "Success": true,
- "Message": "OK"
}
Метод возвращает статус привязки счета клиента по магазину
RequestKey required | string <uuid> Идентификатор запроса на привязку счета. |
TerminalKey required | string <= 20 characters Идентификатор терминала. Выдается мерчанту Т‑Кассой при заведении терминала. |
Token required | string Подпись запроса. |
{- "RequestKey": "13021e10-a3ed-4f14-bcd1-823b5ac37390",
- "TerminalKey": "TinkoffBankTest",
- "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96"
}
{- "TerminalKey": "TinkoffBankTest",
- "RequestKey": 211258,
- "BankMemberId": "100000000004",
- "BankMemberName": "T-Банк",
- "AccountToken": "a022254a5c3c46a7327c8a12cb5c8389",
- "Success": true,
- "Status": "ACTIVE",
- "ErrorCode": "0",
- "Message": "OK"
}
Метод возвращает список привязанных счетов клиента по магазину
TerminalKey required | string <= 20 characters Идентификатор терминала. Выдается мерчанту Т‑Кассой при заведении терминала. |
Token required | string Подпись запроса. |
{- "TerminalKey": "TinkoffBankTest",
- "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96"
}
{- "TerminalKey": "TinkoffBankTest",
- "Success": true,
- "ErrorCode": "0",
- "Message": "OK",
- "AccountTokens": {
- "RequestKey": "8de92934-26c9-474c-a4ce-424f2021d24d",
- "Status": "NEW",
- "AccountToken": "0b67f2cae19b41809f85d5674de30a1a",
- "BankMemberId": "5555",
- "BankMemberName": "T-Банк"
}
}
Проведение платежа по привязанному счету по QR через СБП. Для возможности его использования клиент должен совершить успешную привязку счета с помощью метода AddAccountQr. После вызова метода будет отправлена нотификация на Notification URL о привязке счета , в которой будет указан AccountToken. Для совершения платежа по привязанному счету Мерчант должен вызвать метод Init, в котором поля Recurrent= Y и DATA= {“QR”:“true”}, а затем вызвать метод ChargeQr для оплаты по тем же самым реквизитам и передать параметр AccountToken, полученный после привязки счета по QR в нотификации.
TerminalKey required | string <= 20 characters Идентификатор терминала. |
PaymentId required | string Уникальный идентификатор транзакции в системе Т‑Кассы. |
AccountToken required | string Идентификатор привязки счета, назначаемый банком-эмитентом. |
Token required | string Подпись запроса. |
IP | string IP-адрес клиента. |
SendEmail | boolean
|
InfoEmail | string <email> Адрес почты клиента. Обязательно, если передан параметр |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "700001702044",
- "AccountToken": "70LSS7DN18SJQRS10006DNPKLJL24B05",
- "Token": "f5a3be479324a6d3a4d9efa0d02880b77d04a91758deddcbd9e752a6df97cab5",
- "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334",
- "SendEmail": true,
- "InfoEmail": "customer@test.com"
}
{- "TerminalKey": "TinkoffBankTest",
- "Amount": 100000,
- "OrderId": "21050",
- "Success": true,
- "Status": "CONFIRMED",
- "PaymentId": "13660",
- "ErrorCode": "0",
- "Message": "Неверные параметры",
- "Details": "string",
- "Currency": 643
}
Тестовая платежная сессия с предопределенным статусом по СБП.
TerminalKey required | string <= 20 characters Идентификатор терминала, выдается мерчанту Т‑Кассой. |
PaymentId required | string <= 20 characters Идентификатор платежа в системе Т‑Кассы. |
Token required | string Подпись запроса. |
IsDeadlineExpired | boolean Признак эмуляции отказа проведения платежа банком по таймауту. По умолчанию не используется.
|
IsRejected | boolean Признак эмуляции отказа банка в проведении платежа. По умолчанию не используется.
|
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "13660",
- "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96",
- "IsDeadlineExpired": true,
- "IsRejected": false
}
{- "Success": true,
- "ErrorCode": "0",
- "Message": "OK",
- "Details": "0"
}
Возвращает статус возврата платежа по СБП
TerminalKey required | string Идентификатор терминала, выдается мерчанту Т‑Кассой |
PaymentId required | string Уникальный идентификатор транзакции в системе Т‑Кассы, полученный в ответе на вызов метода Init |
Token required | string Подпись запроса |
{- "TerminalKey": "TinkoffBankTest",
- "PaymentId": "700031849",
- "Token": "l43kb4hyi6lknb23bv4gdfskjn238fsllsdf8"
}
{- "Success": true,
- "ErrorCode": "0",
- "Status": "CONFIRMED",
- "QrCancelCode": "I05043",
- "QrCancelMessage": "У клиента нет расчетного счета в этом банке. Попробуйте вернуть деньги на счет этого клиента в другом банке",
- "OrderId": "7830122",
- "Amount": 10000,
- "Message": "OK"
}
Оплата доступна на мобильных устройствах и десктопах. Проводится последовательным вызовом методов:
/TinkoffPay/terminals/{terminalKey}/status
,/Init
,/TinkoffPay/transactions/{paymentId}/versions/{version}/link
или /TinkoffPay/{paymentId}/QR
.Виджет T‑Pay — способ интеграции через установку виджета на сайт.
Вставьте код на ваш сайт туда, где должна располагаться кнопка Оплатить:
<style>.tinkoffPayRow{display:block;margin:1%;width:160px;}</style>
<link rel="stylesheet" href="./html/payForm/static/css/t-widget.css" type="text/css >
<script src="https://securepay.tinkoff.ru/html/payForm/js/tinkoff.js ></script>
<form name="TinkoffPayForm" onsubmit="pay(this); return false; >
<input class="tinkoffPayRow" type="hidden" name="terminalkey" value="EatFit3DS >
<input class="tinkoffPayRow" type="hidden" name="frame" value="true">
<input class="tinkoffPayRow" type="hidden" name="language" value="ru">
<input class="tinkoffPayRow" type="text" placeholder="Сумма заказа" name="amount
required>
<input class="tinkoffPayRow" type="text" placeholder="Номер заказа" name="order">
<input class="tinkoffPayRow" type="text" placeholder="Описание заказа
name="description">
<input class="tinkoffPayRow" type="text" placeholder="ФИО клиента" name="name">
<input class="tinkoffPayRow" type="text" placeholder="E-mail" name="email">
<input class="tinkoffPayRow" type="text" placeholder="Контактный телефон
name="phone">
<input class="tinkoffPayRow" type="submit" value="Оплатить">
</form>
Вставьте идентификатор мерчанта в код платежного виджета в значение параметра terminalkey
. Идентификатор мерчанта выдается Т‑Кассой —
его можно получить в личном кабинете в разделе Магазины.
Если вам нужно изменить состав полей платежного виджета, у полей, которые хотите скрыть, укажите type
= hidden
:
<input class="tinkoffPayRow" type="hidden" placeholder="ФИО
клиента" name="name">
Если вам нужно сделать поле обязательным для заполнения, добавьте к нему параметр required
:
<input class="tinkoffPayRow" type="text" placeholder="E-mail"
name="email" required>
Если вам нужно открывать платежную форму в текущем окне, укажите у этого атрибута значение true
:
<input class="tinkoffPayRow" type="hidden" name="frame"
value="true">
Платежный виджет стилизует мерчант. Ограничений на стилизацию со стороны Т‑Кассы нет:
<input class="tinkoffPayRow" type="hidden" name="terminalkey"
value="Идентификатор вашего магазина">
Добавьте в код поле ввода receipt
:
<input class="tinkoffPayRow" type="hidden" name="receipt" value="">
В значении атрибута value
поля receipt
указываются параметры чека. Пример добавленного код:
const form = document.forms.TinkoffPayForm;
// Данные для чека
Object.defineProperty(form.receipt, 'value', {
get: function () {
return JSON.stringify({
Email: form.email.value,
Phone: form.phone.value,
EmailCompany: 'mail@mail.com',
Taxation: 'patent',
Items: [
{
Name: form.description.value || 'Оплата',
Price: form.amount.value + '00',
Quantity: 1.0,
Amount: form.amount.value + '00',
PaymentMethod: 'full_prepayment',
PaymentObject: 'service',
Tax: 'none',
},
],
});
},
});
При успешном подключении T‑Pay для интернет-магазина отобразится страница активного статуса подключения T‑Pay на сайте.
Вставьте код на ваш сайт туда, где должна располагаться кнопка T-Pay:
<div id="tinkoffWidgetContainer"></div>
<script type="text/javascript">
const terminalkey = document.forms.TinkoffPayForm.terminalkey
const widgetParameters = {
container: 'tinkoffWidgetContainer’,
terminalKey: terminalkey.value,
paymentSystems: {
TinkoffPay: {
paymentInfo: function () {
return {
infoEmail: "E-mail для отправки информации о платеже",
paymentData: document.forms.TinkoffPayForm
}
}
},
},
};
window.addEventListener('load', function () {
initPayments(widgetParameters);
});
</script>
Метод InitPayments запускает инициализацию платежных кнопок T‑Pay. Входной параметр метода widgetParameters
- объект с данными о настройках проведения платежей, где нужно определить параметры, описанные в структуре метода InitPayments.
Структура объекта T‑Pay
:
Наименование | Обязательность | Тип данных | Описание |
---|---|---|---|
paymentInfo |
Да | Function/Object | Платежная информация |
Для подключения оплаты по T-pay для одного и более товаров в методе InitPayments
нужно передавать массив paymentItems
— это настройки, которые определяют размещение платёжных кнопок и информацию о платеже.
Пример кода:
<div id="tinkoffWidgetContainer1"></div>
<div id="tinkoffWidgetContainer2"></div>
<script type="text/javascript">
const terminalkey = document.forms.TinkoffPayForm.terminalkey
const widgetParameters = {
terminalKey: terminalkey.value,
paymentItems: [{
container: document.getElementById('tinkoffWidgetContainer1'),
paymentInfo: function () {
return {
infoEmail: "E-mail для отправки информации о платеже",
paymentData: document.forms.TinkoffPayForm
}
}},
{
container: document.getElementById('tinkoffWidgetContainer2'),
paymentInfo: function () {
return {
infoEmail: "E-mail для отправки информации о платеже",
paymentData: document.forms.TinkoffPayForm
}
}}],
paymentSystems: {
TinkoffPay: {
},
},
};
window.addEventListener('load', function () {
initPayments(widgetParameters);
});
</script>
Структура объекта массива paymentItems
:
Наименование | Обязательность | Тип данных | Описание |
---|---|---|---|
container |
Да | HTMLFormElement | Элемент, в который вставляют кнопки |
paymentInfo |
Да | Function/Object | Платежная информация |
Для интеграции T‑Pay + T‑ID нужно настроить интеграцию с T‑ID. Подробнее про T-ID.
Вставьте код на ваш сайт туда, где должна располагаться кнопка Оплатить:
<link rel="stylesheet" href="https://securepay.tinkoff.ru/tpaytid/styles.css" media="print"
onload="this.media='all'">
<tinkoff-pay-id-button
terminalkey=”%yourterminalkey%”
redirectsuccess=false
rederectfail=false
></tinkoff-pay-id-button>
<script src="https://securepay.tinkoff.ru/tpaytid/tinkoff-pay-button.js" type="module"></
script>
Вставьте идентификатор магазина в код платежного виджета в значение параметра terminalkey
. Идентификатор магазина выдается Т‑Кассой —
его можно получить в личном кабинете в разделе Магазины.
Если вам нужен переход по ссылке в случае удачной оплаты,
выставите redirectsuccess
= true
или задайте атрибут у себя в коде:
const tpayIdButton = document.querySelector('tinkoff-pay-id-button');
tpayIdButton.setAttribute('redirectsuccess', true);
Если вам нужен переход по ссылке в случае удачной оплаты,
выставите redirectfail
= true
или задайте атрибут у себя в коде:
const tpayIdButton = document.querySelector('tinkoff-pay-id-button');
tpayIdButton.setAttribute('redirectfail', true);
Чтобы получать данные об оплате, подпишитесь на событие onSessionChange
:
const tpayIdButton = document.querySelector('tinkoff-pay-id-button');
tinkoffPayIdButton.addEventListener('onSessionChange', e => {
// Ваш код здесь
})
Структура объекта события о платеже — onSessionChange
:
Наименование |
Обязательность | Тип данных | Описание |
---|---|---|---|
eventType |
Да | String | Тип события |
sessionId |
Да | String | Идентификатор сессии |
paymentId |
Нет | Number | Идентификатор платежи |
accountId |
Нет | String | Идентификатор карты |
data |
Нет | Object | Набор параметров ключ-значение |
eventSessionId |
Нет | String | Идентификатор события открытия карт |
Чтобы реализовать сценарий T‑Pay + T‑ID, нужно установить виджет на сайте. Также нужно подписаться на события, которые генерирует
виджет, и дублировать их на backend в зашифрованном виде через метод /v2/TinkoffPayEvent
, передавая в нем данные о клиенте.
В данном случае это авторизационный токен AccessToken
, выпущенный T‑ID.
Есть три типа событий — для каждого передается набор параметров для последующей валидации:
Инициализация кнопки — процесс отображения кнопки.
Отображение счета — процесс отображения счетов, доступных клиенту для оплаты. Когда поступает событие с таким типом,
нужно создать платежную сессию эквайринга, если она еще не была создана — то есть если в параметрах события нет PaymentId
.
Это делается через метод /v2/Init с учетом особенностей T-Pay. Дальше есть несколько сценариев развития событий:
Оплата — проведение оплаты по выбранному счету.
Рекомендуем принимать результат авторизации асинхронно через нотификации.
container | string ID элемента или элемент, в который вставляются кнопки. |
TerminalKey required | string Идентификатор вашего магазина. |
object (PaymentInfos) Информация о платеже. | |
Array of items Список объектов с информацией о размещаемых кнопках. | |
T-Payweb (object) or TbankFps (object) Объект с информацией о платежных системах. |
{- "container": "string",
- "TerminalKey": "string",
- "paymentInfo": {
- "InfoEmail": "string",
- "PaymentData": {
- "TerminalKey": "TinkoffBankTest",
- "Amount": 1751,
- "OrderId": "autoOrd1615285401068DELb",
- "Description": "string",
- "DATA": { },
- "Receipt": {
- "Items": [
- {
- "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "PaymentMethod": "full_prepayment",
- "PaymentObject": "commodity",
- "Tax": "vat10",
- "Ean13": "0123456789",
- "ShopCode": "12345",
- "AgentData": {
- "AgentSign": "paying_agent",
- "OperationName": "Позиция чека",
- "Phones": [
- "+790912312398"
], - "ReceiverPhones": [
- "+79221210697",
- "+79098561231"
], - "TransferPhones": [
- "+79221210697"
], - "OperatorName": "Tinkoff",
- "OperatorAddress": "г. Тольятти",
- "OperatorInn": "7710140679"
}, - "SupplierInfo": {
- "Phones": [
- "+79221210697",
- "+79098561231"
], - "Name": "ООО Вендор товара",
- "Inn": "7710140679"
}, - "FfdVersion": "1.05",
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Taxation": "osn",
- "Payments": {
- "Cash": 90000,
- "Electronic": 50000,
- "AdvancePayment": 0,
- "Credit": 0,
- "Provision": 0
}
}
]
}
}
}, - "paymentItems": [
- {
- "container": "string",
- "paymentInfo": {
- "InfoEmail": "string",
- "PaymentData": {
- "TerminalKey": "TinkoffBankTest",
- "Amount": 1751,
- "OrderId": "autoOrd1615285401068DELb",
- "Description": "string",
- "DATA": { },
- "Receipt": {
- "Items": [
- {
- "Name": "Наименование товара 1",
- "Price": 10000,
- "Quantity": 1,
- "Amount": 10000,
- "PaymentMethod": "full_prepayment",
- "PaymentObject": "commodity",
- "Tax": "vat10",
- "Ean13": "0123456789",
- "ShopCode": "12345",
- "AgentData": {
- "AgentSign": "paying_agent",
- "OperationName": "Позиция чека",
- "Phones": [
- "+790912312398"
], - "ReceiverPhones": [
- "+79221210697",
- "+79098561231"
], - "TransferPhones": [
- "+79221210697"
], - "OperatorName": "Tinkoff",
- "OperatorAddress": "г. Тольятти",
- "OperatorInn": "7710140679"
}, - "SupplierInfo": {
- "Phones": [
- "+79221210697",
- "+79098561231"
], - "Name": "ООО Вендор товара",
- "Inn": "7710140679"
}
}
]
}, - "FfdVersion": "1.05",
- "Email": "a@test.ru",
- "Phone": "+79031234567",
- "Taxation": "osn",
- "Payments": {
- "Cash": 90000,
- "Electronic": 50000,
- "AdvancePayment": 0,
- "Credit": 0,
- "Provision": 0
}
}
}
}
], - "paymentSystems": {
- "TinkoffPay": { }
}
}
{- "Success": true
}
Метод для определения возможности проведения платежа T‑Pay на терминале и устройстве.
TerminalKey required | string <= 20 characters Example: testRegress Платежный ключ, выдается мерчанту при заведении терминала. |
{- "Params": {
- "Allowed": true,
- "Version": "1.0"
}, - "Success": true,
- "ErrorCode": "0",
- "Message": "string",
- "Details": "string"
}
Метод получения Link для безусловного редиректа на мобильных устройствах
paymentId required | number <= 20 characters Example: 13660 Идентификатор платежа в системе Т‑Кассы |
version required | string Example: 2.0 Версия T‑Pay, доступная на терминале:
|
{- "summary": "Пример ответа",
- "value": {
- "Success": true,
- "ErrorCode": "0",
- "Message": "string",
- "Details": "string"
}
}
Передача уведомления о событии платежного виджета T‑Pay + T‑ID.
TerminalKey required | string Идентификатор терминала. Выдается мерчанту Т‑Кассой при заведении терминала. |
required | object (EventData) |
PaymentId | string Идентификатор платежа. |
Token required | string Подпись запроса. |
{- "TerminalKey": "string",
- "EventData": {
- "SessionId": "string",
- "Type": "string",
- "AccessToken": "string",
- "AccountId": "string",
- "EventSessionId": "string"
}, - "PaymentId": "string",
- "Token": "string"
}
{- "Success": true,
- "ErrorCode": "0",
- "Message": "string",
- "Details": "string"
}
При успешном подключении SberPay для интернет-магазина должна отобразиться страница активного статуса подключения SberPay на сайте.
SberPay не работает для мерчантов интегрированных через InSales.
Требования к функционалу и дизайну кнопки определяются Сбербанком:
Оплата доступна на мобильных устройствах и десктопах. Проводится последовательным вызовом методов:
/Init
,/SberPay/transactions/{PaymentId}/link
или /SberPay/{PaymentId}/QR
,/Confirm
,/Cancel
.returnUrl
не допускается использование символов: +, &, @, #, /, %, =, ~, _, |Data
:"DATA": {
"SberPayWeb": "true",
"Device": "Desktop"
}
Из-за особенностей работы эквайринга Сбербанка подтвердить платежную сессию можно сделать только один раз — либо частично, либо полностью.
Также из-за асинхронной обработки запросов на подтверждение платеж может вернуться в статусе CONFIRMING
,
если у сервисов партнера возникнут проблемы с производительностью.
Из-за особенностей работы эквайринга Сбербанка отменить платежную сессию можно только один раз и только на полную сумму платежа.
Возврат можно делать несколько раз — как частично, так и полностью — до тех пор, пока не будет исчерпана сумма платежа.
Также из-за асинхронной обработки запросов на подтверждение платеж может вернуться в статусе REVERSING
или REFUNDING
,
если у сервисов партнера возникнут проблемы с производительностью.
Метод для получения ссылки SberPay.
paymentId required | number Example: 700001702044 Уникальный идентификатор транзакции в системе Т‑Кассы. |
{- "Params": {
- "RedirectUrl": "tinkoffbank://Main/EInvoicing?billId=5000015507&providerId=e-invoicing"
}, - "Success": true,
- "ErrorCode": "0",
- "Message": "string",
- "Details": "string"
}