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

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

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

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

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

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

Способ интеграции интернет-эквайринга с сайтом, созданным на основе CMS. Вы устанавливаете модуль — на странице сайта появляется кнопка оплаты. Покупатель нажимает на кнопку и переходит на платежную форму с разными способами оплаты: банковскими картами, по Tinkoff Pay, SberPay, Mir Pay, СБП, Долями, в рассрочку. Вы можете выбрать, какие способы оплаты оставить в форме: все или некоторые.

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

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

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

Способ интеграции интернет-эквайринга с самописным сайтом. Вы вставляете готовый код на страницу сайта — на этом месте появляется кнопка оплаты. Покупатель нажимает на кнопку и переходит на платежную форму с разными способами оплаты: банковскими картами, по Tinkoff Pay, SberPay, Mir Pay, СБП, Долями, в рассрочку. Вы можете выбрать, какие способы оплаты оставить в форме: все или некоторые.

Виджет подходит в двух случаях:

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

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

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

Мобильный SDK

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

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

SDK подходит, если принимаете оплату в приложении на Android начиная с версии 7.0 или iOS начиная с версии 12.3. С инструкцией по подключению SDK в ЛК можно ознакомиться по ссылкам ниже:

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

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

API

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

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

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

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

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

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

Некоторые webview не умеют обрабатывать DeepLink ссылки. Из-за этого способы оплаты, которые осуществляют переход в мобильное приложение во время платежа (СБП, Mir pay, Tinkoff pay), могут работать некорректно.

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

По результатам доработок необходимо дополнительно протестировать корректную работу всех способов оплат. В случае обнаружения проблем, требуется связаться с разработчиками webview модуля для их устранения, либо рекомендуется отключить неработающие способы оплаты. Ссылки с примерами решений:

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

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

Платформа IOS: Чтобы deeplink работал в web - есть 2 варианта решения:

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, Tinkoff pay). Это связано с тем, что Iframe является изолированным контейнером, из-за этого переходы на сторонние ссылки не могут быть обработаны внутри iframe.

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

После реализации доработок необходимо протестировать корректную работу всех способов оплат. В случае проблем и вопросов вы можете обратиться в нашу поддержку acq_help@tinkoff.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, а именно:

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

2. При любых способах интеграции с MAPI (в том числе и с помощью нашего платежного виджета) необходимо сверять параметры созданных заказов. В случае выявления расхождений между суммой операции, инициированной клиентом, и суммой совершенной операции, не осуществляйте доставку товара клиенту и незамедлительно уведомите Тинькофф банк об этом. Для сверки параметров есть несколько способов:
   2.1. Получение нотификаций:

   • По e-mail: на указанную почту придет письмо при переходе платежа в статус «CONFIRMED»;

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

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

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

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

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

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

Если ваш ресурс соответствует требованиям PCI DSS, то вы можете собирать и хранить карточные данные клиентов. В таком случае, MerchantAPI получает зашифрованные карточные данные от Мерчанта. Подробную информацию о подключении такого способа смотрите в разделе PCI DSS.

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

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

Подробное описание сценариев проведения операций, значений 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/

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

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

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

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

Инициализация платежа

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

При создании платежа (вызов метода /Init), в объекте DATA в атрибуте OperationInitiatorType необходимо передавать признак инициатора операции. См. метод Init.

В ответ 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, то MAPI в ответе FinishAuthorize вернет один из трех конечных статусов платежа:

• CONFIRMED (при одностадийном платеже);

• AUTHORIZED (при двухстадийном платеже);

• REJECTED (при отказе в проведении платежа).

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

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

В заголовке запроса требуется передать параметр 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 необходимо передавать признак инициатора операции. См. метод Init.

Метод Authorize

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

Метод FinishAuthorize

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

Осуществление платежа на платежной форме Тинькофф Кассы

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

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

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

Переадресация клиента:

• в случае успешного перевода на Success URL;
• в случае неуспешного перевода на Fail URL.

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

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

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

Двухстадийный платеж — платеж, состоящий из двух этапов. На первом этапе проверяется наличие средств у клиента и осуществляется их блокировка (холдирование средств). На втором этапе Мерчант должен либо подтвердить списание средств, либо отменить холдирование средств.

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

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

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

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

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

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

Когда Мерчант захочет списать деньги, он должен вызвать метод Confirm и передать в запросе PaymentId. После успешного списания платеж перейдет в статус CONFIRMED. Если Мерчант хочет отменить заказ (например, данный товар закончился), он должен вызвать метод Cancel.

Рекуррентные платежи

Мерчант может сохранять платежные данные клиента и использовать их для повторных списаний. Такие платежи называются рекуррентными. В этом случае клиент должен совершить хотя бы один платеж, который был настроен как рекуррентный. Для этого Мерчант должен передать параметр Recurrent в методе Init.

После успешной оплаты MAPI отправит Мерчанту уведомление об изменении статуса платежа на AUTHORIZED или CONFIRMED и передаст параметр RebillId. Следующие платежи этого клиента будут рекуррентными, если Мерчант вызовет метод Init, а затем без переадресации на PaymentURL вызовет метод Charge и передаст параметр RebillId.

Метод Charge работает как по одностадийной, так и по двухстадийной схеме оплаты. Чтобы перейти на двухстадийную схему, нужно переключить терминал в Личном кабинете, а также написать обращение на acq_help@tinkoff.ru с просьбой переключить схему рекуррентов.

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

Успешный платеж - платеж, который находится в статусе AUTHORIZED или CONFIRMED. Если Мерчант отменяет платеж в статусе AUTHORIZED, то происходит разморозка заблокированной суммы на карте клиента. Если платеж в статусе CONFIRMED, то деньги списываются со счета Мерчанта и возвращаются на карту клиента.

Возврат может быть частичный или полный. Частичный возврат - отмена не на всю сумму платежа. Полный возврат - отмена на полную сумму платежа.

Чтобы отменить платеж, Мерчант должен вызвать метод Cancel и передать в запросе идентификатор платежа PaymentId. По умолчанию, MAPI сделает полный возврат. Если требуется частичная отмена, то во входящем запросе Мерчант должен передать сумму, которая вернется клиенту, в параметре Amount.

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

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

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

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

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

На схеме ниже - полный жизненный цикл платежа

В этом разделе перечислены методы для взаимодействия с СБП.

Внимание! Тестирование оплаты через Систему быстрых платежей возможно на prod окружении и только на demo терминале.

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

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

На схемах ниже изображен полный жизненный цикл платежа

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

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

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

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

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

Процесс выглядит следующим образом:

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

• Сценарий “Платеж-успех”

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. Инициировать возврат (не отмену) методом Cancel тестового платежа по QR-коду СБП, выполненного успешно в тесте “Платеж-успех”
2. Запросить текущий статус платежа вызывая метод GetState.
3. Получить ответ со статусом REFUNDED.

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

Заполните заявку и откройте расчетный счет в Тинькофф.

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

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

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

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

Требования к подключению СБП

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

Подключение СБП в Личном Кабинете

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

Нажмите "Настроить“ на плашке Система быстрых платежей. Далее выбираете тот способ интеграции, который планируете использовать

Платежная форма тинькофф

Если планируете использовать её, то выбираете данную вкладку и нажимаете "Включить".

После подключения вкладка будет выглядить следующим образом

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

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

После подключения вкладка будет выглядить следующим образом

Приложение

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

После включения вкладка будет выглядить следующим образом

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

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

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

Платежная форма Тинькофф

После подключения СБП в Личном кабинете, QR код автоматически отобразится на платежной форме, ничего дополнительно интегрировать не нужно. Описание, как интегрировать Платежную форму на сайт. Платёжные формы Тинькофф: Мобильная

Десктопная

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

API

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

SDK

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

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

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

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

Интерфейс "Тинькофф SDK":

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

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

Получение стикера

Для получения стикера с QR кодом небходимо:

1. Создать магазин с выставлением счета, если у вас уже есть магазин, то далее п.2
2. Зайдите в настройки СБП в разделе "Способы оплаты"
3. Нажать на кнопку "скачать" в разделе Статический QR
4. Полученный QR код необходимо распечатать и разместить в кассовой зоне вашего магазина. Стикер “Тинькофф QR”:

После сканирования покупателем Стикера с QR кодом ему необходимо будет ввести сумму и подтвердить оплату.

Внимание! Фискализация по операциям с помощью Стикера с QR-кодом не происходит через онлайн кассы, даже если онлайн кассы подключенны в личном кабинете.

Нотификации об оплате

После оплаты вам придет нотификация в зависимости от настроек, на email или по http на ваш сервер.

Магазин - Выставление счетов
Настройка нотификаций происходит через acq_help@tinkoff.ru

Магазин - Интернет магазин
Если у вас уже есть интернет-магазин, то нотификации вы можете самостоятельно настроить в разделе Терминал

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

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

1. Чтобы сформировать прямую ссылку на переход в приложение банка, необходимо заменить https из функциональной ссылки на значение параметра schema из списка банков.
2. Список банков лежит по ссылке - https://qr.nspk.ru/proxyapp/c2bmembers.json

Например: Функциональная ссылка https://qr.nspk.ru/AS10004UVOQ9J4I489A8SG8NIA6P3F8B Заменить https на соответствующую schema банка Тинькофф - bank100000000004://qr.nspk.ru/AS10004UVOQ9J4I489A8SG8NIA6P3F8B Для каждого из банков сделать прямую ссылку по логике указанной в п.1. На Вашей платёжной форме необходимо отобразить список банков из п. 2

СБП можно интегрировать с помощью виджета, ниже будет описан порядок такой интеграции.

Установка платежного виджета на сайт

Вставьте следующий код на ваш сайт в место, где должна располагаться кнопка "Оплатить СБП" (подробное описание скрипта в п.1.2).

<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" указывается в рублях, копейки через точку

Настройка платежного виджета

Вставьте идентификатор магазина в код платежного виджета в значение параметра terminalkey. Идентификатор магазина выдаётся банком, его можно получить в личном кабинете (раздел «Магазины», вкладка "Терминалы"):

Для корректного отображения, добавьте в тег <head> </head> у себя на странице:

<meta name="viewport" content="width=device-width, initial-scale=1">

Если необходимо изменить состав полей платежного виджета, укажите у полей, которые хотите скрыть, 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 или на e-mail (https://www.tinkoff.ru/kassa/develop/api/notifications/).

Подключение СБП в Личном Кабинете

1. Перейдите в свой личныӗ кабинет и откройте страницу интернетмагазина, для которого вы хотите подключить оплату через СБП на сайте. Перейдите на вкладку “Способы оплаты”. Для подключения СБП надо провести первый платеж любым доступным способом
2. Нажмите на плашку СБП для подключения оплаты через СБП на сайте.
3. В случае успешного подключения СБП для интернет-магазина плашка должна стать активной.

Для подключения оплаты СБП для одного и более товаров потребуется передавать в метод initPayments объект настроек, в котором определено поле paymentItems.

Значением поля 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

Добавьте в код поле ввода 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',
              },
            ],
          });
        },
      });