Прием платежей (1.31)

Интернет-эквайринг помогает принимать онлайн-платежи так, как удобно вам и покупателю: на сайте, в мобильном приложении, соцсетях, мессенджерах, по e-mail или СМС. Вы можете принимать оплату разными способами, возвращать и замораживать выплаты и настраивать рекуррентные платежи.

Чтобы подключить интернет-эквайринг, оставьте заявку на сайте Т‑Банка и заполните анкету компании или ИП. Подробнее о подключении можно прочитать в Т-Помощи или узнать у персонального менеджера.

Интернет-эквайринг нужно интегрировать — настроить оплату на сайте или в приложении. Есть четыре способа интеграции:

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

Интегрироваться можно самостоятельно или с помощью разработчика.

Платежный модуль

Способ интеграции интернет-эквайринга с сайтом, который создан на основе CMS.

Модуль подходит, если ваш сайт собран на CMS — например, 1С-Битрикс, WordPress или Taplink. Т‑Касса поддерживает многие популярные CMS, в некоторые уже встроены модули — их устанавливать не нужно.

Принцип работы:

1. Вы устанавливаете модуль и настраиваете способы оплаты — банковская карта, T‑Pay, SberPay, Mir Pay, СБП, Долями, в рассрочку.
   Можно оставить все способы или выбрать определённые.
2. На странице сайта появляется кнопка оплаты.
3. Покупатель нажимает на кнопку и переходит на платежную форму с разными способами оплаты.

На этой странице представлен список систем управления контентом (CMS), для которых разработаны платежные модули. Если вашего решения нет в этом списке, мы рекомендуем настроить передачу объекта DATA с параметром connection_type. В этом параметре укажите название модуля, через который вы интегрируетесь. Более подробную информацию вы можете в описании метода Init. Если у вас возникнут вопросы или потребуется дополнительная настройка, пожалуйста, обратитесь в техническую поддержку вашего модуля.

Инструкции по интеграции с помощью платежного модуля

Платежный виджет

Способ интеграции интернет-эквайринга с самописным сайтом.

Виджет подходит, если:

• ваш сайт самописный или на CMS, для которой в Т‑Банке нет платежного модуля;
• вы не планируете принимать автоплатежи.

Принцип работы:

1. Вы вставляете готовый код на страницу сайта и настраиваете способы оплаты — банковская карта, T‑Pay, SberPay, Mir Pay, СБП, Долями, в рассрочку.
   Можно оставить все способы или выбрать определённые.
2. На месте кода появляется кнопка оплаты.
3. Покупатель нажимает на кнопку и переходит на платежную форму с разными способами оплаты.

Для интеграции виджета потребуется помощь программиста.

Инструкция по интеграции с помощью виджета

Мобильный SDK

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

С помощью SDK вы можете:

• Разместить платежную форму Т‑Кассы со всеми или некоторыми способами оплаты.
• Отдельно встраивать способы оплаты в вашу платежную форму — например, T‑Pay или СБП.

Инструкции по подключению SDK в личном кабинете:

• Инструкция для Android начиная с версии 7.0

• Инструкция для iOS начиная с версии 12.3

API

Самый гибкий и сложный способ интеграции интернет-эквайринга. Например, API подходит, если у вас самописный сайт и вы хотите настроить оплату под запросы бизнеса — совмещать в платежной форме разные способы оплаты, принимать рекуррентные платежи или подключать другие сервисы Т‑Кассы.

Для интеграции понадобится помощь программиста.

Документация API

Платежная форма — это готовый интерфейс с встроенными способами оплаты, который позволяет принимать платежи онлайн.

Для использования платежной формы нужно подключить интернет-эквайринг, настроить терминал и интегрировать платежную форму на ваш сайт одним из способов выше — кроме SDK.

Платежная форма в WebView

Некоторые WebView не умеют обрабатывать DeepLink-ссылки. Из-за этого способы оплаты, которые выполняют переход в мобильное приложение во время платежа, могут работать некорректно — например, СБП, Mir Pay, T‑Pay.

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

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

Примеры решений:

1. Первое решение (java,kotlin).
2. Второе решение (java).

Рекомендации по интеграции

Платформа IOS

Чтобы DeepLink работал в Web, есть два варианта решения:

1. Использовать SFSafariViewController — он умеет открывать диплинки, дополнительная настройка не нужна.
2. Обработать открытие диплинка Т‑Банка — если используете WKWebView: он не умеет открывать диплинки из коробки.

Пример реализации обработки открытия диплинка Т‑Банка:

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

Мы не рекомендуем использовать платежную форму в iframe для мобильных версий сайтов — у кнопочных способов оплаты могут возникать проблемы с открытием DeepLink и переходов в мобильное приложение для оплаты: СБП, Mir Pay, T‑Pay. Это связано с тем, что iframe — изолированный контейнер. Из-за этого переходы на сторонние ссылки не могут обрабатываться внутри iframe.

Если вам нужно использовать iframe в мобильной версии сайта, сделайте доработки по инструкции ниже, чтобы использовать кнопочные способы оплаты. Это позволит произвести переход в стороннее приложение. Доработки представляют собой скрипт «снаружи» iframe, который получит сообщение о переходе от iframe и вызовет его на основной странице.

После реализации доработок нужно протестировать корректную работу всех способов оплат. Если у вас возникнут проблемы или вопросы, обратитесь в нашу поддержку — acq_help@tbank.ru.

В десктопной версии 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>

<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>

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 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 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>

Кастомизация платежной формы

Платежную форму можно кастомизировать — настроить под себя и своих клиентов. Для установки кастомизации обратитесь к вашему персональному менеджеру и передайте пожелания по настройкам.

Список доступных настроек кастомизации

Убедитесь, что вы используете последнюю версию интеграции и генерируете и передаете корректный токен при любом способе интеграции.

Если ваш сайт собран на CMS, нужно использовать новейшую версию платежного модуля, доступную на сайте Т‑Кассы — это источник актуальных версий. Современные модули для популярных CMS генерируют корректный токен автоматически.

Дополнительные обязательные меры, которые нужно соблюдать при интеграции с MAPI:

• Наиболее безопасный способ передачи данных от мерчанта в MAPI — прямая интеграция бэкенда мерчанта с бэкендом Т‑Кассы. В этом случае злоумышленник сможет перехватить запрос только если окажется в локальной сети мерчанта.

• Сверяйте параметры созданных заказов при любых способах интеграции с MAPI, в том числе с помощью нашего платежного виджета. Если выявляются расхождения между суммой операции, инициированной клиентом, и суммой совершенной операции, не доставляйте товар клиенту и уведомите об этом Т‑Банк. Для сверки параметров есть несколько способов:

  • Получение нотификаций:

    • По электронной почте — на указанную почту придет письмо при переходе платежа в статус CONFIRMED.

    • По HTTP — MAPI будет отправлять POST-запрос при каждом изменении статуса платежа на URL, который указан в настройках терминала.

  • Вызов метода GetState, который возвращает основные параметры и текущий статус платежа. Рекомендуем сверять или валидировать дополнительные данные заказа — PaymentId и Amount.

• Обновляйте модули для CMS. Современные модули для популярных CMS сверяют суммы заказов автоматически.

Если вы не применяете эти меры безопасности на вашем сайте или используете программное обеспечение для интеграции не с сайта Т‑Кассы, вы сами отвечаете за возможные риски и неблагоприятные последствия, связанные с использованием такого программного обеспечения.

Платежные системы разработали требования к безопасности карточных данных клиентов — Payment Card Industry Data Security Standard (PCI DSS). Компания должна пройти сертификацию, чтобы подтвердить надежность управления карточной информацией.

Если:

• У вас нет сертификации PCI DSS, вы можете использовать платежную форму Т‑Кассы. В этом случае все операции, которые связаны с обработкой критичных данных, проводятся на стороне Т‑Кассы. Мерчанту достаточно настроить интеграцию с MerchantAPI и инициализировать платеж. Клиент будет перенаправлен на платежную форму, в которую он сможет ввести данные карты. Когда платеж завершится, клиент снова увидит сайт мерчанта.

• Ваш ресурс соответствует требованиям PCI DSS, вы можете собирать и хранить карточные данные клиентов. В этом случае MerchantAPI получает зашифрованные карточные данные от мерчанта.

Подробнее о подключении эквайринга с и без PCI DSS

Платежные системы хотят понимать, кем была инициирована карточная операция. Это особенно важно при проведении операций без 3DS и по сохраненным данным.

Для выполнения требования регулятора мы добавили новый атрибут OperationInitiatorType в метод Init. В значении этого атрибута мы ожидаем получать признак того, кем была инициирована операция и какой способ предоставления реквизитов был использован.

Подробное описание сценариев проведения операций, значений OperationInitiatorType, взаимосвязь с другими атрибутами и типами терминалов:

Каждый терминал обладает свойствами, которые влияют на те или иные аспекты приёма платежей. Эти свойства настраиваются при подключении интернет-эквайринга и могут быть изменены в личном кабинете мерчанта.

Основные параметры приёма платежей для терминала:

* В 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"
      }
    ]
  }
}

Чтобы зашифровать данные запроса, мерчанту нужно:

1. Собрать массив передаваемых данных в виде пар ключ-значения. В массив нужно добавить только параметры корневого объекта. Вложенные объекты и массивы не участвуют в расчете токена. В примере в массив включены параметры TerminalKey, Amount, OrderId, Description и исключен объект Receipt и DATA.

[{"TerminalKey": "MerchantTerminalKey"},{"Amount": "19200"},{"OrderId": "21090"},{"Description": "Подарочная карта на 1000 рублей"}]

2. Добавить в массив пару {Password, Значение пароля}. Пароль можно найти в личном кабинете мерчанта.

[{"TerminalKey": "MerchantTerminalKey"},{"Amount": "19200"},{"OrderId": "21090"},{"Description": "Подарочная карта на 1000 рублей"},{"Password": "usaf8fw8fsw21g"}]

3. Отсортировать массив по алфавиту по ключу.

[{"Amount": "19200"},{"Description": "Подарочная карта на 1000 рублей"},{"OrderId": "21090"},{"Password": "usaf8fw8fsw21g"},{"TerminalKey": "MerchantTerminalKey"}]

4. Конкатенировать только значения пар в одну строку.

"19200Подарочная карта на 1000 рублей21090usaf8fw8fsw21gMerchantTerminalKey"

5. Применить к строке хеш-функцию SHA-256 (с поддержкой UTF-8).

"0024a00af7c350a3a67ca168ce06502aa72772456662e38696d48b56ee9c97d9"

6. Добавить получившийся результат в значение параметра 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.

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

Основная сущность в интернет-эквайринге Т‑Кассы — платеж. В зависимости от настроек терминала, платеж может идти по двум сценариям:

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

Настроить способ приема на терминале можно в личном кабинете мерчанта или передать нужный тип в параметре PayType при вызове метода Init.

Стандартный платеж для мерчантов с PCI DSS

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

Чтобы создать платеж, мерчант должен инициировать его через метод Init — передать сумму платежа и номер заказа.

При вызове метода Init в объекте DATA в атрибуте OperationInitiatorType нужно передавать признак инициатора операции. В ответ MAPI создаст новый платеж в статусе NEW и вернёт его идентификатор в параметре PaymentId.

После этого мерчант вызывает метод Check3DSVersion, в котором передает зашифрованные карточные данные клиента и PaymentId. Это нужно для проверки версии протокола 3D-Secure по карте. Она может быть версии 1.0 или 2.0.

Если в ответе метода Check3DSVersion есть параметр ThreeDSMethodURL, браузер клиента должен вызывать ресурс, адрес которого пришел в параметре ThreeDSMethodURL. В запросе нужно передать строковый параметр threeDSMethodData. Эта строка — закодированный в формате base64 JSON-объект с параметрами:

Браузер должен вызвать 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 карточные данные клиента, продолжая обработку платежа.

Если платеж:

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

В ответ MAPI вернет один из статусов:

Без 3DS-подтверждения

Если по платежу не нужно проходить подтверждение 3DS, в ответе FinishAuthorize MAPI вернет один из трех конечных статусов платежа:

• CONFIRMED — при одностадийном платеже;
• AUTHORIZED — при двухстадийном платеже;
• REJECTED — при отказе в проведении платежа.

С 3DS-подтверждением

Если в ответе метода FinishAuthorize вернулся статус 3DS_CHECKING — значит, нужно пройти проверку 3D-Secure. Для этого мерчант должен сформировать запрос в сервис аутентификации банка, выпустившего карту. Адрес сервиса возвращается в ответе FinishAuthorize в параметре ACSUrl. Вместе с этим нужно перенаправить клиента для прохождения 3DS на эту же страницу — ACSUrl.

В заголовке запроса нужно передать параметр Content-Type со значением application/x-www-form-urlencoded. Набор параметров в теле запросе зависит от версии протокола 3DS по карте.

Проводить тестовые платежи можно только на тестовом окружении.

3DS 1.0

Если версия 3DS — 1.0, в запросе передаются параметры:

3DS 2.0

Если версия 3DS — 2.0, в запросе передаются параметры в зависимости от типа устройства клиента. Тип устройства передается в запросе FinishAuthorize в параметре deviceChannel. Возможны два варианта — браузер (BRW, код 02) и приложение (APP, код 01).

Параметры для браузера:

Строка creq для браузера формируется из следующих параметров:

Параметры для приложения:

Строка creq для приложения формируется из следующих параметров:

Подтверждение прохождения 3DS

Когда сервис аутентификации банка, который выпустил карту, прислал результат прохождения 3D-Secure, мерчант должен передать эту информацию в MAPI. В зависимости от версии протокола 3DS нужно вызвать один из методов:

• Для 3DS 1.0 — Submit3DSAuthorization.
• Для 3DS 2.0 — Submit3DSAuthorizationV2.

Стандартный платеж для мерчантов без PCI DSS

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

Чтобы создать платеж, мерчант должен инициировать его через метод Init — передать сумму платежа и номер заказа. При успешном прохождении запроса в ответе метода Init вернется параметр PaymentURL, на который нужно переадресовать клиента. При переходе на PaymentURL клиенту откроется платежная форма Т‑Кассы, где нужно ввести реквизиты карты, а после этого — этап прохождения 3DS.

Методы Authorize и FinishAuthorize вызываются системами Т‑Кассы при переадресации клиента на PaymentURL — параметр возвращается в ответе метода Init. Актуально для мерчантов, которые используют платежную форму Т-Банка.

При вызове метода Init в объекте DATA в атрибуте OperationInitiatorType нужно передавать признак

Метод Authorize

Вызывается автоматически при переадресации клиента на страницу PaymentURL, которая возвращается в ответе метода Init. Статус платежа выставляется в FORM_SHOWED.

Метод FinishAuthorize

Подтверждает инициированный платеж передачей карточных данных и списывает деньги с карты клиента.

Исполнение платежа на платежной форме Т‑Кассы

Вызывается формой оплаты по адресу PaymentURL, когда клиент вводит данные карты и нажимает кнопку Оплатить.

Статус перевода:

• CONFIRMED — при успешном сценарии;
• REJECTED — при неуспешном.

Клиент переадресовывается на:

• Success URL — при успешном переводе;
• Fail URL — при неуспешном переводе.

Завершение платежа

Если платёж завершился успешно, клиент будет перенаправлен на страницу Success URL из настроек терминала.

Двухстадийный платеж

Двухстадийный платеж включает два этапа:

1. Банк проверяет наличие средств у клиента и блокирует их — холдирует.
2. Мерчант подтверждает списание средств или отменяет блокировку.

Когда клиент оплачивает заказ, деньги за покупку замораживаются (холдируются) на его счете до семи дней. Если за это время клиент:

• Отказался от заказа — он автоматически получает деньги обратно, а компания избегает комиссии за эквайринг.
• Не стал отказываться от товара и вы подтвердили продажу в течение семи дней, деньги на его счете размораживаются и поступают на счет компании. В этом случае Т‑Касса списывает комиссию.

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

Техническая реализация двухстадийных платежей

Если терминал настроен на прием двухстадийных платежей, после вызова метода 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 мерчант передает сумму, которая вернется клиенту.

{
    "Name": "Item12",
    "Price": 50000,
    "Quantity": 0.1,
    "Amount": 5000,
    "Tax": "none",
    "PaymentObject": "service"
}

Мерчант может получить информацию об основных параметрах платежа в любой момент.

Если нужно получить данные по конкретному платежу, мерчанту нужно вызвать метод GetState и передать PaymentId в запросе.

Если по одному заказу было несколько платежей, получить историю платежей и их текущий статус можно через метод CheckOrder — в запросе нужно передать OrderId.

OrderId не является уникальным параметром. Рекомендуем сверять дополнительные данные заказа — PaymentId и Amount.

В процессе обработки платеж меняет свое состояние. Основные статусы и условия перехода в них:

ВАЖНО! Тестовый терминал (DEMO) не поддерживает проверку 3DS. Для тестирования 3DS нужно использовать боевой терминал в связке с тестовой средой (https://rest-api-test.tinkoff.ru/v2)

• Покупатель выбирает банк на своём устройстве — через API это настроить нельзя.
• Если оплата СБП отклоняется на стороне эмитента, эквайер на своей стороне не может повлиять на это.
• На платежной форме банка при выборе способа оплаты СБП отображается QR-код с текстом «Отсканируйте в приложении Т-Банка». Мы указываем только информацию о Т-Банке, потому что не можем гарантировать, что другие банки позволяют сканировать QR-коды в своих приложениях.
• По СБП нет двухстадийной оплаты, поэтому средства нельзя захолдировать даже при рекуррентном платеже.
• СБП не работает для маркетплейсов.
• Протестировть оплату через СБП можно только на PROD-окружении и DEMO-терминале.

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

В процессе обработки платеж меняет свое состояние. Основные статусы и условия перехода в них:

Таблица статусов привязки счёта

Схема привязки счёта

Схема с переходами статуса привязки счета при оплате с одновременной привязкой

Изменения статуса платежа в этой операции показаны на схеме полного цикла платежа.

Таблица статусов рекуррентного платежа

Схема проведения рекуррентого платежа

Логика привязки при наличии нескольких терминалов

Если клиент привязывает счет к терминалу мерчанта, у которого есть несколько терминалов, клиент может выполнять рекуррентные платежи на всех терминалах мерчанта.

Процесс выглядит так:

1. Мерчанту принадлежат терминалы А и Б, покупатель ранее проводил оплату только по терминалу А.
2. Покупатель пробует провести рекуррентный платеж по терминалу Б.
3. Система проверяет наличие привязки по терминалу Б.
4. Так как привязка по этому терминалу не проводилась, система с помощью идентификатора магазина проверяет наличие привязки на других терминалах мерчанта.
5. Система успешно находит привязку по терминалу А и разрешает проведение рекуррентного платежа.

1. Откройте расчетный счёт в Т‑Банке — для этого заполните заявку.

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

2. Подключите интернет-эквайринг — подайте заявку на подключение интернет-эквайринга и заполните данные об организации и магазине.

3. Выберите доступные типы интеграций.

   СБП доступен для следующих типов интеграций:

   • Платежный виджет.
   • Платежный API.
   • Мобильный SDK.
   • Через Агента ТСП.
   • Стикер с QR-кодом для размещения на кассе.

4. Настройте интеграцию на сайте, в мобильном приложении или любом другом интерфейсе.

Расчётный счёт в Т‑Банке должен быть установлен в магазине как счёт для выплат.

СПБ включается в личном кабинете:

1. Войдите в свой личный кабинет и откройте страницу магазина, для которого вы хотите подключить оплату через СБП. Перейдите на вкладку Способы оплаты.

   

2. На плашке Система быстрых платежей нажмите Настроить.

3. Выберите способ интеграции, который планируете использовать:

Платежная форма Т‑Банка

Выберите вкладку Платежная форма Т‑Банка и нажмите Включить.

После подключения на экране появится сообщение «Система быстрых платежей включена».

Собственная платежная форма

Если у вас уже есть собственная платежная форма или вы хотите подключить виджет СБП, нажмите Включить на вкладке Своя платежная форма. После включения останется настроить интеграцию по API.

После подключения на экране появится сообщение «Система быстрых платежей включена».

Приложение

Если вы планируете использовать СБП в своём приложении, нажмите Включить на вкладке Приложение и следуете инструкции из этого раздела в личном кабинете.

После подключения на экране появится сообщение «Система быстрых платежей включена».

Статический QR

Вне зависимости от того, какой способ интеграции вы используете, вы всегда можете скачать статический QR-код в разделе Статический QR-код.

Настройка интеграций при включении способа оплаты СБП

Платежная форма Т‑Банка

После подключения СБП в личном кабинете, QR код автоматически отобразится на платежной форме — дополнительно ничего интегрировать не нужно.

Как интегрировать платежную форму на сайт

Платёжные формы Т‑Банка:

Мобильная

Десктопная

Способ Оплата картой обязательный — отключить его нельзя. Все остальные способы опциональные — их можно отключить в личном кабинете.

API

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

SDK

Если ваша интеграция предусматривает использование мобильного приложения, в SDK нужно передать специальные параметры для отображения QR кода — IOS, Android.

Интерфейс SDK Т‑Банка

Агентская интеграция

Если ваша интеграция настроена с Агентом ТСП:

1. Создайте магазин типа Выставление счета.
2. Включите СБП в способах оплаты.
3. Сообщите Агенту ТСП об успешном включении.

Прием платежей с помощью стикеров с QR-кодом

Стикер со статичным QR кодом — платежный QR-код, который размещается в кассовой зоне магазина. Его можно скачать в личном кабинете после создания магазина.

Получить стикер

Чтобы получить стикер с QR-кодом:

1. Создайте магазин с выставлением счета. Если у вас уже есть магазин, переходите к пункту 2.
2. В разделе Способы оплаты перейдите в настройки СБП.
3. В разделе Статический QR нажмите Скачать.
4. Распечатайте и разместите QR-код в кассовой зоне вашего магазина.

QR-стикер Т‑Банка

Покупателю будет нужно отсканировать стикер с QR-кодом, ввести сумму и подтвердить оплату.

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

Уведомления об оплате

После оплаты вам придет уведомление на электронную почту или по HTTP на ваш сервер — в зависимости от настроек.

Магазин — Выставление счетов

Уведомления настраиваются по почте — acq_help@tbank.ru.

Магазин — Интернет-магазин

Если у вас уже есть интернет-магазин, уведомления можно настроить самостоятельно в разделе Терминал.

Настроить выбор банка при интеграции по API

Если вы интегрировались по 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:

Вставьте идентификатор магазина в код платежного виджета в значение параметра 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="Идентификатор вашего магазина"> 

Проверить статус платежа можно:

• В личном кабинете интернет-эквайринга, просмотрев операции по СБП.
• По API — через метод GetState или с помощью уведомлений по HTTP или на электронную почту. Подробнее.

Протестировать оплату через СБП можно только на PROD-окружении и DEMO-терминале

Сценарий «Платеж — успех»

1. Инициируйте начало платежной сессии — вызовите метод Init.
2. Запросите формирование динамического QR-кода через метод GetQr.
3. Отобразите динамический QR-код на странице клиенту.
4. Вызовите метод SbpPayTest, передавав в нем внутренний идентификатор платежной сессии Т‑Кассы — PaymentId.
5. Запросите текущий статус платежа через метод GetState.
6. Вернется ответ со статусом CONFIRMED.

Сценарий «Платеж — отказ по таймауту»

1. Инициируйте начало платежной сессии — вызовите метод Init.
2. Запросите формирование динамического QR-кода через метод GetQr.
3. Отобразите динамический QR-код на странице клиенту.
4. Вызовите метод SbpPayTest, передавав в нем внутренний идентификатор платежной сессии Т‑Кассы (PaymentId) и параметр IsDeadlineExpired = true.
5. Запросите текущий статус платежа через метод GetState.
6. Вернется ответ со статусом DEADLINE_EXPIRED.

Сценарий «Платеж — отказ, отклонен Т‑Кассой»

1. Инициируйте начало платежной сессии — вызовите метод Init.
2. Запросите формирование динамического QR-кода через метод GetQr.
3. Отобразите динамический QR-код на странице клиенту.
4. Вызовите метод SbpPayTest, передавав в нем внутренний идентификатор платежной сессии Т‑Кассы (PaymentId) и параметр IsRejected = true.
5. Запросите текущий статус платежа через метод GetState.
6. Вернется ответ со статусом REJECTED.

Сценарий «Возврат — успех»

1. Инициируйте возврат (не отмену) тестового платежа по QR-коду СБП, который успешно выполнен в тесте «Платеж-успех», через метод Cancel.
2. Запросите текущий статус платежа через метод GetState.
3. Вернется ответ со статусом REFUNDED.