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

Download OpenAPI specification:Download

Введение

Подключение интернет-эквайринга от Тинькофф Кассы

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

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

Способы интеграции интернет-эквайринга от Тинькофф Кассы

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

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

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

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

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

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

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

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

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

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

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

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

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

Мобильный SDK

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

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

SDK подходит, если принимаете оплату в приложении на Android начиная с версии 7.0 или iOS начиная с версии 12.3.

Инструкция для 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)

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

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

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

После реализации доработок необходимо протестировать корректную работу всех способов оплат. В случае проблем и вопросов вы можете обратиться в нашу поддержку acq_help@tinkoff.ru

В десктопной версии iframe кнопочные способы оплаты будут работать без специальных доработок.

Инструкция по доработкам для mobile iframe
Iframe является изолированным контейнером, из-за этого переходы на сторонние ссылки не могут быть обработаны внутри iframe (переход будет внутри iframe). Чтобы произвести переход в стороннее приложение требуется скрипт "снаружи" iframe, который получит сообщение о переходе от iframe и вызовет его на основной странице.

В случае если у вас подключены способы оплаты, использующие deeplink, а именно: Tinkoff pay, СБП или Mir pay, то в процессе оплаты может возникать ошибка.

Информация

Скрипт общается с фреймом по средствам window.postMessage().

Добавление скрипта решает проблему передачи ссылки на ресурс платежного сервиса, для способов оплаты использующих DeepLink. Данная проблема может возникнуть при попытке передачи ссылки в браузер Клиента, из контейнера Платежной формы расположенного в теге <iframe>.

Установка

Не рекомендуется копировать скрипт полностью в свою сборку. Интерфейс общения с Платежной Формой может изменится, поэтому просьба всегда загружать скрипт из предоставленного URL

Простая интеграция (Если используется уже созданный 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 принимает 2 аргумента:

  1. HTMLIFrameElement - iframe DOM элемент
  2. 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 только в случае их переопределения в config.

Как работает скрипт

Общение между формой и родителем, происходит через window.postMessage().

  1. После успешной загрузки, платежная форма внутри iframe отправляет сообщение loaded родителю.
  2. После получения loaded из ПФ, скрипт отправляет сообщение ready на Платежную форму, таким образом происходит рукопожатие и платежная форма определяет что может отобразить кнопочные методы оплаты
  3. Действиями Клиента на Платежной форме вызывается способ оплаты возвращающий DeepLink на ресурс платежного сервиса.
  4. Платежная форма, передает DeepLink в целевое окно клиента, с помощью события deepLink
  5. Целевое окно выполняет редирект Клиента, по ссылке полученной в DeepLink, с помощью вызова deepLinkRedirectCallback
  6. Аналогично передаются и другие сообщения

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

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

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

Возможности кастомизации Доп. описание
Управление способами оплаты
  • менять порядок способов оплаты (кроме Tinkoff pay)
  •  сворачивать/разворачивать блоки оплаты (оплата картой и рассрочка) 
  • менять количество отображаемых способов с помощью кнопки "еще" (минимум - один способ, максимум - все доступные на ПФ)
  • Брендирование UI платежной формы
  • добавлять лого своей компании на ПФ (логотип отобразится рядом с суммой заказа) 
  • управлять цветами кнопок (кнопка "Оплатить" и другие кнопки со страниц статусов и модальных окон)
  • Управление блоком детализации (информация о заказе и магазине)
  • делать блок свернутым и развернутым по-умолчанию
  •  скрывать  блок с детализацией на ПФ
  • менять порядок строк в детализации
  • Управление светлой и темной темой
  • показывать темную или светлую тему по-умолчанию
  • отключать темной/светлой темы
  • Инструкции по безопасности при интеграции

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

    Тип операции и инициатор Описание Сценарий карточной операции 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 (CIT COF R) Инициированные торговым предприятием повторяющиеся платежи без графика (ранее была проведена операция с сохранением реквизитов CIT CC). Применяются для оплаты коммунальных услуг, платежей за услуги связи, кабельное/спутниковое телевидение и т.п. Сумма может быть определена заранее или становится известна непосредственно перед оплатой Рекуррентный платеж, инициированный торговым предприятием R not null N Запрещено Разрешено
    Merchant Credential-on-File, Installment (CIT COF I) Инициированные торговым предприятием повторяющиеся платежи по графику (ранее была проведена операция с сохранением реквизитов CIT CC). Применяется для платежей в рассрочку по товарному кредиту, для оплаты страховки в рассрочку, для погашения кредита в соответствии с графиком платежей. График платежей может быть изменен по соглашению сторон, т.е. суммы и даты платежей должны быть известны плательщику (держателю карты) до момента проведения операции. Рекуррентный платеж, инициированный торговым предприятием I not null N Разрешено Запрещено

    Какими терминами пользуемся в документации?

    Термин Определение
    Клиент Физлицо, производящее перевод с использованием банковской карты на сайте Мерчанта
    Мерчант Бизнес, принимающий и осуществляющий переводы по банковским картам на своем сайте
    Тинькофф Касса Сервис, помогающий проводить выплату клиенту-физлицу
    Эмитент Банк, выпустивший карту клиента-физлица
    PCI DSS Международный стандарт безопасности, созданный для защиты данных банковских карт
    3-DSecure Протокол, который используется как дополнительный уровень безопасности для онлайн-кредитных и дебетовых карт. 3-D Secure добавляет ещё один шаг аутентификации для онлайн-платежей
    Терминал Точка приема платежей Мерчанта (в общем случае привязывается к сайту, на котором осуществляется прием платежей) Далее в этой документации описан протокол для терминала мерчанта
    ККМ Контрольно-кассовая машина
    Личный кабинет Мерчанта Веб-приложение, в котором Мерчант управляет интернет-эквайрингом - настраивает параметры терминалов, подтверждает или отменяет платежи, анализирует статистику

    Параметры терминала

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

    В таблице ниже перечислены основые параметры приёма платежей для терминала

    Название параметра Формат Описание
    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"
          }
        ]
      }
    }
    

    Чтобы зашифровать данные запроса Мерчант должен выполнить следующие шаги:

    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

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

    Сценарии оплаты по карте

    Правила работы

    Прием платежей осуществляется вызовом методов с передачей параметров методом 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-объект с параметрами:

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

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

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

    В ответ MAPI вернет один из возможных статусов:

    Статус Описание Доступные действия
    AUTH_FAIL Неуспешная авторизация Провести платеж заново
    REJECTED Платеж отклонен Провести платеж заново
    CONFIRMED Успешный одностадийный платеж -
    AUTHORIZED Успешный двухстадийный платеж Подтвердить платеж
    3DS_CHECKING Требуется подтверждение платежа по 3D-Secure
    • Отменить платеж (действие доступно для клиента)
    • Пройти подтверждение (действие доступно для клиента)

    Без 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, то в запросе передаются параметры:

    Название параметра Описание
    MD Информация для идентификации платежной сессии на стороне торговой точки. Придет в ответе метода FinishAuthorize
    PaReq Запрос на аутентификацию плательщика, который содержит разные детали транзакции. Придет в ответе метода FinishAuthorize
    TermURL Адрес перенаправления после аутентификации 3DS. Должен содержать ссылку на обработчик на стороне Мерчанта, принимающий результаты прохождения 3-D Secure
    3DS 2.0

    Если версия 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.Допустимые значения:
  • 01 = 250 x 400
  • 02 = 390 x 400
  • 03 = 500 x 600
  • 04 = 600 x 400
  • 05 = Full screen
  • messageType string Передается фиксированное значение «CReq»
    messageVersion string Версия 3DS, полученная из ответа метода Check3dsVersion

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

    Название параметра Тип данных Описание
    creq string JWE object с параметрами threeDSServerTransID, acsTransID, messageType, messageVersion, sdkTransID, sdkCounterStoA закодированный в формат PS256

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

    Название параметра Тип данных Описание
    threeDSServerTransID string Идентификатор транзакции из ответа метода FinishAuthorize
    acsTransID string Идентификатор транзакции, присвоенный ACS, полученный в ответе на FinishAuthorize
    messageType string Передается фиксированное значение «CReq»
    messageVersion string Версия 3DS, полученная из ответа метода Check3dsVersion
    sdkTransID string Уникальный идентификатор транзакции, назначенный 3DS SDK для идентификации одной транзакции, полученный в ответе на FinishAuthorize
    sdkCounterStoA string Внутренний счетчик 3DS SDK внутри ACS. Поддерживаемые значения:
    000-255

    Подтверждение прохождения 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. Статус платежа выставляется в FORMSHOWED.

    Метод 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.

    Статусная модель платежа

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

    Статус Правило перехода
    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 Полный возврат по подтвержденному платежу завершился успешно
    СANCELED Мерчант отменил платеж
    DEADLINE_EXPIRED 1. Клиент не завершил платеж в срок жизни ссылки на платежную форму PaymentURL. Этот срок Мерчант настраивает в Личном кабинете, либо передает в параметре RedirectDueDate при вызове метода Init
    2. Платеж не прошел проверку 3D-Secure в срок
    REJECTED Банк отклонил платеж
    AUTH_FAIL Платеж завершился ошибкой или не прошел проверку 3D-Secure

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

    Стандартный платёж

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

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

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string <= 20 characters

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

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

    Идентификатор заказа в системе Мерчанта

    Token
    required
    string

    Подпись запроса.

    Description
    string <= 250 characters

    Описание заказа.

    • Поле необходимо обязательно заполнять для осуществления привязки и одновременной оплаты по CБП. При оплате через СБП данная информация будет отображена в приложении мобильного банка клиента. Максимально допустимое количество знаков для передачи назначения платежа в СБП - 140 символов.
    CustomerKey
    string <= 36 characters

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

    • Обязателен, если передан атрибут Recurrent.
    • Если был передан в запросе, в нотификации будет указан CustomerKey и его CardId. См. метод GetCardList.
    • Необходим для сохранения карт на платежной форме (платежи в один клик).
    • Не является обязательным при реккурентных платежах через СБП.
    Recurrent
    string <= 1 characters

    Признак родительского рекуррентного платежа.

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

    Значение зависимо от атрибутов:

    PayType
    string
    Enum: "O" "T"

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

    • "O" - одностадийная оплата,
    • "T" - двухстадийная оплата Если параметр передан - используется его значение. Если нет - значение в настройках терминала.
    Language
    string <= 2 characters

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

    • ru — русский
    • en — английский. Если не передан, форма откроется на русском языке
    NotificationURL
    string <uri>

    URL на веб-сайте Мерчанта, куда будет отправлен POST запрос о статусе выполнения вызываемых методов (настраивается в Личном кабинете):

    • Если параметр передан – используется его значение.
    • Если нет – значение в настройках терминала.
    SuccessURL
    string <uri>

    URL на веб-сайте Мерчанта, куда будет переведен клиент в случае успешной оплаты (настраивается в Личном кабинете):

    • Если параметр передан – используется его значение.
    • Если нет – значение в настройках терминала.
    FailURL
    string <uri>

    URL на веб-сайте Мерчанта, куда будет переведен клиент в случае неуспешной оплаты (настраивается в Личном кабинете):

    • Если параметр передан – используется его значение.
    • Если нет – значение в настройках терминала.
    RedirectDueDate
    any <date-time>

    Cрок жизни ссылки или динамического QR-кода СБП (если выбран данный способ оплаты). Если текущая дата превышает дату, переданную в данном параметре, ссылка для оплаты или возможность платежа по QR-коду становятся недоступными и платёж выполнить нельзя.

    • Максимальное значение: 90 дней от текущей даты.
    • Минимальное значение: 1 минута от текущей даты.
    • Формат даты: YYYY-MM-DDTHH24:MI:SS+GMT
    • Пример даты: 2016-08-31T12:28:00+03:00
      Если не передан, принимает значение 24 часа для платежа и 30 дней для счета

    При выставлении счета через Личный кабинет:
    В случае, если параметр RedirectDueDate не был передан, проверяется настроечный параметр платежного терминала REDIRECT_TIMEOUT, который может содержать значение срока жизни ссылки в часах. Если его значение больше нуля, то оно будет установлено в качестве срока жизни ссылки или динамического QR-кода. Иначе, устанавливается значение «по умолчанию» - 1440 мин.(1 сутки)

    Common (object) or TinkoffPay (object) or YandexPay (object) or LongPay (object)

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

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

    • Ключ - 20 знаков
    • Значение - 100 знаков.

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

    1. Если у терминала включена опция привязки клиента после успешной оплаты и передается параметр CustomerKey, то в передаваемых параметрах DATA могут присутствовать параметры метода AddCustomer. Если они присутствуют, то автоматически привязываются к клиенту. Например, если указать:

      "DATA":{"Phone":"+71234567890", "Email":"a@test.com"}
      

      к клиенту автоматически будут привязаны данные Email и телефон, и они будут возвращаться при вызове метода GetCustomer.

      Для МСС 4814 обязательно передать значение в параметре Phone. Требования по заполнению:

      • минимум 7 символов
      • максимум 20 символов
      • разрешены только цифры, исключение - первый символ может быть «+»

      Для МСС 6051 и 6050 обязательно передать параметр account (номер электронного кошелька, не должен превышать 30 символов). Пример:

      "DATA": {"account":"123456789"}
      
    2. Если используется функционал сохранения карт на платежной форме, то при помощи опционального параметра DefaultCard можно задать какая карта будет выбираться по умолчанию. Возможные варианты:

    • Оставить платежную форму пустой. Пример:
      "DATA":{"DefaultCard":"none"}
      
    • Заполнить данными передаваемой карты. В этом случае передается CardId. Пример:
       "DATA":{"DefaultCard":"894952"}
      
    • Заполнить данными последней сохраненной карты. Применяется, если параметр DefaultCard не передан, передан с некорректным значением или в значении null. По умолчанию возможность сохранение карт на платежной форме может быть отключена. Для активации обратитесь в службу технической поддержки.
    1. При реализации подключения оплаты через Yandex Pay Web или Tinkoff Pay Web, необходимо обязательно передавать следующие параметры в объекте Data. Пример:

      "DATA": {
       "TinkoffPayWeb": "true",
       "Device": "Desktop",
       "DeviceOs": "iOS",
       "DeviceWebView": "true",
       "DeviceBrowser": "Safari"
      }
      

      где следует передать параметры устройства, с которого будет осуществлен переход.

    2. Параметр notificationEnableSource позволяет отправлять нотификации только если Source (также присутствует в параметрах сессии) платежа входит в перечень указанных в параметре. Возможные варианты: TinkoffPay, sbpqr, YandexPay. Пример:

      notificationEnableSource=TinkoffPay
      
    3. Для осуществления привязки и одновременной оплаты по CБП необходимо передавать параметр "QR" = "true"

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

      • Значением атрибута Reccurent в методе /Init
      • Значением атрибута RebillId в методе /Charge
      • Типом терминала, используемом для проведения операций (ECOM/AFT)

    Подробную таблицу см. в разделе Передача признака инициатора операции

    В случае передачи значений атрибутов не соответствующих таблице - MAPI вернет ошибку 1126 (Несопоставимые значения rebillId или Recurrent с переданным значением OperationInitiatorType)

    Receipt_FFD_105 (object) or Receipt_FFD_12 (object)

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

    Array of objects (Shops)

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

    Descriptor
    string

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

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 140000,
    • "OrderId": "21090",
    • "Description": "Подарочная карта на 1000 рублей",
    • "Token": "68711168852240a2f34b6a8b19d2cfbd296c7d2a6dff8b23eda6278985959346",
    • "DATA": {
      },
    • "Receipt": {
      }
    }

    Response samples

    Content type
    application/json
    {}

    Проверка версии 3DS

    Для Мерчантов с PCI DSS
    Проверяет поддерживаемую версию 3DS протокола по карточным данным из входящих параметров.

    При определении второй версии, возможно в ответе получение данных для прохождения дополнительного метода 3DS Method, который позволяет эмитенту собрать данные браузера клиента – это может быть полезно при принятии решения в пользу Frictionless Flow (аутентификация клиента без редиректа на страницу ACS)

    Request Body schema: application/json
    PaymentId
    required
    number <= 20 characters

    Идентификатор платежа в системе Тинькофф Кассы

    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CardData
    required
    any

    Зашифрованные данные карты в формате:

    PAN=4300000000000777;ExpDate=0519;CardHolder=IVAN PETROV;CVV=111
    

    type: string

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "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"
    }

    Response samples

    Content type
    application/json
    {
    • "Version": "2.1.0",
    • "TdsServerTransID": "17d3791b-5cfa-4318-bc23-3d949e8c4b7e",
    • "PaymentSystem": "mir",
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "None",
    • "Details": "None"
    }

    Подтверждение платежа

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

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string

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

    PaymentId
    required
    number <= 20 characters

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса

    IP
    string

    IP-адрес клиента.

    Обязательный параметр для 3DS второй версии. DS платежной системы требует передавать данный адрес в полном формате, без какихлибо сокращений (8 групп по 4 символа).

    Данный формат регламентируется на уровне спецификации EMVCo.

    Пример правильного адреса: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
    Пример неправильного адреса: 2a00:1fa1:c7da:9285:0:51:838b:1001

    SendEmail
    boolean
    • true – отправлять клиенту информацию на почту об оплате
    • false – не отправлять
    Source
    string
    Enum: "cards" "beeline" "mts" "tele2" "megafon" "einvoicing" "webmoney" "YandexPay"

    Источник платежа. Значение параметра зависит от параметра Route.

    • ACQ - cards (так же поддерживается написание Cards), YandexPay
    • MC - beeline / mts / tele2 / megafon
    • EINV - einvoicing
    • WM - webmoney
    3DSv2 (object) or object

    JSON объект, содержащий дополнительные параметры в виде ключ:значение. Данные параметры будут переданы на страницу оплаты (в случае ее кастомизации). Максимальная длина для каждого передаваемого параметра:

    • Ключ - 20 знаков;
    • Значение - 100 знаков. Максимальное количество пар ключ:значение не может превышать 20.
    InfoEmail
    string <email>

    Email для отправки информации об оплате. Обязателен при передаче SendEmail

    EncryptedPaymentData
    string

    Данные карты. Используется и является обязательным только для ApplePay или GooglePay

    CardData
    required
    string

    Объект CardData собирается в виде списка ключ=значение c разделителем ;. Объект зашифровывается открытым ключом (X509 RSA 2048), получившееся бинарное значение кодируется в Base64. Открытый ключ генерируется Тинькофф Кассой и выдается при регистрации терминала. Все поля обязательны.

    Наименование Тип данных Обязательность Описание
    PAN Number ДА Номер карты
    ExpDate Number Да Месяц и год срока действия карты в формате MMYY
    CardHolder String Нет Имя и фамилия держателя карты (как на карте)
    CVV String Нет Код защиты (с обратной стороны карты). Для платежей по Apple Pay (с расшифровкой токена на своей стороне) не является обязательным.
    ECI String Нет Electronic Commerce Indicator. Индикатор, показывающий степень защиты, применяемую при предоставлении клиентом своих данных ТСП.
    CAVV String Нет Cardholder Authentication Verification Value или Accountholder Authentication Value

    Пример значения элемента формы CardData:

    PAN=4300000000000777;ExpDate=0519;CardHolder=IVAN PETROV;CVV=111
    

    Для YandexPay (расшифровка токена происходит на стороне Мерчанта) надо:

    1. Передавать Route=ACQ и Source=YandexPay;
    2. Передавать в DATA.transactionId значение PaymentToken.messageId;
    3. Передавать в DATA.YandexPayWeb значение true;
    4. Передавать параметр CardData: Размапить параметры из расшифрованного токена event.token
      • paymentMethodDetails.pan в pan;
      • paymentMethodDetails,expirationMonth + paymentMethodDetails.expirationYear в ExpDate;
      • paymentMethodDetails.cryptogram в CAVV (если есть);
      • paymentMethodDetails.eci в ECI (если есть)

    Для MirPay (если интеграция с НСПК для получения платежного токена) надо:

    1. Передавать Route=ACQ и Source= MirPay;
    2. Передавать в DATA.transId значение transId;
    3. Передавать в DATA.tavv значение cav;
    4. Передавать параметр CardData:
      • Pan заполнять tan;
      • ExpDate заполнять tem + tey
        Для случая, когда Мерчант интегрируется только с Банком для проведения платежа по MirPay данный метод не вызывается. Эквайер самостоятельно получает платежный токен и инициирует авторизацию, вместо Мерчанта.

    В случае получения CAVV в CardData оплата будет проводиться как оплата токеном, иначе прохождение 3DS будет регулироваться стандартными настройками треминала/платежа.

    Не используется и не является обязательным, если передается EncryptedPaymentData

    Amount
    number <= 10 characters

    Сумма в копейках

    deviceChannel
    string

    Канал устройства. Поддерживается следующий канал устройства:

    • 01 = Application (APP)
    • 02 = Browser (BRW) (используется по умолчанию)
    Route
    string
    Enum: "ACQ" "MC" "EINV" "WM"

    Способ платежа. Является обязательным для Apple Pay или Google Pay.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 700001702044,
    • "Token": "f5a3be479324a6d3a4d9efa0d02880b77d04a91758deddcbd9e752a6df97cab5",
    • "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334",
    • "SendEmail": true,
    • "Source": "cards",
    • "DATA": {
      },
    • "InfoEmail": "qwerty@test.com",
    • "EncryptedPaymentData": "string",
    • "CardData": "eyJzaWduYXR1cmUiOiJNRVVDSVFEdjNJS1A5WG9nWml4RytUUm9zZWFDK0RGd3RKd2FtMHVEcm91RUVGZVB6Z0lnYXBFbHhxQ3AwQWtZcVVmTFVMaVNhUjBKWkVQNmg 4THFqYks5YkJKQnM5d1x1MDAzZCIsInByb3RvY29sVmVyc2lvbiI6IkVDdjEiLCJzaWduZWRNZXNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwiQW11dm5OYUIralBsa3VKTitrMUZLSDZFcm1VK2lTY052 L05rR3FFaXIxOHZmSWxkVFJ5L2U4cW5zMXkyanFtcm1acU1JSWNYMUhyTHBxRURpaXkvS3B6SUhNZFllcXRkSVVNOU1tRjNpejU2d2NTZUVVaXU2ODI3QThGcitaYm8xRWtWRjY1TUxRYVY3NlBOUFRndH UvQ1BodW5HUk0rN25KdVhDczVtbkVvOHFma0RNVk8xWktGWDQ4TnVEL2FKcDJQdVVIY2puSnBTZ0pTSDB4U21YSnAzU1MreXFDNm54N254WUEwN2h4YjYvSnp2R2s3ZExDU2hWWGU1Z2haUjNDaFQyV W8rRnpXTWJRRGZtSjBLQW9kc2VlR0xaaitqMzVqOUlKMkhJRFhIUUZZMWNuTW9YVUVoTjgvdEkvRkpqRnJiYVdFRkIzRDZwOFUzT2tkUmVaNHAyYi8yYURNZXVxR1ozSUtjc3R0R2lKMFhQQVhhZXYyQU8 o1M3RRQXVqQXRYdFlaekNTVjVBVXdXZS85T1VcXHUwMDNkXCJ9In0=",
    • "Amount": 10000,
    • "deviceChannel": "02",
    • "Route": "ACQ"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 100000,
    • "OrderId": "21050",
    • "Success": true,
    • "Status": "NEW",
    • "PaymentId": "13660",
    • "ErrorCode": "0",
    • "Message": "Неверные параметры",
    • "Details": "0",
    • "RebillId": "21813157",
    • "CardId": "string"
    }

    Получение статуса платежа

    Метод возвращает статус платежа

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string <= 20 characters

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

    PaymentId
    required
    number <= 20 characters

    Идентификатор платежа в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса

    IP
    string

    IP-адрес клиента

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 13660,
    • "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96",
    • "IP": "192.168.0.52"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 100000,
    • "OrderId": "21050",
    • "Success": true,
    • "Status": "NEW",
    • "PaymentId": 13660,
    • "ErrorCode": "0",
    • "Message": "OK",
    • "Details": "0",
    • "Params": [
      ]
    }

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

    Метод возвращает статус заказа

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала выдается Мерчанту Тинькофф Кассой

    OrderId
    required
    string

    Номер заказа в системе Мерчанта.
    Не является уникальным идентификатором.

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "OrderId": 21057,
    • "Token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "OrderId": "21057",
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "OK",
    • "Details": "None",
    • "Payments": {
      }
    }

    Получение справки по операции

    Справку по конкретной операции можно получить на:
    1. URL-сервиса, развернутого на своей стороне
    2. Электронную почту

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CallbackUrl
    required
    string

    URL сервиса получения справок

    PaymentIdList
    required
    Array of numbers

    Json-массив, содержащий в себе перечень paymentID (уникальных идентификаторов в системе Тинькофф Кассы) c типом Number

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CallbackUrl": "https://www.tinkoff.ru",
    • "PaymentIdList": [
      ],
    • "Token": "f2fdd7fec8225872590e1558b7ea258c75df8f300d808006c41ab540dd7514d9"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "Success": true,
    • "ErrorCode": 0,
    • "Message": "OK",
    • "PaymentIdList": [
      ]
    }

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

    Подтверждение платежа

    Метод для списания заблокированных денежных средств. Используется при двухстадийном проведении платежа. Применим только к платежам в статусе AUTHORIZED. Статус транзакции перед разблокировкой выставляется в CONFIRMING. Сумма списания может быть меньше или равна сумме авторизации

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    number <= 20 characters

    Идентификатор платежа в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса (хэш SHA-256)

    IP
    string

    IP-адрес клиента

    Amount
    number

    Сумма в копейках (если не передан, используется Amount, переданный в методе Init)

    Receipt_FFD_12 (object) or Receipt_FFD_105 (object)

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

    Array of objects (Shops)

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

    Route
    string
    Enum: "TCB" "BNPL"

    Способ платежа.

    • При проведении платежа в «Рассрочку» необходимо передавать значение TCB
    • При проведении платежа «Долями» необходимо передавать значение BNPL
    Source
    string
    Enum: "installment" "BNPL"

    Источник платежа.

    • При проведении платежа в «Рассрочку» необходимо передавать значение installment
    • При проведении платежа «Долями» необходимо передавать значение BNPL

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 2304882,
    • "Token": "c0ad1dfc4e94ed44715c5ed0e84f8ec439695b9ac219a7a19555a075a3c3ed24",
    • "IP": "192.168.255.255",
    • "Amount": 19200,
    • "Receipt": {
      },
    • "Shops": [
      ],
    • "Route": "BNPL",
    • "Source": "BNPL"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "OrderId": "21057",
    • "Success": true,
    • "Status": "CONFIRMED",
    • "PaymentId": "2304882",
    • "ErrorCode": "0",
    • "Message": "OK",
    • "Details": "None",
    • "Params": [
      ]
    }

    Прохождение 3DS

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

    Для Мерчантов с PCI DSS
    Осуществляет проверку результатов прохождения 3-D Secure и при успешном результате прохождения 3-D Secure подтверждает инициированный платеж. При использовании одностадийной оплаты осуществляет списание денежных средств с карты клиента
    При двухстадийной оплате осуществляет блокировку указанной суммы на карте клиента

    Формат запроса: x-www-form-urlencoded

    После получения на TermUrl мерчанта ответа ACS с результатами прохождения 3-D Secure необходимо сформировать запрос к методу Submit3DSAuthorization

    Request Body schema: application/x-www-form-urlencoded
    MD
    required
    string

    Уникальный идентификатор транзакции в системе Тинькофф Кассы (возвращается в ответе от ACS)

    PaRes
    required
    string

    Шифрованная строка, содержащая результаты 3-D Secure аутентификации (возвращается в ответе от ACS)

    PaymentId
    string

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    TerminalKey
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    Token
    string

    Подпись запроса

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "OrderId": "21050",
    • "Success": true,
    • "Status": "CONFIRMED",
    • "PaymentId": "10063",
    • "ErrorCode": "0",
    • "Message": "string",
    • "Details": "string"
    }

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

    Для Мерчантов с PCI DSS
    Осуществляет проверку результатов прохождения 3-D Secure v2 и при успешном результате прохождения 3-D Secure v2 подтверждает инициированный платеж. При использовании одностадийной оплаты осуществляет списание денежных средств с карты клиента. При двухстадийной оплате осуществляет блокировку указанной суммы на карте клиента.

    Формат запроса: x-www-form-urlencoded

    После получения на TermUrl Мерчанта ответа ACS с результатами прохождения 3-D Secure необходимо сформировать запрос к методу Submit3DSAuthorizationV2

    Request Body schema: application/x-www-form-urlencoded
    PaymentId
    required
    string

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "OrderId": "21050",
    • "TerminalKey": "TinkoffBankTest",
    • "Status": "CONFIRMED",
    • "PaymentId": "10063",
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "string",
    • "Details": "string"
    }

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

    Автоплатёж

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

    Описание

    Осуществляет рекуррентный (повторный) платеж — безакцептное списание денежных средств со счета банковской карты клиента. Для возможности его использования клиент должен совершить хотя бы один платеж в пользу Мерчанта, который должен быть указан как рекуррентный (см. параметр Recurrent методе Init), фактически являющийся первичным. По завершении оплаты в нотификации на AUTHORIZED или CONFIRMED будет передан параметр RebillId. В дальнейшем для совершения рекуррентного платежа Мерчант должен вызвать метод Init, а затем без переадресации на PaymentURL вызвать метод Charge для оплаты по тем же самым реквизитам и передать параметр RebillId, полученный при совершении первичного платежа. Метод Charge работает по одностадийной и двухстадийной схеме оплаты. Чтобы перейти на двухстадийную схему нужно переключить терминал в личном кабинете, а также написать обращение на acq_help@tinkoff.ru с просьбой переключить схему рекуррентов.

    При проведении рекуррентного платежа учитывать взаимосвязь атрибута RebillId в методе /Charge с:

    • Значением атрибута OperationInitiatorType в методе /Init
    • Значением атрибута Reccurent в методе /Init
    • Типом терминала, используемом для проведения операций (ECOM/AFT)

    Наглядно допустимые сценарии взаимосвязи описаны в таблице:

    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)

    Одностадийная оплата

    1. Совершить родительский платеж путем вызова Init с указанием дополнительных параметров Recurrent=Y и CustomerKey.
    2. Переадресовать клиента на PaymentUrl (только для Мерчантов без PCI DSS).
    3. После оплаты заказа клиентом в нотификации на статус AUTHORIZED или CONFIRMED будет передан параметр RebillId, который необходимо сохранить.
    4. Спустя некоторое время для совершения рекуррентного платежа необходимо вызвать метод Init со стандартным набором параметров (параметры Recurrent и CustomerKey здесь не нужны).
    5. Получить в ответ на Init параметр PaymentId.
    6. Вызвать метод Charge с параметром RebillId, полученным в п.3, и параметром PaymentId, полученным в п.5. При успешном сценарии операция перейдет в статус CONFIRMED.

    Двухстадийная оплата

    1. Совершить родительский платеж путем вызова Init с указанием дополнительных параметров Recurrent=Y и CustomerKey.
    2. Переадресовать клиента на PaymentUrl (только для Мерчантов без PCI DSS).
    3. После оплаты заказа клиентом в нотификации на статус AUTHORIZED или CONFIRMED будет передан параметр RebillId, который необходимо сохранить.
    4. Спустя некоторое время для совершения рекуррентного платежа необходимо вызвать метод Init со стандартным набором параметров (параметр Recurrent и CustomerKey здесь не нужны).
    5. Получить в ответ на Init параметр PaymentId.
    6. Вызвать метод Charge с параметром RebillId, полученным в п.3, и параметром PaymentId, полученным в п.5. При успешном сценарии операция перейдет в статус AUTHORIZED. Денежные средства будут заблокированы на карте клиента.
    7. Вызвать метод Confirm для подтверждения платежа
    Request Body schema: application/json
    One of
    TerminalKey
    required
    string <= 20 characters

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

    PaymentId
    required
    number <= 20 characters

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    RebillId
    required
    string

    Идентификатор рекуррентного платежа. Значение зависимо от атрибутов:

    Token
    required
    string

    Подпись запроса

    IP
    string

    IP-адрес клиента

    SendEmail
    boolean
    • true – если клиент хочет получать уведомления на почту
    InfoEmail
    string <email>

    Адрес почты клиента

    • Обязателен при передаче SendEmail

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 700001702044,
    • "RebillId": "145919",
    • "Token": "f5a3be479324a6d3a4d9efa0d02880b77d04a91758deddcbd9e752a6df97cab5",
    • "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334",
    • "SendEmail": true,
    • "InfoEmail": "customer@test.com"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 100000,
    • "OrderId": "21050",
    • "Success": true,
    • "Status": "NEW",
    • "PaymentId": 13660,
    • "ErrorCode": "0",
    • "Message": "string",
    • "Details": "string"
    }

    Отмена платежа

    Отмена платежа

    Отменяет платежную сессию. В зависимости от статуса платежа переводит его в следующие состояния:

    • NEW - CANCELED
    • AUTHORIZED - PARTIAL_REVERSED – если отмена не на полную сумму
    • AUTHORIZED - REVERSED - если отмена на полную сумму
    • CONFIRMED - PARTIAL_REFUNDED – если отмена не на полную сумму
    • CONFIRMED - REFUNDED – если отмена на полную сумму

    Для платежей «в Рассрочку» отмена доступна только из статуса AUTHORIZED
    Для платежей «Долями» если операция в статусе CONFIRMED или PARTIAL_REFUNDED будет осуществлен частичный либо полный возврат
    Если платеж находился в статусе AUTHORIZED производится отмена холдирования средств на карте клиента. При переходе из статуса CONFIRMED – возврат денежных средств на карту клиента

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    number

    Идентификатор платежа в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса (хэш SHA-256)

    IP
    string

    IP-адрес клиента

    Amount
    number

    Сумма в копейках (если не передан, используется Amount, переданный в методе Init). В случае отмены статуса NEW поле Amount, даже если оно заполнено, игнорируется. Отмена производится на полную сумму

    Receipt_FFD_12 (object) or Receipt_FFD_105 (object)

    JSON-объект с данными чека. Обязателен, если подключена онлайн-касса.
    Данные переданные в данном запросе могут отличаться от переданных в Init, если отмена производится только по части товаров.
    В случае полной отмены структура чека не передается. В случае частичной отмены необходимо передавать те товары, которые нужно отменить.

    Array of objects (Shops)

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

    QrMemberId
    string

    Код банка в классификации СБП, в который необходимо выполнить возврат. См. параметр MemberId в методе QrMembersList.

    Route
    string
    Enum: "TCB" "BNPL"

    Способ платежа.

    • При проведении платежа в «Рассрочку» необходимо передавать значение TCB
    • При проведении платежа «Долями» необходимо передавать значение BNPL
    Source
    string
    Enum: "installment" "BNPL"

    Источник платежа.

    • При проведении платежа в «Рассрочку» необходимо передавать значение installment
    • При проведении платежа «Долями» необходимо передавать значение BNPL
    ExternalRequestId
    string <= 256 characters

    Идентификатор операции на стороне мерчанта

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

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 2304882,
    • "Token": "c0ad1dfc4e94ed44715c5ed0e84f8ec439695b9ac219a7a19555a075a3c3ed24",
    • "IP": "192.168.255.255",
    • "Amount": 19200,
    • "Receipt": {
      },
    • "Shops": [
      ],
    • "QrMemberId": "77892",
    • "Route": "BNPL",
    • "Source": "BNPL",
    • "ExternalRequestId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "OrderId": "21057",
    • "Success": true,
    • "Status": "REVERSED",
    • "OriginalAmount": 13000,
    • "NewAmount": 5000,
    • "PaymentId": "2304882",
    • "ErrorCode": "0",
    • "Message": "OK",
    • "Details": "None",
    • "ExternalRequestId": "756478567845678436"
    }

    Оплата через СБП

    Общая информация для оплат по QR

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

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

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

    Статусная модель платежа

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

    Статус Правило перехода
    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. Этот срок Мерчант настраивает в Личном кабинете, либо передает в параметре RedirectDueDate при вызове метода Init
    2. Платеж не прошел проверку 3D-Secure в срок
    ATTEMPTS_EXPIRED Клиент превысил количество попыток открытия формы
    REJECTED Банк отклонил платеж
    AUTH_FAIL Платеж завершился ошибкой или не прошел проверку 3D-Secure
    PREAUTHORIZING Проверка платежных данных Покупателя(актуально только для рекуррентных платежей)

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

    Привязка счёта

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

    Статус Правило перехода
    NEW MAPI получил запрос AddAccountQr или GetQr для сессии с рекуррентным платежом
    PROCESSING QR сформирован и отправлен мерчанту
    ACTIVE Привяза счета прошла успешно
    INACTIVE Банк отклонил привязку счета

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

    scheme

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

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

    scheme

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

    scheme;display:block;margin:auto|
    Если клиент привязывает счёт к терминалу мерчанта, у которого есть несколько терминалов, то клиент имеет возможность выполнять рекуррентные платежи на всех терминалах Мерчанта

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

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

    Тесты по QR

    • Сценарий “Платеж-успех”
    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-кодом для размещения на кассе

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

    Включение СБП

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

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

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

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

    sposobioplati;display:block;margin:auto|

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

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

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

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

    pfsbpmobile;display:block;margin:auto|

    Десктопная pfsbpdesktop;display:block;margin:auto|

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

    API

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

    SDK

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

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

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

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

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

    sbpsdk1;display:block;margin:auto|

    sbpsdk2;display:block;margin:auto|

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

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

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

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

    1. Создать магазин с выставлением счета, если у вас уже есть магазин, то далее п.2
    2. Нажать на кнопку скачать QR-код Страница “Способы Оплаты”:

    podklucheniesbp;display:block;margin:auto|

    1. Полученный QR код необходимо распечатать и разместить в кассовой зоне вашего магазина. Стикер “Тинькофф QR”:

    sbpqr;display:block;margin:auto|

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

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

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

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

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

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

    nastroikiterminala;display:block;margin:auto|

    Настроить выбор банка при интеграции по 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

    Наименование Обязательный Тип данных Описание
    container Да HTMLFormElement Элемент, в который вставляют кнопки
    paymentInfo Да Function/Object Информация о платеже

    Формирование чека

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

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

    Request Body schema: application/json
    container
    string

    ID элемента или элемент, в который вставляются кнопки

    TerminalKey
    required
    string

    Идентификатор вашего магазина

    object (PaymentInfos)

    Информация о платеже

    paymentItems
    Array of arrays

    Список объектов с информацией о размещаемых кнопках

    TinkoffPayweb (object) or TinkoffFps (object)

    Объект с информацией о платежных системах

    Responses

    Request samples

    Content type
    application/json
    {
    • "container": "string",
    • "TerminalKey": "string",
    • "paymentInfo": {
      },
    • "paymentItems": [ ],
    • "paymentSystems": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "Success": "true"
    }

    Формирование QR

    Метод регистрирует QR и возвращает информацию о нем. Должен быть вызван после вызова метода Init.

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    number

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    DataType
    string
    Default: "PAYLOAD"
    Enum: "PAYLOAD" "IMAGE"

    Тип возвращаемых данных:

    • PAYLOAD – В ответе возвращается только Payload (по-умолчанию)
    • IMAGE – В ответе возвращается SVG изображение QR
    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 10063,
    • "DataType": "PAYLOAD",
    • "Token": "871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Список банков-пользователей QR

    Метод возвращает список участников куда может быть осуществлен возврат платежа, совершенного по QR

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    number

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 10063,
    • "Token": "871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
    }

    Response samples

    Content type
    application/json
    {
    • "Members": [
      ],
    • "OrderId": "21050",
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "OK"
    }

    Привязка счёта к магазину

    Метод инициирует привязку счета клиента к магазину и возвращает информацию о нём

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    Description
    required
    string

    Подробное описание деталей заказа

    DataType
    string
    Default: "PAYLOAD"
    Enum: "PAYLOAD" "IMAGE"

    Тип возвращаемых данных:

    • PAYLOAD – В ответе возвращается только Payload (по-умолчанию)
    • IMAGE – В ответе возвращается SVG изображение QR
    object

    JSON объект, содержащий дополнительные параметры в виде ключ:значение. Данные параметры будут переданы на страницу оплаты (в случае ее кастомизации). Максимальная длина для каждого передаваемого параметра:

    • Ключ - 20 знаков;
    • Значение - 100 знаков. Максимальное количество пар ключ:значение не может превышать 20
    RedirectDueDate
    string <datatime>

    Cрок жизни ссылки или динамического QR-кода СБП (если выбран данный способ оплаты). В случае, если параметр RedirectDueDate не был передан, проверяется настроечный параметр платежного терминала REDIRECT_TIMEOUT, который может содержать значение срока жизни ссылки в часах. Если его значение больше нуля, то оно будет установлено в качестве срока жизни ссылки или динамического QR-кода. Иначе, устанавливается значение «по умолчанию» - 1440 мин (1 сутки).

    Если текущая дата превышает дату, переданную в данном параметре, ссылка для оплаты или возможность платежа по QR-коду становятся недоступными и платёж выполнить нельзя. Максимальное значение: 90 дней от текущей даты. Минимальное значение: 1 минута от текущей даты. Формат даты: YYYY-MM-DDTHH24:MI:SS+GMT

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Description": "string",
    • "DataType": "PAYLOAD",
    • "Data": {
      },
    • "RedirectDueDate": "2016-08-31T12:28:00+03:00",
    • "Token": "871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
    }

    Response samples

    Content type
    application/json
    {}

    Получение статуса привязки счёта к магазину

    Метод возвращает статус привязки счета клиента по магазину

    Request Body schema: application/json
    RequestKey
    required
    string <uuid>

    Идентификатор запроса на привязку счета

    TerminalKey
    required
    string <= 20 characters

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

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "RequestKey": "13021e10-a3ed-4f14-bcd1-823b5ac37390",
    • "TerminalKey": "TinkoffBankTest",
    • "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "testRegress",
    • "RequestKey": "211258",
    • "BankMemberId": "100000000004",
    • "BankMemberName": "Тинькофф Банк",
    • "AccountToken": "a022254a5c3c46a7327c8a12cb5c8389",
    • "Success": true,
    • "Status": "ACTIVE",
    • "ErrorCode": "0",
    • "Message": "OK"
    }

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

    Метод возвращает список привязанных счетов клиента по магазину

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

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

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "testRegress",
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "OK",
    • "AccountTokens": {
      }
    }

    Автоплатеж по QR

    Проведение платежа по привязанному счету по QR через СБП. Для возможности его использования клиент должен совершить успешную привязку счета с  помощью метода AddAccountQr. После вызова метода будет отправлена нотификация на Notification URL о привязке счета , в которой будет указан AccountToken. Для совершения платежа по привязанному счету Мерчант должен вызвать метод Init, в котором поля  Recurrent= Y и DATA= {“QR”:“true”}, а затем вызвать метод ChargeQr для оплаты по тем же самым  реквизитам и передать параметр AccountToken, полученный после привязки счета по QR в  нотификации

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

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

    PaymentId
    required
    number

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    AccountToken
    required
    string

    Идентификатор привязки счета, назначаемый банком-эмитентом

    Token
    required
    string

    Подпись запроса

    IP
    string

    IP-адрес клиента

    SendEmail
    boolean
    • true – если клиент хочет получать уведомления на почту
    InfoEmail
    string <email>

    Адрес почты клиента. Обязательно, если передан параметр SendEmail = true

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 700001702044,
    • "AccountToken": "70LSS7DN18SJQRS10006DNPKLJL24B05",
    • "Token": "f5a3be479324a6d3a4d9efa0d02880b77d04a91758deddcbd9e752a6df97cab5",
    • "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334",
    • "SendEmail": true,
    • "InfoEmail": "customer@test.com"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 100000,
    • "OrderId": "21050",
    • "Success": true,
    • "Status": "CONFIRMED",
    • "PaymentId": 13660,
    • "ErrorCode": "0",
    • "Message": "Неверные параметры",
    • "Details": "string",
    • "Currency": 643
    }

    Создание тестовой платежной сессии

    Тестовая платежная сессия с предопределенным статусом по СБП.

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    number <= 20 characters

    Идентификатор платежа в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса

    IsDeadlineExpired
    boolean

    Признак эмуляции отказа проведения платежа Банком по таймауту. По умолчанию не используется (эмуляция не требуется).

    • false – эмуляция не требуется
    • true – требуется эмуляция (не может быть использован вместе с IsRejected = true)
    IsRejected
    boolean

    Признак эмуляции отказа Банка в проведении платежа По умолчанию не используется (эмуляция не требуется)

    • false – эмуляция не требуется
    • true – требуется эмуляция (не может быть использован вместе с IsDeadlineExpired = true)

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 13660,
    • "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96",
    • "IsDeadlineExpired": true,
    • "IsRejected": false
    }

    Response samples

    Content type
    application/json
    {
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "OK",
    • "Details": "0"
    }

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

    Возвращает статус возврата платежа по СБП

    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    string

    Уникальный идентификатор транзакции в системе Тинькофф Кассы, полученный в ответе на вызов метода Init

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": "700031849",
    • "Token": "l43kb4hyi6lknb23bv4gdfskjn238fsllsdf8"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "Success": true,
    • "ErrorCode": "0",
    • "Status": "CONFIRMED",
    • "QrCancelCode": "I05043",
    • "QrCancelMessage": "У клиента нет расчетного счета в этом банке. Попробуйте вернуть деньги на счет этого клиента в другом банке",
    • "OrderId": "7830122",
    • "Amount": 10000,
    • "Message": "OK"
    }

    Оплата через Tinkoff Pay

    Общая информация

    Оплата доступна на мобильных устройствах и десктопах, проводится последовательным вызовом методов:

    • /TinkoffPay/terminals/{terminalKey}/status
    • /Init
    • /TinkoffPay/transactions/{paymentId}/versions/{version}/link либо /TinkoffPay/{paymentId}/QR

    Другие способы интеграции

    Tinkoff pay SDK

    Tinkoff pay SDK - интеграция способа оплаты в приложение. Документация по SDK активно поддерживается на GitHub.
    Адреса:

    Tinkoff pay web

    Tinkoff pay web - способ интеграции через установку виджета на сайт

    Подключение платежного виджета

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

    Вставьте следующий код на ваш сайт в место, где должна располагаться кнопка «Оплатить»

    <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="Идентификатор вашего магазина"> 
    

    Подключение Tinkoff Pay

    Подключение Tinkoff Pay в личном кабинете

    1. Перейдите в свой личный кабинет и откройте страницу интернет-магазина, для которого вы хотите подключить оплату через Tinkoff Pay на сайте. Перейдите на вкладку «Способы оплаты».
    2. Нажмите кнопку «Настроить» на плашке Tinkoff Pay, перейдите в подраздел «Своя платежная форма» и нажмите «Включить»
    3. В случае успешного подключения Tinkoff Pay для интернет-магазина должна отобразиться страница активного статуса подключения Tinkoff Pay на сайте.

    Подключение Tinkoff Pay на страницах интернет-магазина

    Вставьте приведенный ниже код на страницу вашего сайта сразу после кода платежного виджета:

    <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 запускает инициализацию платежных кнопок Tinkoff Pay. Входным параметром метода является объект с данными о настройках проведения платежей.

    Структура объекта Tinkoff Pay
    Наименование Обязательный Тип данных Описание
    paymentInfo Да Function/Object Платежная информация

    Настройка оплаты множества товаров

    Для подключения оплаты Tinkoff Pay на одной странице для нескольких товаров потребуется передавать в метод initPayments объект настроек, в котором определено поле paymentItems. Значением поля 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 Платежная информация

    Tinkoff Pay + Tinkoff ID.

    Для интеграции Tinkoff Pay + Tinkoff ID, предварительно требуется настроить интеграцию с ID. Ознакомиться с его API можно по ссылке https://developer.tinkoff.ru/products/scenarios/TID/w2w

    Подключение платежного виджета

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

    Вставьте следующий код на ваш сайт в место, где должна располагаться кнопка «Оплатить».

    <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 Идентификатор события открытия карт

    Схема интеграции сценария Tinkoff Pay + Tinkoff ID

    scheme Имплементация сценария Tinkoff Pay+Tinkoff ID требует установку на сайте SDK виджета. Необходимо подписаться на события генерируемые виджетом и дублировать их на backend в зашифрованном виде методом /v2/TinkoffPayEvent, обогащая его данными о клиенте (в данном случае это авторизационный токен AccessToken, выпущенный Tinkoff ID).

    Всего предполагается три типа событий, для каждого из которых передается набор параметров для последующей валидации: * Инициализация кнопки – процесс отображения кнопки; * Отображение счета – процесс отображения счетов, доступных клиенту для оплаты. При получении события с таким типом требуется сгенерировать платежную сессию эквайринга (в случае если она не была сгенерирована ранее – т.е. в параметрах события отсутствует PaymentId) стандартно методом /v2/Init, учитывая особенности для Tinkoff Pay (пп 2.3.). Возможны несколько сценариев развития событий:

    1. Клиент определен и имеет счета для оплаты – отобразится список счетов;
    2. Клиент не определен или требуется дополнительная аутентификация – произойдет редирект в мобильное приложение Тинькофф;
    3. Клиент определен и не имеет подходящих счетов – отобразится ошибка;
    • Оплата – проведение оплаты по выбранному счету.
      

    Результат авторизации следует принимать асинхронно через нотификации.

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

    Request Body schema: application/json
    container
    string

    ID элемента или элемент, в который вставляются кнопки

    TerminalKey
    required
    string

    Идентификатор вашего магазина

    object (PaymentInfos)

    Информация о платеже

    paymentItems
    Array of arrays

    Список объектов с информацией о размещаемых кнопках

    TinkoffPayweb (object) or TinkoffFps (object)

    Объект с информацией о платежных системах

    Responses

    Request samples

    Content type
    application/json
    {
    • "container": "string",
    • "TerminalKey": "string",
    • "paymentInfo": {
      },
    • "paymentItems": [ ],
    • "paymentSystems": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "Success": "true"
    }

    Статус

    Метод определения возможности проведения платежа Tinkoff Pay на терминале и устройстве

    path Parameters
    TerminalKey
    required
    string <= 20 characters
    Example: testRegress

    Платежный ключ, выдается Мерчанту при заведении терминала

    Responses

    Response samples

    Content type
    application/json
    {
    • "Params": {
      },
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "string",
    • "Details": "string"
    }

    Получение ссылки

    Метод получения Link для безусловного редиректа на мобильных устройствах

    path Parameters
    paymentId
    required
    number <= 20 characters
    Example: 13660

    Идентификатор платежа в системе Тинькофф Кассы

    version
    string
    Example: 1.0

    Версия Tinkoff Pay, доступная на терминале:

    • 1.0 (e-invoice)
    • 2.0 (Tinkoff Pay)

    Responses

    Response samples

    Content type
    application/json
    {
    • "Params": {
      },
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "string",
    • "Details": "string"
    }

    Получение QR

    Метод получения QR для десктопов.

    path Parameters
    paymentId
    required
    number
    Example: 700001702044

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    Responses

    Передача уведомления о событии

    Передача уведомления о событии платежного виджета Tinkoff Pay+Tinkoff ID

    Request Body schema: application/json
    TerminalKey
    required
    string

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

    required
    object (EventData)
    PaymentId
    number

    Идентификатор платежа

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "string",
    • "EventData": {
      },
    • "PaymentId": 0,
    • "Token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "Success": "true",
    • "ErrorCode": 0,
    • "Message": "string",
    • "Details": "string"
    }

    Оплата через Yandex Pay

    Общая информация

    Описание продукта

    С Yandex Pay можно оплачивать покупки на сайтах банковской картой, не вводя её данные. Для этого подойдёт карта, привязанная к аккаунту на Яндексе. Кнопка Yandex Pay отображается на платёжной странице рядом с другими способами оплаты.

    При использовании Yandex Pay необходимо соблюдать:

    1. Правила оформления бренда;
    2. Список запрещенных товаров и услуг;

    Чек-лист для подключения Yandex Pay

    1. Подключить Интернет-эквайринг;
    2. Выбрать тип интеграции;
    3. Подключить в личном кабинете.

    Подключите Интернет-эквайринг

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

    Выберите интеграцию

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

    • Кнопка Yandex Pay на Платежном виджете Тинькофф (Интеграция с Yandex Pay реализована на стороне Тинькофф Кассы)
    • Кнопка Yandex Pay на сайте Мерчанта; (Необходима прямая интеграция Мерчанта с API Тинькофф и Yandex Pay)

    Yandex Pay на Платежном виджете Тинькофф

    При таком варианте интеграции клиент находится на сайте Мерчанта только до момента ввода данных своей платежной карты или до оплаты с Yandex Pay Для оплаты клиент перенаправляется на платежную страницу Тинькофф Кассы, на которой будет отображен способ оплаты Yandex Pay После оплаты клиент будет проинформирован о результате и возвращен обратно на сайт Мерчанта, а Мерчанту будут отправлены уведомления с результатом платежа. Мерчанту не требуется интегрироваться с Yandex Pay, все необходимое уже реализовано на стороне Тинькофф Кассы

    Yandex Pay на сайте Мерчанта (API)

    Для добавления кнопки Yandex Pay на сайт необходимо иметь сертификат PCI DSS и самостоятельно выполнить интеграцию с Yandex Pay. Для выполнения платежа необходимо получить токен в Yandex Pay и передать его в платежный шлюз Тинькофф Кассы.

    Для выполнения оплаты через API необходимо:

    1. Передать в Тинькофф Кассу токен, полученный на сайте с помощью Yandex Pay Web SDK в параметре «Token».
    2. Yandex Pay формирует токен в Base64. Токен необходимо декодировать и передавать в API.

    Внимание!

    Для большинства карт в Yandex Pay будет проведена 3-D Secure аутентификация клиента

    Включение Yandex Pay

    Для включения кнопки Yandex Pay в Платежном виджете и API, необходимо переключить тоггл Yandex Pay в Личном кабинете Тинькофф Кассы.

    • Если интеграция с помощью Платежного виджета, то кнопка Yandex Pay автоматически появится на Платежном виджете Тинькофф Кассы.
    • Если интеграция по API, то отображение кнопки Yandex Pay находится на стороне Мерчанта.

    Настройка нотификаций об оплате

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

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

    Настройка нотификаций происходит через acq_help@tinkoff.ru

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

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

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

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

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string <= 20 characters

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

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

    Идентификатор заказа в системе Мерчанта

    Token
    required
    string

    Подпись запроса.

    Description
    string <= 250 characters

    Описание заказа.

    • Поле необходимо обязательно заполнять для осуществления привязки и одновременной оплаты по CБП. При оплате через СБП данная информация будет отображена в приложении мобильного банка клиента. Максимально допустимое количество знаков для передачи назначения платежа в СБП - 140 символов.
    CustomerKey
    string <= 36 characters

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

    • Обязателен, если передан атрибут Recurrent.
    • Если был передан в запросе, в нотификации будет указан CustomerKey и его CardId. См. метод GetCardList.
    • Необходим для сохранения карт на платежной форме (платежи в один клик).
    • Не является обязательным при реккурентных платежах через СБП.
    Recurrent
    string <= 1 characters

    Признак родительского рекуррентного платежа.

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

    Значение зависимо от атрибутов:

    PayType
    string
    Enum: "O" "T"

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

    • "O" - одностадийная оплата,
    • "T" - двухстадийная оплата Если параметр передан - используется его значение. Если нет - значение в настройках терминала.
    Language
    string <= 2 characters

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

    • ru — русский
    • en — английский. Если не передан, форма откроется на русском языке
    NotificationURL
    string <uri>

    URL на веб-сайте Мерчанта, куда будет отправлен POST запрос о статусе выполнения вызываемых методов (настраивается в Личном кабинете):

    • Если параметр передан – используется его значение.
    • Если нет – значение в настройках терминала.
    SuccessURL
    string <uri>

    URL на веб-сайте Мерчанта, куда будет переведен клиент в случае успешной оплаты (настраивается в Личном кабинете):

    • Если параметр передан – используется его значение.
    • Если нет – значение в настройках терминала.
    FailURL
    string <uri>

    URL на веб-сайте Мерчанта, куда будет переведен клиент в случае неуспешной оплаты (настраивается в Личном кабинете):

    • Если параметр передан – используется его значение.
    • Если нет – значение в настройках терминала.
    RedirectDueDate
    any <date-time>

    Cрок жизни ссылки или динамического QR-кода СБП (если выбран данный способ оплаты). Если текущая дата превышает дату, переданную в данном параметре, ссылка для оплаты или возможность платежа по QR-коду становятся недоступными и платёж выполнить нельзя.

    • Максимальное значение: 90 дней от текущей даты.
    • Минимальное значение: 1 минута от текущей даты.
    • Формат даты: YYYY-MM-DDTHH24:MI:SS+GMT
    • Пример даты: 2016-08-31T12:28:00+03:00
      Если не передан, принимает значение 24 часа для платежа и 30 дней для счета

    При выставлении счета через Личный кабинет:
    В случае, если параметр RedirectDueDate не был передан, проверяется настроечный параметр платежного терминала REDIRECT_TIMEOUT, который может содержать значение срока жизни ссылки в часах. Если его значение больше нуля, то оно будет установлено в качестве срока жизни ссылки или динамического QR-кода. Иначе, устанавливается значение «по умолчанию» - 1440 мин.(1 сутки)

    Common (object) or TinkoffPay (object) or YandexPay (object) or LongPay (object)

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

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

    • Ключ - 20 знаков
    • Значение - 100 знаков.

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

    1. Если у терминала включена опция привязки клиента после успешной оплаты и передается параметр CustomerKey, то в передаваемых параметрах DATA могут присутствовать параметры метода AddCustomer. Если они присутствуют, то автоматически привязываются к клиенту. Например, если указать:

      "DATA":{"Phone":"+71234567890", "Email":"a@test.com"}
      

      к клиенту автоматически будут привязаны данные Email и телефон, и они будут возвращаться при вызове метода GetCustomer.

      Для МСС 4814 обязательно передать значение в параметре Phone. Требования по заполнению:

      • минимум 7 символов
      • максимум 20 символов
      • разрешены только цифры, исключение - первый символ может быть «+»

      Для МСС 6051 и 6050 обязательно передать параметр account (номер электронного кошелька, не должен превышать 30 символов). Пример:

      "DATA": {"account":"123456789"}
      
    2. Если используется функционал сохранения карт на платежной форме, то при помощи опционального параметра DefaultCard можно задать какая карта будет выбираться по умолчанию. Возможные варианты:

    • Оставить платежную форму пустой. Пример:
      "DATA":{"DefaultCard":"none"}
      
    • Заполнить данными передаваемой карты. В этом случае передается CardId. Пример:
       "DATA":{"DefaultCard":"894952"}
      
    • Заполнить данными последней сохраненной карты. Применяется, если параметр DefaultCard не передан, передан с некорректным значением или в значении null. По умолчанию возможность сохранение карт на платежной форме может быть отключена. Для активации обратитесь в службу технической поддержки.
    1. При реализации подключения оплаты через Yandex Pay Web или Tinkoff Pay Web, необходимо обязательно передавать следующие параметры в объекте Data. Пример:

      "DATA": {
       "TinkoffPayWeb": "true",
       "Device": "Desktop",
       "DeviceOs": "iOS",
       "DeviceWebView": "true",
       "DeviceBrowser": "Safari"
      }
      

      где следует передать параметры устройства, с которого будет осуществлен переход.

    2. Параметр notificationEnableSource позволяет отправлять нотификации только если Source (также присутствует в параметрах сессии) платежа входит в перечень указанных в параметре. Возможные варианты: TinkoffPay, sbpqr, YandexPay. Пример:

      notificationEnableSource=TinkoffPay
      
    3. Для осуществления привязки и одновременной оплаты по CБП необходимо передавать параметр "QR" = "true"

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

      • Значением атрибута Reccurent в методе /Init
      • Значением атрибута RebillId в методе /Charge
      • Типом терминала, используемом для проведения операций (ECOM/AFT)

    Подробную таблицу см. в разделе Передача признака инициатора операции

    В случае передачи значений атрибутов не соответствующих таблице - MAPI вернет ошибку 1126 (Несопоставимые значения rebillId или Recurrent с переданным значением OperationInitiatorType)

    Receipt_FFD_105 (object) or Receipt_FFD_12 (object)

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

    Array of objects (Shops)

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

    Descriptor
    string

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

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 140000,
    • "OrderId": "21090",
    • "Description": "Подарочная карта на 1000 рублей",
    • "Token": "68711168852240a2f34b6a8b19d2cfbd296c7d2a6dff8b23eda6278985959346",
    • "DATA": {
      },
    • "Receipt": {
      }
    }

    Response samples

    Content type
    application/json
    {}

    Сценарии привязки карты

    Общая информация

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

    Мерчант может выбрать способ привязки клиента - с проверкой 3D-Secure или без.

    Если выбрана опция с проверкой, то клиент должен будет подтвердить операцию уже на этом этапе. Все дальнейшие платежи будут проходить по схеме реккурентного платежа, то есть подтверждать каждое списание не нужно.

    Если Мерчант выбрал опцию привязки без проверки 3D-Secure, то клиент и его карты будут сохранены без подтверждения. Однако, оно подтребуется при первом платеже по привязанной карте.

    За способ привязки отвечает параметр CheckType в запросе метода AddCard. Если Мерчант не передаст этот параметр, то MAPI, по умолчанию, будет считать, что привязка прошла без подтверждения клиента.

    Для корректной работы методов Тинькофф Касса должна разрешить Мерчанту привязывать карты и клиентов к терминалу. В результате привязки карты к параметру CustomerKey будет привязана CardId.

    Сценарии работы с картами и клиентами

    Добавление, получение и удаление клиента

    Для сохранения идентификатора клиента CustomerKey Мерчант должен вызвать метод AddCustomer и передать в запросе параметр CustomerKey.

    Для удаления клиента из списка привязанных к терминалу Мерчант должен вызвать метод RemoveCustomerпередать в запросе параметр CustomerKey.

    Для получения сохраненных данных клиента Мерчант должен вызвать метод GetCustomer и передать в запросе параметр CustomerKey.

    Добавление, получение и удаление карты

    для Мерчантов с PCI DSS

    Инициализация привязки

    После сохранения клиента в списке привязанных к терминалу Мерчант может добавить карту. Для этого он вызывает метод AddCard и передает в запросе параметр CustomerKey. В ответ MAPI пришлет идентификатор сессии привязки карты PaymentId.

    Проверка версии 3DS

    На следующем этапе Мерчант вызвает метод 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="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU2ZTcxMmE1LTE5MGEtNDU4OC05MWJjLWUwODYyNmU3N2M0NCIsInRocm
    VlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3Jlc3QtYXBpLXRlc3QudGlua29mZi5ydS92Mi9Db21wbGV0ZTNEU0
    1ldGhvZHYyIn0">
    </form>
    </body>
    

    Пример декодированного значения threeDSMethodData:

    {
    "threeDSServerTransID":"56e712a5-190a-4588-91bc-e08626e77c44",
    "threeDSMethodNotificationURL":"https://rest-api-test.tinkoff.ru/v2/>Complete3DSMethodv2"
    }
    

    Завершение привязки

    Для завершения привязки карты Мерчант вызывает метод AttachCard и передает зашифрованные карточные данные, а также набор параметров для прохождения проверки 3D-Secure.

    В ответ MAPI вернет один из возможных статусов:

    Статус Описание Доступные действия
    REJECTED Привязка отклонена Провести привязку заново
    COMPLETED Успешная привязка карты -
    3DS_CHECKING Требуется подтверждение привязки по 3D-Secure
    • Отменить привязку
    • Пройти подтверждение

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

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

    3DS 1.0

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

    Название параметра Описание
    MD Информация для идентификации платежной сессии на стороне торговой точки. Придет в ответе метода AttachCard
    PaReq Запрос на аутентификацию плательщика, который содержит разные детали транзакции. Придет в ответе метода AttachCard
    TermURL Адрес перенаправления после аутентификации 3DS. Должен содержать ссылку на обработчик на стороне Мерчанта, принимающий результаты прохождения 3-D Secure
    3DS 2.0

    Если версия 3DS 2.0, то в запросе передаются параметры, в зависимости от типа устройства клиента.

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

    Название параметра Тип данных Описание
    creq string JSON с параметрами threeDSServerTransID, acsTransID,challengeWindowSize, messageType, messageVersion закодированный в формат base64

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

    Название параметра Тип данных Описание
    threeDSServerTransID string Идентификатор транзакции из ответа метода AttachCard
    acsTransID string Идентификатор транзакции, присвоенный ACS, полученный в ответе на AttachCard
    challengeWindowSize string Размер экрана, на котором открыта страница ACS.Допустимые значения:
  • 01 = 250 x 400
  • 02 = 390 x 400
  • 03 = 500 x 600
  • 04 = 600 x 400
  • 05 = Full screen
  • messageType string Передается фиксированное значение «CReq»
    messageVersion string Версия 3DS, полученная из ответа метода Check3dsVersion

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

    Название параметра Тип данных Описание
    creq string JWE object с параметрами threeDSServerTransID, acsTransID, messageType, messageVersion, sdkTransID, sdkCounterStoA закодированный в формат PS256

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

    Название параметра Тип данных Описание
    threeDSServerTransID string Идентификатор транзакции из ответа метода AttachCard
    acsTransID string Идентификатор транзакции, присвоенный ACS, полученный в ответе на AttachCard
    messageType string Передается фиксированное значение «CReq»
    messageVersion string Версия 3DS, полученная из ответа метода Check3dsVersion
    sdkTransID string Уникальный идентификатор транзакции, назначенный 3DS SDK для идентификации одной транзакции, полученный в ответе на AttachCard
    sdkCounterStoA string Внутренний счетчик 3DS SDK внутри ACS. Поддерживаемые значения:
    000-255

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

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

    • Для 3DS 1.0 - Submit3DSAuthorization
    • Для 3DS 2.0 - Submit3DSAuthorizationV2

    Завершение привязки

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

    Статусная модель привязки карты

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

    Статус Описание
    NEW Новая сессия
    FORM_SHOWED Показ формы привязки карты
    3DS_CHECKING Отправка клиента на проверку 3DS
    3DS_CHECKED Клиент успешно прошел проверку 3DS
    AUTHORIZING Отправка платежа на 0 руб
    AUTHORIZED Платеж на 0 руб прошел успешно
    COMPLETED Привязка успешно завершена
    REJECTED Привязка отклонена

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

    scheme

    Методы работы с клиентами

    Регистрация клиента

    Регистрирует клиента в связке с терминалом. Возможна автоматическая привязка клиента и карты, по которой был совершен платеж, при передаче параметра CustomerKey в методе Init. Это можно использовать для сохранения и последующего отображения клиенту замаскированного номера карты, по которой будет совершен рекуррентный платеж

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CustomerKey
    required
    string <= 36 characters

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

    Token
    required
    string

    Подпись запроса

    IP
    string <= 40 characters

    IP-адрес запроса

    Email
    string <email> <= 64 characters

    Email клиента

    Phone
    string <= 64 characters

    Телефон клиента в формате +{Ц}

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "4387c647-a693-449d-bc35-91faecfc50de",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e",
    • "IP": "10.100.10.10",
    • "Email": "username@test.ru",
    • "Phone": "+79031234567"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "05d65baa-9718-445e-8212-76fa0dd4c1d2",
    • "ErrorCode": "0",
    • "Success": true,
    • "Message": "Неверные параметры",
    • "Details": "Терминал не найден"
    }

    Получение данных клиента

    Возвращает данные клиента, сохраненные в связке с терминалом

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CustomerKey
    required
    string <= 36 characters

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

    Token
    required
    string

    Подпись запроса

    IP
    string <= 40 characters

    IP-адрес запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "string",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e",
    • "IP": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "4264aa7b-08ab-4429-ab5a-2a171d841ced",
    • "ErrorCode": "0",
    • "Success": true,
    • "Message": "Неверный статус клиента",
    • "Details": "Клиент не найден.",
    • "Email": "a@test.ru",
    • "Phone": "+79031234567"
    }

    Удаление данных клиента

    Удаляет сохраненные данные клиента

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CustomerKey
    required
    string <= 36 characters

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

    Token
    required
    string

    Подпись запроса

    IP
    string <= 40 characters

    IP-адрес запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "string",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e",
    • "IP": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "string",
    • "ErrorCode": "0",
    • "Success": true,
    • "Message": "Неверные параметры",
    • "Details": "string"
    }

    Методы работы с картами

    Инициализация привязки карты к клиенту

    Для Мерчантов с PCI DSS
    Метод инициирует привязку карты к клиенту. В случае успешной привязки переадресует клиента на Success Add Card URL, в противном случае на Fail Add Card URL. Можно использовать форму Тинькофф Кассы, возможно заменить на кастомную форму

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CustomerKey
    required
    string <= 36 characters

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

    Token
    required
    string

    Подпись запроса

    CheckType
    string
    Enum: "NO" "HOLD" "3DS" "3DSHOLD"

    Если CheckType не передается, автоматически проставляется значение NO. Возможные значения: Возможные значения:

    • NO – сохранить карту без проверок. RebillID для рекуррентных платежей не возвращается;
    • HOLD – при сохранении сделать списание на 0 руб. RebillID возвращается для терминалов без поддержки 3DS.
    • 3DS – при сохранении карты выполнить проверку 3DS и выполнить списание на 0 р. В этом случае RebillID будет только для 3DS карт. Карты, не поддерживающие 3DS, привязаны не будут.
    • 3DSHOLD – при привязке карты выполнить проверку, поддерживает карта 3DS или нет. Если карта не поддерживает 3DS, то выполняется списание на 0 руб.
    IP
    string <= 40 characters

    IP-адрес запроса

    ResidentState
    boolean

    Признак резидентности добавляемой карты: Возможные значения:

    • true - Карта РФ;
    • false - Карта не РФ;
    • null - Не специфицируется (универсальная карта)

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "1111133333",
    • "CustomerKey": "testCustomer1234",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e",
    • "CheckType": "NO",
    • "IP": "10.100.10.10",
    • "ResidentState": true
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "PaymentId": 6155312072,
    • "TerminalKey": "TinkoffBankTest",
    • "CustomerKey": "906540",
    • "RequestKey": "ed989549-d3be-4758-95c7-22647e03f9ec",
    • "ErrorCode": "0",
    • "Success": true,
    • "Message": "Неверные параметры",
    • "Details": "Терминал не найден",
    • "PaymentURL": "82a31a62-6067-4ad8-b379-04bf13e37642d"
    }

    Привязка карты

    Для Мерчантов с PCI DSS
    Завершает привязку карты к клиенту.
    В случае успешной привязки переадресует клиента на Success Add Card URL в противном случае на Fail Add Card URL.
    Для прохождения 3DS второй версии перед вызовом метода должен быть вызван /v2/check3dsVersion и выполнен 3DS Method, который является обязательным при прохождении 3DS по протоколу версии 2.0.

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

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

    RequestKey
    required
    string <uuid>

    Идентификатор запроса на привязку карты

    CardData
    required
    string

    Зашифрованные данные карты в формате: PAN=4300000000000777;ExpDate=0519;CardHolder=IVAN PETROV;CVV=111

    object or 3DSv2 (object)

    В объекте передаются дополнительные параметры в формате Ключ:Значение с разделителем |, например,

    {"javaEnabled"="false"|"screen_height"="854"}
    

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

    • Ключ – 20 знаков,
    • Значение – 100 знаков.

    Максимальное количество пар «ключ-значение» не может превышать 20.

    ВАЖНО! Для 3DS второй версии в DATA необходимо передавать параметры, описанные в объекте 3DSv2. В HttpHeaders запроса обязательны заголовки: User-Agent и Accept.

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "RequestKey": "13021e10-a3ed-4f14-bcd1-823b5ac37390",
    • "CardData": "U5jDbwqOVx+2vDApxe/rfACMt+rfWXzPdJ8ZXxNFVIiZaLZrOW72bGe9cKZdIDnekW0nqm88YxRD↵jyfa5Ru0kY5cQV alU+juS1u1zpamSDtaGFeb8sRZfhj72yGw+io+qHGSBeorcfgoKStyKGuBPWfG↵d0PLHuyBE6QgZyIAM1XfdmNlV0UAxOnkTGDsskL pIt3AWhw2e8KOar0vwbgCTDjznDB1/DLgOW01↵Aj/bXyLJoG1BkOrPBm9JURs+f+uyFae0hkRicNKNgXoN5pJTSQxOEauOi6ylsVJ B3WK5MNYXtj6x↵GlxcmTk/LD9kvHcjTeojcAlDzRZ87GdWeY8wgg==",
    • "DATA": {
      },
    • "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "testRegress",
    • "CustomerKey": "testCustomerKey",
    • "RequestKey": "8de92934-26c9-474c-a4ce-424f2021d24d",
    • "CardId": "5555",
    • "Success": true,
    • "ErrorCode": "0",
    • "Status": "NEW",
    • "RebillId": "130799909",
    • "Message": "Неверные параметры",
    • "Details": "string",
    • "MD": "ACQT-563587431",
    • "PaReq": "eJxVUl1TwjAQ/CtM30s+KLTDHGHQwsiogFh09C2kp1RpC2nLh7/eBAtqnnYvN3ubvUD/kK4bO9RFkmc9hzWp08BM5XGSvfecRT RyA6cvIFppxPARVaVRwD0WhXzHRhL3HMUU73itwKVtyl1Pcs8Nli3pymUQK+z2Sww6joDZYI5bAfUgYeY0OZAzNYparWRWCpBqe zWeiDZnLe3BqSmkqMeh4PRy2p02BfJThkymKCIsSiAnCCqvslIfhXEG5Eyg0muxKstN0SVkv983yyT7zN/emroiQOwlkF8js8qiwogdk lg8rEfT5WK0jj6G7D4cepNo8TWNBmwSDXtAbAfEskTjkPk0oF6DeV3a6jLj8VQHmVoXglFTqTFs7IjBn4u/BTBZa7OK8yPODPCwyT M0HSbACwby6/f6xsaoSpNMMN89+uHdV/iUPz2nyat/uxrPXz5nuX/c2nBPTVYxMflwzthJ0hIgVobUeyP1yg469xW+AedOuuM="
    }

    Статус привязки карты

    Для мерчантов с PCI DSS
    Метод возвращает статус привязки карты

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    RequestKey
    required
    string

    Идентификатор запроса на привязку карты

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "testRegressBank",
    • "RequestKey": "13021e10-a3ed-4f14-bcd1-823b5ac37390",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "RequestKey": "13021e10-a3ed-4f14-bcd1-823b5ac37390",
    • "Status": "NEW",
    • "Success": true,
    • "CardId": "156516516",
    • "RebillId": "134249124",
    • "ErrorCode": "0",
    • "Message": "Неверные параметры",
    • "Details": "Данный RequestKey не найден.",
    • "CustomerKey": "testCustomer1234"
    }

    Список карт клиента

    Возвращает список всех привязанных карт клиента, включая удаленные

    Request Body schema: application/json
    One of
    TerminalKey
    required
    string

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CustomerKey
    required
    string

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

    SavedCard
    boolean

    Признак сохранения карты для оплаты в 1 клик

    Token
    required
    string

    Подпись запроса

    IP
    string

    IP-адрес запроса

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "testRegressBank",
    • "CustomerKey": "testCustomer1234",
    • "SavedCard": "Y",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e",
    • "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334"
    }

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Удаление привязанной карты клиента

    Метод удаляет привязанную карту клиента

    Request Body schema: application/json
    TerminalKey
    required
    string <= 20 characters

    Идентификатор терминала, выдается Мерчанту Тинькофф Кассой

    CustomerKey
    required
    string <= 36 characters

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

    CardId
    required
    string <= 40 characters

    Идентификатор карты в системе Тинькофф Кассы

    Token
    required
    string

    Подпись запроса

    IP
    string <= 40 characters

    IP-адрес запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "testRegressBank",
    • "CustomerKey": "testCustomer1234",
    • "CardId": "156516516",
    • "Token": "30797e66108934dfa3d841b856fdad227c6b9c46d6a39296e02dc800d86d181e",
    • "IP": "2011:0db8:85a3:0101:0101:8a2e:0370:7334"
    }

    Response samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Status": "D",
    • "CustomerKey": "testCustomer1234",
    • "CardId": "156516516",
    • "CardType": 0,
    • "Success": true,
    • "ErrorCode": "0",
    • "Message": "Неверные параметры",
    • "Details": "Не удалось удалить карту клиента, для данного клиента такая карта не существует."
    }

    Нотификации Мерчанта об операциях

    Нотификации – это уведомления магазину о статусе выполнения платежа. На основании этих уведомлений магазин должен предоставлять услугу/товар клиенту.

    Нотификации по E-mail

    Тинькофф Касса может присылать письма с уведомлениями об успешных платежах (статус CONFIRMED). Настроить нотификации на электронную почту можно в личном кабинете. Уведомления на почту можно комбинировать с уведомлениями, отправляемыми по http(s).

    Нотификации по HTTP(s)

    При совершении операций Authorize, FinishAuthorize, Confirm, Cancel на адрес Notification URL высылается уведомление POST-запросом с информацией об операции. При использовании одностадийного проведения платежа при обращении к методу FinishAuthorize нотификация отправляется на сайт Мерчанта на адрес Notification URL синхронно и ожидает ответа в течение 10 секунд.

    После получения ответа или неполучения его за заданное время сервис переадресует клиента на Success URL или Fail URL в зависимости от результата платежа.

    В случае успешной обработки нотификации Мерчант должен вернуть ответ c HTTP-кодом сообщения 200 с телом сообщения: OK (без тегов и заглавными английскими буквами). Если тело сообщения отлично от OK, любая нотификация считается неуспешной, и сервис будет повторно отправлять нотификацию раз в час в течение 24 часов. Если нотификация за это время так и не доставлена, она складывается в дамп.

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

    Если в NotificationURL используются порты, допустимо использование порта 443 (HTTPS). Актуальный список внешних сетей*, используемых Тинькофф Касса, для отправки нотификаций:

    • 91.194.226.0/23
    • 91.218.132.0/24
    • 91.218.133.1/24
    • 91.218.134.0/24
    • 91.218.135.0/24
    • 212.233.80.0/24
    • 212.233.81.0/24
    • 212.233.82.0/24
    • 91.194.226.181 (тестовая среда)

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

    Укажите в настройках терминала URL, чтобы получать на него POST-запросы со статусами:

    Статус Описание
    AUTHORIZED Деньги захолдированы на карте клиента. Ожидается подтверждение операции *
    CONFIRMED Операция подтверждена
    PARTIAL_REVERSED Частичная отмена
    REVERSED Операция отменена
    PARTIAL_REFUNDED Произведён частичный возврат
    REFUNDED Произведён возврат
    REJECTED Списание денежных средств закончилась ошибкой
    3DS_CHECKING ** Автоматическое закрытие сессии, которая превысила срок пребывания в статусе 3DS_CHECKING (более 36 часов)

    * Операция может быть подтверждена:

    • Через Личный Кабинет;
    • Запросом Confirm;
    • Автоматически, если у магазина настроена одностадийная схема оплаты для магазина в Личном Кабинете.
    • По неподтвержденным операциям возмещение не производится. Узнать статус платежа можно с помощью вызова метода GetState.

    ** Напишите на почту acq_help@tinkoff.ru c просьбой включить отправку нотификаций об автозакрытии сессий в статусе 3DS_CHECKING

    Ответ на HTTP(s)-нотификацию

    В случае успешной обработки нотификации Мерчанту необходимо вернуть ответ HTTP CODE = 200 с телом сообщения: OK (без тегов и заглавными английскими буквами).

    PHP. Пример ответа на http(s)-нотификацию

    <?php
    echo «OK»;
    ?>
    

    Java. Пример ответа на http(s)-нотификацию

    @POST
    @Path("/ok")
    public Response NotifyResponse() {
    return Response.status(200).entity("OK").build();
    }
    

    Если ответ «OK» не получен, нотификация считается неуспешной, и сервис будет повторно отправлять данную нотификацию раз в час в течение 24 часов. Если нотификация за это время не доставлена, она будет сложена в архив.

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

    Проверка токенов

    Для формирования подписи запроса для нотификации небходимо:

    1. Собрать массив всех обязательных передаваемых параметров для конкретного метода в виде пар Ключ-Значение (кроме параметра Token). Например:

      [["TerminalKey": "1321054611234DEMO"],["OrderId": "201709"],["Success": "true"],["Status": "AUTHORIZED"],["PaymentId": "8742591"],["ErrorCode": "0"],["Amount": "9855"],["CardId": "322264"],["Pan": "430000******0777"],["ExpDate": "1122"],["RebillId": "101709"]]
      
    2. Добавить в массив пару (Password, значение). Password – пароль для терминала, указан в личном кабинете мерчанта:

      [["TerminalKey": "1321054611234DEMO"],["OrderId": "201709"],["Success": "true"],["Status": "AUTHORIZED"],["PaymentId": "8742591"],["ErrorCode": "0"],["Amount": "9855"],["CardId": "322264"],["Pan": "430000******0777"],["ExpDate": "1122"],["RebillId": "101709"],["Password": "Dfsfh56dgKl"]]
      
    3. Отсортировать массив по Ключам по алфавиту:

      [["Amount": "9855"],["CardId": "322264"],["ErrorCode": "0"],["ExpDate": "1122"],["OrderId": "201709"],["Pan": "430000******0777"],["Password": "Dfsfh56dgKl"],["PaymentId": "8742591"],["RebillId": "101709"],["Status": "AUTHORIZED"],["Success": "true"],["TerminalKey": "1321054611234DEMO"]]
      
    4. Конкатенировать значения всех пар:

      985532226401122201709430000******0777Dfsfh56dgKl8742591101709AUTHORIZEDtrue1321054611234DEMO
      
    5. Вычислить SHA-256 от полученного в п.4. значения:

      b906d28e76c6428e37b25fcf86c0adc52c63d503013fdd632e300593d165766b
      

    Пример генерации токена:

    private static final String PASSWORD_KEY = "Password"; private static final String PASSWORD_VALUE = "12345678";
    private String generateToken(final Map<String, String> parameters) throws UnsupportedEncodingException,
    NoSuchAlgorithmException { final Map<String, String> sortedParameters = new TreeMap<String, String>(parameters);
    if (sortedParameters.containsKey(TOKEN)) {
    sortedParameters.remove(TOKEN);
    }
    sortedParameters.put(PASSWORD_KEY, PASSWORD_VALUE); final String paramString =
    Joiner.on("").skipNulls().join(sortedParameters.values()); return
    calculateSha256(paramString);
    }
    

    Пример сравнения токенов:

    private boolean checkToken(final Map<String,String> params, final String expectedToken) {
    final String actualToken = params.get(TOKEN);
    return !(expectedToken == null || !expectedToken.equals(actualToken));
    }
    

    Нотификации

    Метод реализуется на стороне Мерчанта для получения уведомлений об изменении статуса платежа.

    Нотификации о привязке (NotificationAddCard) Для Мерчантов с PCI DSS
    Уведомления магазину о статусе выполнения метода привязки карты AttachCard. После успешного выполнения метода AttachCard Тинькофф Касса отправляет POST-запрос с информацией о привязке карты. Нотификация отправляется на ресурс Мерчанта на адрес Notification URL синхронно и ожидает ответа в течение 10 секунд. После получения ответа или неполучения его за заданное время сервис переадресует клиента на Success AddCard URL или Fail AddCard URL в зависимости от результата привязки карты. В случае успешной обработки нотификации Мерчант должен вернуть ответ с телом сообщения: OK (без тегов и заглавными английскими буквами).
    Если тело сообщения отлично от OK, любая нотификация считается неуспешной, и сервис будет повторно отправлять нотификацию раз в час в течение 24 часов. Если нотификация за это время так и не доставлена, она складывается в дамп.

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

    Нотификация о статусе привязки счета по QR (NotificationQr)
    После привязки счета по QR, магазину отправляется статус привязки и токен. Нотификация будет приходить по статусам ACTIVE и INACTIVE.

    Request Body schema: application/json
    One of
    TerminalKey
    string <= 20 characters

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

    Amount
    number <= 10 characters

    Сумма в копейках

    OrderId
    string <= 36 characters

    Идентификатор заказа в системе Мерчанта

    Success
    boolean

    Выполнение платежа

    Status
    string <= 20 characters

    Статус платежа

    PaymentId
    number <= 20 characters

    Уникальный идентификатор транзакции в системе Тинькофф Кассы

    ErrorCode
    string <= 20 characters

    Код ошибки. «0» в случае успеха

    Message
    string

    Краткое описание ошибки

    Details
    string

    Подробное описание ошибки

    RebillId
    string <= 20 characters

    Идентификатор автоплатежа

    CardId
    string

    Идентификатор карты в системе Тинькофф Кассы

    Pan
    string

    Замаскированный номер карты/Замаскированный номер телефона

    ExpDate
    string

    Срок действия карты В формате MMYY, где YY — две последние цифры года

    Token
    string

    Подпись запроса. Формируется по такому же принципу, как и в случае запросов в Тинькофф Кассу

    object (DataNotification)

    Дополнительные параметры платежа, переданные при создании заказа. Явяляются обязательными для платежей «в Рассрочку»

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "TerminalKey": "TinkoffBankTest",
    • "Amount": 100000,
    • "OrderId": "21050",
    • "Success": true,
    • "Status": "string",
    • "PaymentId": 13660,
    • "ErrorCode": "0",
    • "Message": "string",
    • "Details": "string",
    • "RebillId": 3207469334,
    • "CardId": "10452089",
    • "Pan": "string",
    • "ExpDate": "0229",
    • "Token": "7241ac8307f349afb7bb9dda760717721bbb45950b97c67289f23d8c69cc7b96",
    • "DATA": {
      }
    }

    Общая информация

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

    Передаваемый чек может быть в формате ФФД 1.05 и ФФД 1.2 (зависит от привязанной к терминалу онлайн-кассы). Для передачи чека в формате ФФД 1.2 необходимо наличие привязанной к терминалу кассы с поддержкой ФФД 1.2 и передача в чеке параметра "FfdVersion" "1.2".

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

    Чек возврата передается в методе Cancel. В чеке должна быть указаны позиции возврата, сумма чека возврата должна совпадать с возвращаемой суммой.

    Методы работы с чеками

    Закрывающий чек в кассу

    Метод позволяет отправить закрывающий чек в кассу. Условия работы метода:

    1. Закрывающий чек может быть отправлен если платежная сессия по первому чеку находится в статусе CONFIRMED.
    2. В платежной сессии был передан объект Receipt.
    3. В объекте Receipt был передан хотя бы один объект Receipt.Items.PaymentMethod = full_prepayment или prepayment или advance
    Request Body schema: application/json
    TerminalKey
    required
    string

    Идентификатор терминала выдается Мерчанту Тинькофф Кассой

    PaymentId
    required
    number

    Идентификатор платежа в системе Тинькофф Кассы

    required
    Receipt_FFD_12 (object) or Receipt_FFD_105 (object)

    Объект с данными чека

    Token
    required
    string

    Подпись запроса

    Responses

    Request samples

    Content type
    application/json
    {
    • "TerminalKey": "TinkoffBankTest",
    • "PaymentId": 2304882,
    • "Receipt": {
      },
    • "Token": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "Success": true,
    • "ErrorCode": "2304882",
    • "Message": "Неверные параметры"
    }

    Описание дополнительных объектов

    Структура объекта Receipt для ФФД 1.05

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

    Параметр Тип Обязательность Описание
    Items Array of objects Да Массив, содержащий в себе информацию о товарах.
    См. Структура объекта Items
    FfdVersion String Нет
    Версия ФФД.
    Возможные значения:
    • "FfdVersion": "1.2"
    • "FfdVersion": "1.05"
    По умолчанию версия ФФД - 1.05.
    Email String Нет* Электронная почта для отправки чека
    Phone String Нет* Телефон для отправки чека
    Taxation Enum Да Система налогообложения. Перечисление с возможными значениями:
    - osn - общая СН;
    - usn_income - упрощенная СН;
    - usn_income_outcome - упрощенная СН (доходы минус расходы);
    - envd - единый налог на вмененный доход;
    - esn - единый сельскохозяйственный налог;
    - patent - патентная СН;
    Payments Object Нет** Объект c информацией о видах суммы платежа.
    См. Структура объекта Payments

    *Должен быть заполнен параметр или Phone, или E-mail
    **Если объект не передан, будет автоматически указана итоговая сумма чека с видом оплаты "Безналичный".
    Если передан объект receipt.Payments, то значение в Electronic должно быть равно итоговому значению Amount в методе Init. При этом сумма введенных значений по всем видам оплат, включая Electronic, должна быть равна сумме (Amount) всех товаров, переданных в объекте receipt.Items.

    Структура объекта Shops

    Параметр Тип Обязательность Описание
    ShopCode String Да Присвоенный идентификатор точки на стороне банка
    Amount String Да Сумма в копейках, которая относится к указанному ShopCode
    Name String Нет Наименование позиции. Максимум 128 символов
    Fee String Нет Сумма комиссии в копейках, удерживаемая из возмещения Партнера в пользу Маркетплейса.
    Если не передано, используется комиссия, указанная при регистрации.

    Структура объекта Items

    Параметр Тип Обязательность Описание
    Name String Да Наименование товара
    Price Number Да Цена в копейках
    Quantity Number Да Количество/вес:
    - целая часть не более 5 знаков;
    - дробная часть не более 3 знаков для Атол, не более 2 знаков для CloudPayments.
    Amount Number Да Сумма в копейках. Целочисленное значение не более 10 знаков
    PaymentMethod Enum Да Признак способа расчёта. Если значение не передано, по умолчанию в онлайн-кассу передается признак способа расчёта "full_payment". Возможные значения:
    − «full_prepayment» – предоплата 100%.
    − «prepayment» – предоплата.
    − «advance» – аванс.
    − «full_payment» – полный расчет.
    − «partial_payment» – частичный расчет и
    кредит.
    − «credit» – передача в кредит.
    − «credit_payment» – оплата кредита.
    PaymentObject Enum Да Признак предмета расчёта.Если значение не передано, по умолчанию в онлайн-кассу отправляется признак предмета расчёта "commodity".
    Возможные значения:
    − «commodity» – товар.
    − «excise» – подакцизный товар.
    − «job» – работа.
    − «service» – услуга.
    − «gambling_bet» – ставка азартной игры.
    − «gambling_prize» – выигрыш азартной игры.
    − «lottery» – лотерейный билет.
    − «lottery_prize» – выигрыш лотереи.
    − «intellectual_activity» – предоставление результатов интеллектуальной деятельности.
    − «payment» – платеж.
    − «agent_commission» – агентское вознаграждение.
    − «composite» – составной предмет расчета.
    − «another» – иной предмет расчета
    Tax Enum Да Ставка налога. Перечисление со значениями:
    - none - без НДС;
    - vat0 - НДС по ставке 0%;
    - vat10 - НДС чека по ставке 10%;
    - vat20 - НДС чека по ставке 20%;
    - vat110 - НДС чека по расчетной ставке 10/110;
    - vat120 - НДС чека по расчетной ставке 20/120.
    Ean13 String Нет Штрих-код в требуемом формате. В зависимости от типа кассы требования могут отличаться:
    АТОЛ Онлайн - шестнадцатеричное представление с пробелами. Максимальная длина – 32 байта (^[a-fA-F0-9]{2}$)
    ShopCode String Нет Код магазина. Для параметра ShopСode необходимо использовать значение параметра Submerchant_ID, полученного в ответ при регистрации магазинов через xml. Если xml не используется, передавать поле не нужно.
    AgentData Object Да, если используется агентская схема Данные агента. Параметры объекта описаны в таблице Структура объекта AgentData
    SupplierInfo Object Да, если передается значение AgentSign в объекте AgentData Данные поставщика платежного агента. араметры объекта описаны в таблице Структура объекта AgentData

    Структура объекта Payments

    Параметр Тип Обязательность Описание
    Cash Number(14) Нет Вид оплаты "Наличные". Сумма к оплате в копейках не более 14 знаков.
    Electronic Number(14) Да Вид оплаты "Безналичный"
    AdvancePayment Number(14) Нет Вид оплаты "Предварительная оплата (Аванс)"
    Credit Number(14) Нет Вид оплаты "Постоплата (Кредит)"
    Provision Number(14) Нет Вид оплаты "Иная форма оплаты"

    Структура объекта AgentData

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

    Параметр Тип Обязательность Описание
    AgentSign String Нет Признак агента.
    Возможные значения:
    • bank_paying_agent – банковский платежный агент
    • bank_paying_subagent – банковский платежный субагент
    • paying_agent – платежный агент
    • paying_subagent – платежный субагент
    • attorney – поверенный
    • commission_agent – комиссионер
    • another – другой тип агента
    OperationName String Нет Наименование операции.
    Атрибут обязателен, если AgentSign передан в значениях:
    • bank_paying_agent
    • bank_paying_subagent
    Phones Array of Strings Нет Телефоны платежного агента, в формате +{Ц}.
    Атрибут обязателен, если в AgentSign передан в значениях:
    • bank_paying_agent
    • bank_paying_subagent
    • paying_agent
    • paying_subagent
    ReceiverPhones Array of Strings Нет Телефоны оператора по приему платежей, в формате +{Ц}.
    Атрибут обязателен, если в AgentSign передан в значениях:
    • paying_agent
    • paying_subagent
    TransferPhones Array of Strings Нет Телефоны оператора перевода, в формате +{Ц}.
    Атрибут обязателен, если в AgentSign передан в значениях:
    • bank_paying_agent
    • bank_paying_subagent
    OperatorName String Нет Наименование оператора перевода.
    Атрибут обязателен, если в AgentSign передан в значениях:
    • bank_paying_agent
    • bank_paying_subagent
    OperatorAddress String Нет Адрес оператора перевода.
    Атрибут обязателен, если в AgentSign передан в значениях:
    • bank_paying_agent
    • bank_paying_subagent
    OperatorInn String Нет ИНН оператора перевода.
    Атрибут обязателен, если в AgentSign передан в значениях:
    • bank_paying_agent
    • bank_paying_subagent

    Структура объекта SupplierInfo

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

    Параметр Тип Обязательность Описание
    Phones Массив String Да, если передается значение AgentSign в объекте AgentData Телефон поставщика, в формате +{Ц} (1-19 символов в каждой строке массива).
    Name String Да, если передается значение AgentSign в объекте AgentData Наименование поставщика.
    Внимание: в данные 239 символов включаются телефоны поставщика + 4 символа на каждый телефон.
    Например, если передано два телефона поставщика длиной 12 и 14 символов, то максимальная длина наименования поставщика будет 239 – (12 + 4) – (14 + 4) = 205 символов
    Inn String Да, если передается значение AgentSign в объекте AgentData ИНН поставщика, в формате ЦЦЦЦЦЦЦЦЦЦ (10-12 символов).

    Пример запроса:

    {
    "TerminalKey":"TinkoffBankTest",
    "Amount":140000,
    "OrderId":"21050",
    "Description":"Подарочная карта на 1000 рублей",
    "Token":"871199b37f207f0c4f721a37cdcc71dfcea880b4a4b85e3cf852c5dc1e99a8d6"
    "DATA":{
    "Phone":"+71234567890",
    "Email":"a@test.com"},
    "Receipt": {
          "Email":"a@test.ru",
          "Phone":"+79031234567",
          "Taxation":"osn",
          "Items": [
            {
              "Name":"Наименование товара 1",
              "Price":10000,
              "Quantity":1.00,
              "Amount":10000,
              "Tax":"vat10"
            },
            {
              "Name":"Наименование товара 2",
              "Price":20000,
              "Quantity":2.00,
              "Amount":40000,
              "Tax":"vat20"
            },
            {
              "Name":"Наименование товара 3",
              "Price":30000,
              "Quantity":3.00,
              "Amount":90000,
              "Tax":"vat10"
            }
          ]
        }
    }
    

    Пример запроса, если используется агентская схема:

    {
    "TerminalKey":"TinkoffBankTest",
    "Amount": 50000,
    "OrderId":"21050",
    "Description":"Подарочная карта на 1000 рублей",
    "Token":"2ED30E046136931431B5251B7C9A1EAC68DAB082203BD42676BA14A851359DF4",
    "DATA":{"Phone":"+71234567890","Email":"a@test.com"},
    "Receipt": {
          "Email": "a@test.ru",
          "Phone": "+79031234567",
          "Taxation": "osn",
       "Customer":"TestCustomer",
       "CustomerInn":"1234567890",
       "Payments": {
                "electronic": 50000,
                "cash": 90000,
                "advancePayment": 0,
                "credit": 0,
                "provision": 0
            },
       "AgentData": {
                "AgentSign": "bank_paying_subagent",
                "OperationName": "Чек",
                "Phones": ["+19221210697", "+19098561231"],
                "ReceiverPhones": ["+29221210697", "+29098561231"],
                "TransferPhones": ["+39221210697"],
                "OperatorName": "Tinkoff",
                "OperatorAddress": "г.Москва",
                "OperatorInn": "7710140679"
            },
            "SupplierInfo": {
                "Phones": ["+49221210697", "+49098561231"]
            },
          "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.00,
              "Amount": 10000,
              "Tax": "vat10",
              "Ean13": "303130323930303030630333435",
              "ShopCode": "12345",
              "MeasurementUnit": "шт"
            },
            {
              "Name": "Наименование товара 2",
              "Price": 20000,
              "Quantity": 2.00,
              "Amount": 40000,
              "Tax": "vat20"
            },
            {
              "Name": "Наименование товара 3",
              "Price": 30000,
              "Quantity": 3.00,
              "Amount": 90000,
              "Tax": "vat10"
            }
          ]
        }
    }
    

    Структура объекта Receipt для ФФД 1.2

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

    Параметр Тип Обязательность Описание
    Items Array of objects Да Массив, содержащий в себе информацию о товарах.
    См. Структура объекта Items
    FfdVersion String Нет
    Версия ФФД.
    Возможные значения:
    • "FfdVersion": "1.2"
    • "FfdVersion": "1.05"
    По умолчанию версия ФФД - 1.05.
    Email String Нет* Электронная почта для отправки чека
    Phone String Нет* Телефон для отправки чека
    Taxation Enum Да Система налогообложения. Перечисление с возможными значениями:
    - osn - общая СН;
    - usn_income - упрощенная СН;
    - usn_income_outcome - упрощенная СН (доходы минус расходы);
    - envd - единый налог на вмененный доход;
    - esn - единый сельскохозяйственный налог;
    - patent - патентная СН;
    Payments Object Нет** Объект c информацией о видах суммы платежа.
    См. Структура объекта Payments

    *Должен быть заполнен параметр или Phone, или E-mail
    **Если объект не передан, будет автоматически указана итоговая сумма чека с видом оплаты "Безналичный".
    Если передан объект receipt.Payments, то значение в Electronic должно быть равно итоговому значению Amount в методе Init. При этом сумма введенных значений по всем видам оплат, включая Electronic, должна быть равна сумме (Amount) всех товаров, переданных в объекте receipt.Items.

    Наименование Тип Обязательность Описание
    FfdVersion String Нет
    Версия ФФД.
    Возможные значения:
    • "FfdVersion": "1.2"
    • "FfdVersion": "1.05"
    По умолчанию версия ФФД - 1.05.
    ClientInfo Object Нет* Информация по покупателю
    Taxation Enum Да Система налогообложения. Перечисление с возможными значениями:
    - osn - общая СН;
    - usn_income - упрощенная СН;
    - usn_income_outcome - упрощенная СН (доходы минус расходы);
    - envd - единый налог на вмененный доход;
    - esn - единый сельскохозяйственный налог;
    - patent - патентная СН;
    Email String Нет** Электронная почта для отправки чека
    Phone String Нет** Телефон для отправки чека
    Customer String Нет Идентификатор/Имя покупателя
    CustomerInn String Нет ИНН покупателя
    Items Array of objects Да Массив, содержащий в себе информацию о товарах
    Payments Object Нет*** Объект c информацией о видах суммы платежа. См. Структура объекта Payments
    OperatingСheckProps Object Нет Операционный реквизит чека (тег 1270)
    SectoralCheckProps Object Нет Отраслевой реквизит чека (тег 1261)
    AddUserProp Object Нет Дополнительный реквизит пользователя (тег 1084)
    AdditionalCheckProps String Нет Дополнительный реквизит чека (БСО) (тег 1192)

    *Обязателен для товаров с маркировкой
    **Должен быть заполнен параметр или Phone, или E-mail
    ***Если объект не передан, будет автоматически указана итоговая сумма чека с видом оплаты "Безналичный"
    Если передан объект receipt.Payments, то значение в Electronic должно быть равно итоговому значению Amount в методе Init. При этом сумма введенных значений по всем видам оплат, включая Electronic, должна быть равна сумме (Amount) всех товаров, переданных в объекте receipt.Items.

    Структура объекта ClientInfo

    Параметр Тип Обязательность Описание
    Birthdate String Нет Дата рождения покупателя в формате ДД.ММ.ГГГГ
    Citizenship String Нет Числовой код страны, гражданином которой является покупатель. Код страны указывается в соответствии с Общероссийским классификатором стран мира ОКСМ
    DocumentСode String Нет Числовой код вида документа, удостоверяющего личность.
    Может принимать только значения:
    • 21 - Паспорт гражданина Российской Федерации
    • 22 - Паспорт гражданина Российской Федерации, дипломатический паспорт, служебный паспорт, удостоверяющие личность гражданина Российской Федерации за пределами Российской Федерации
    • 26 - Временное удостоверение личности гражданина Российской Федерации, выдаваемое на период оформления паспорта гражданина Российской Федерации
    • 27 - Свидетельство о рождении гражданина Российской Федерации (для граждан Российской Федерации в возрасте до 14 лет)
    • 28 - Иные документы, признаваемые документами, удостоверяющими личность гражданина Российской Федерации в соответствии с законодательством Российской Федерации
    • 31 - Паспорт иностранного гражданина
    • 32 - Иные документы, признаваемые документами, удостоверяющими личность иностранного гражданина в соответствии с законодательством Российской Федерации и международным договором Российской Федерации
    • 33 - Документ, выданный иностранным государством и признаваемый в соответствии с международным договором Российской Федерации в качестве документа, удостоверяющего личность лица безгражданства.
    • 34 - Вид на жительство (для лиц без гражданства)
    • 35 - Разрешение на временное проживание (для лиц без гражданства)
    • 36 - Свидетельство о рассмотрении ходатайства о признании лица без гражданства беженцем на территории Российской Федерации по существу
    • 37 - Удостоверение беженца
    • 38 - Иные документы, признаваемые документами, удостоверяющими личность лиц без гражданства в соответствии с законодательством Российской Федерации и международным договором Российской Федерации
    • 40 - Документ, удостоверяющий личность лица, не имеющего действительного документа, удостоверяющего личность, на период рассмотрения заявления о признании гражданином Российской Федерации или о приеме в гражданство Российской Федерации
    DocumentData String Нет Реквизиты документа, удостоверяющего личность (например: серия и номер паспорта)
    Address String Нет Адрес покупателя (клиента), грузополучателя. Максимум 256 символов

    Структура объекта OperatingСheckProps

    Параметр Тип Обязательность Описание
    Name String Да Идентификатор операции (тег 1271)
    Принимает значения «0» до определения значения реквизита ФНС России.
    Value String Да Данные операции (тег 1272)
    Timestamp String Да Дата и время операции в формате ДД.ММ.ГГГГ ЧЧ:ММ:СС (тег 1273)

    Структура объекта SectoralCheckProps

    Параметр Тип Обязательность Описание
    FederalId String Да Идентификатор ФОИВ (тег 1262). Максимальное количество символов – 3
    Date String Да Дата документа основания в формате ДД.ММ.ГГГГ (тег 1263)
    Number String Да Номер документа основания (тег 1264)
    Value String Да Значение отраслевого реквизита (тег 1265)

    Структура объекта AddUserProp

    Параметр Тип Обязательность Описание
    Name String Да Наименование дополнительного реквизита пользователя (тег 1085)
    Value String Да Значение дополнительного реквизита пользователя (тег1086)

    Структура объекта Items

    Параметр Тип Обязательность Описание
    Name String Да Наименование товара
    Максимум 128 символов
    Price Number Да Цена в копейках
    Quantity Number Да Количество/вес:
    - целая часть не более 5 знаков;
    - дробная часть не более 3 знаков для Атол, не более 2 знаков для CloudPayments
    Значение «1», если передан объект markCode
    Amount Number Да Сумма в копейках. Целочисленное значение не более 10 знаков
    PaymentMethod Enum Да Признак способа расчёта. Если значение не передано, по умолчанию в онлайн-кассу передается признак способа расчёта "full_payment". Возможные значения:
    − «full_prepayment» – предоплата 100%.
    − «prepayment» – предоплата.
    − «advance» – аванс.
    − «full_payment» – полный расчет.
    − «partial_payment» – частичный расчет и
    кредит.
    − «credit» – передача в кредит.
    − «credit_payment» – оплата кредита.
    PaymentObject Enum Да Признак предмета расчёта.Если значение не передано, по умолчанию в онлайн-кассу отправляется признак предмета расчёта "commodity".
    Возможные значения:
    − «commodity» – товар.
    − «excise» – подакцизный товар.
    − «job» – работа.
    − «service» – услуга.
    − «gambling_bet» – ставка азартной игры.
    − «gambling_prize» – выигрыш азартной игры.
    − «lottery» – лотерейный билет.
    − «lottery_prize» – выигрыш лотереи.
    − «intellectual_activity» – предоставление результатов интеллектуальной деятельности.
    − «payment» – платеж.
    − «agent_commission» – агентское вознаграждение.
    − «composite» – составной предмет расчета.
    − «another» – иной предмет расчета
    UserData String Нет Дополнительный реквизит предмета расчета
    Excise Number Нет Сумма акциза в рублях с учетом копеек, включенная в стоимость предмета расчета.
    Целая часть не более 8 знаков
    Дробная часть не более 2 знаков
    Значение не может быть отрицательным
    CountryCode String Нет Цифровой код страны происхождения товара в соответствии с Общероссийским классификатором стран мира (3 цифры)
    DeclarationNumber String Нет Номер таможенной декларации (32 цифры максимум)
    MeasurementUnit String Да Единицы измерения. Передовать в соответствии с ОК 015-94 (МК 002-97)
    Возможные варианты указаны в статье (также возможна передача произвольных значений)
    MeasurementUnit обязателен, в случае если ФФД онлайн-кассы 1.2.
    MarkProcessingMode String Нет* Режим обработки кода маркировки. Должен принимать значение равное «0»
    MarkCode Object Нет* Код маркировки в машиночитаемой форме, представленный в виде одного из видов кодов, формируемых в соответствии с требованиями, предусмотренными правилами, для нанесения на потребительскую упаковку, или на товары, или на товарный ярлык. Параметры объекта описаны в таблице Структура объекта MarkCode
    MarkQuantity Object Нет** Реквизит «дробное количество маркированного товара». MarkQuantity не является обязательным объектом, в том числе для товаров с маркировкой. Этот объект МОЖНО передавать, если товар с маркировкой. Т.е. даже при ФФД 1.2 этот объект не является обязательным
    SectoralItemProps Array of objects Нет*** Отраслевой реквизит предмета расчета. Параметры объекта описаны в таблице Структура объекта SectoralItemProps
    Tax Enum Да Ставка налога. Перечисление со значениями:
    - none - без НДС;
    - vat0 - НДС по ставке 0%;
    - vat10 - НДС чека по ставке 10%;
    - vat20 - НДС чека по ставке 20%;
    - vat110 - НДС чека по расчетной ставке 10/110;
    - vat120 - НДС чека по расчетной ставке 20/120.
    AgentData Object Да, если используется агентская схема Данные агента. Параметры объекта описаны в таблице Структура объекта AgentData
    SupplierInfo Object Да, если передается значение AgentSign в объекте AgentData Данные поставщика платежного агента. Параметры объекта описаны в таблице Структура объекта AgentData

    *Включается в чек в случае, если предметом расчета является товар, подлежащий обязательной маркировке средством идентификации (соответствующий код в поле paymentObject).
    **Передается только в случае, если расчет осуществляется за маркированный товар (соответствующий код в поле paymentObject) и значение в поле measurementUnit равно «0»
    Состоит из двух параметров, где
    • Numerator – Числитель дробной части предмета расчета. Значение должно быть строго меньше значения реквизита «знаменатель».
    • Denominator - Знаменатель дробной части предмета расчета. Значение равно количеству товара в партии (упаковке), имеющей общий код маркировки товара.
    Пример:

    {
    "numerator": "1",
    "denominator": "2"
    }
    

    ***Необходимо указывать только для товаров подлежащих обязательной маркировке средством идентификации и включение данного реквизита предусмотрено НПА отраслевого регулирования для соответствующей товарной группы

    Структура объекта MarkCode

    Параметр Тип Обязательность Описание
    MarkCodeType String Да Тип штрих кода. Возможные значения:
    • UNKNOWN - код товара, формат которого не идентифицирован, как один из реквизитов
    • EAN8 - код товара в формате EAN-8
    • EAN13 - код товара в формате EAN-13
    • ITF14 - код товара в формате ITF-14
    • GS10 - код товара в формате GS1, нанесенный на товар, не подлежащий маркировке
    • GS1M - код товара в формате GS1, нанесенный на товар, подлежащий маркировке
    • SHORT - код товара в формате короткого кода маркировки, нанесенный на товар
    • FUR - контрольно-идентификационный знак мехового изделия
    • EGAIS20 - код товара в формате ЕГАИС-2.0
    • EGAIS30 - код товара в формате ЕГАИС-3.0
    • RAWCODE - Код маркировки, как он был прочитан сканером.
    value String Да Код маркировки

    Структура объекта SectoralItemProps

    Параметр Тип Обязательность Описание
    FederalId Enum (string) Да Идентификатор ФОИВ (федеральный орган исполнительной власти)
    Date String Да Дата нормативного акта ФОИВ
    Number String Да Номер нормативного акта ФОИВ
    Value String Да Состав значений, определенных нормативного актом ФОИВ

    Пример запроса с маркировкой:

    {
        "TerminalKey": "testRegressTwoFiscalAtolBank",
        "Amount": 90000,
        "OrderId": "{{$timestamp}}",
        "Description": "RS_TESTING",
        "CustomerKey": "a.grigorash",
        "Receipt": {
            "FfdVersion": "1.2",
            "ClientInfo": {
                "Birthdate": "21.11.1995",
                "Сitizenship": "643",
                "DocumentCode": "40",
                "DocumentData": "4507 443564",
                "Address": "г. Краснодар ул. Привокзальная 1"
            },
            "Taxation": "osn",
            "Email": "ext.test.qa@tinkoff.ru",
            "Phone": "88005553535",
            "Customer": "Клиент",
            "CustomerInn": "516974792202",
            "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": "Тестовый товар",
                    "Price": 100000,
                    "Quantity": 1,
                    "Amount": 90000,
                    "Tax": "vat20",
                    "PaymentMethod": "full_prepayment",
                    "PaymentObject": "goods_with_marking_code",
                    "UserData": "Данные пользователя ext.test.qa@tinkoff.ru",
                    "Excise": 12.2,
                    "CountryCode": "056",
                    "DeclarationNumber": "12345678901",
                    "MeasurementUnit": "шт",
                    "MarkProcessingMode": "0",
                    "MarkCode": {
                        "MarkCodeType": "EAN8",
                        "Value": "12345678"
                    },
                    "MarkQuantity": {
                        "Denominator": "2",
                        "Numerator": "1"
                    },
                    "SectoralItemProps": [
                        {
                            "Number": "123/43",
                            "Date": "21.11.2020",
                            "Value": "test value SectoralItemProps",
                            "FederalId": "001"
                        }
                    ]
                }
            ]
        }
    }
    

    Пример запроса без маркировки:

    {
        "TerminalKey": "testRegressTwoFiscalAtolBank",
        "Amount": 90000,
        "OrderId": "{{$timestamp}}",
        "Description": "RS_TESTING",
        "CustomerKey": "a.grigorash",
        "Receipt": {
            "FfdVersion": "1.2",
            "Taxation": "osn",
            "Email": "ext.test.qa@tinkoff.ru",
            "Phone": "88005553535",
            "Customer": "Клиент",
            "CustomerInn": "516974792202",
            "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": "Тестовый товар",
                    "Price": 100000,
                    "Quantity": 1,
                    "Amount": 90000,
                    "Tax": "vat20",
                    "PaymentMethod": "full_prepayment",
                    "PaymentObject": "commodity",
                    "MeasurementUnit": "шт"
                     
                }
            ]
        }
    }
    

    Коды ошибок

    CODE MESSAGE DETAILS (опционально)
    0 None
    1 Параметры не сопоставлены
    2 Отсутствуют обязательные параметры
    3 Внутренняя ошибка системы интернет эквайринга
    4 Не получится изменить статус платежа
    5 Обратитесь в поддержку, чтобы уточнить детали
    6 Не получилось привязать карту покупателя. Обратитесь в поддержку, чтобы уточнить детали
    7 Неверный статус покупателя
    8 Неверный статус транзакции
    9 Переадресовываемый url пуст
    10 Метод Charge заблокирован для данного терминала
    11 Невозможно выполнить платеж
    12 Неверный параметр RedirectDueDate
    13 Оплата с мобильного телефона недоступна
    13 Оплата через WebMoney недоступна
    14 Платеж неверный.
    15 Не удалось осуществить платеж через EINV.
    16 Счет был отклонен.
    17 Неверные введенные данные.
    18 Не удалось осуществить платеж через MC.
    19 Не удалось осуществить платеж через WebMoney.
    20 Ошибка повторного идентификатора заказа.
    21 Внутренняя ошибка вызова сервиса ACQAPI.
    27 Кассовая ссылка на текущий момент недоступна для повторной активации
    50 Ошибка отправки нотификации.
    51 Ошибка отправки Email.
    52 Ошибка отправки Sms.
    53 Обратитесь к продавцу
    54 Повторное прохождение 3DS авторизации не допустимо.
    55 Повторите попытку позже Не найдено оплаченных назначений платежа
    60 Запрещено получение документов по url для текущего терминала Запрещено получение документов по url для текущего терминала
    61 Должен быть заполнен один из параметров: emailList или Url Должен быть заполнен один из параметров: emailList или Url
    62 Запрещено получение документов по url для текущего systemId Запрещено получение документов по url для текущего systemId
    63 Не найдена операция Не найдена операция
    64 Невалидные данные в запросе Невалидные данные в запросе
    65 Не удалось сформировать документ. Обратитесь в службу поддержки Не удалось сформировать документ. Повторите операцию позднее
    66 Не удалось сформировать документ. Повторите операцию позднее Запрещено получение документов по url для текущего терминала
    67 Не удалось сформировать документ. Повторите операцию позднее Не удалось сформировать документ. Повторите операцию позднее
    68 Не удалось сформировать документ. Обратитесь в службу поддержки Стороний сервис не доступен.
    76 Операция по иностранной карте недоступна. Операция по иностранной карте недоступна. Воспользуйтесь картой российского банка
    77 Оплата иностранной картой недоступна. Оплата по иностранной карте недоступна. Воспользуйтесь картой российского банка
    78 Выплата на иностранную карту недоступна. Выплата на иностранную карту недоступна. Воспользуйтесь картой российского банка
    79 Возврат на иностранную карту недоступен. Возврат на иностранную карту недоступен. Обратитесь в поддержку
    96 Ошибка Iris.
    97 Ошибка Jasper.
    98 Ошибка SubExt.
    99 Попробуйте повторить попытку позже Банк, выпустивший карту, отклонил операцию
    100 • Попробуйте еще раз. Если ошибка повторится — обратитесь в поддержку
    • Платеж не получится отменить, потому что деньги покупателя не были зарезервированы
    • Платеж уже отменен
    • Не получилось отменить платеж. Укажите сумму не больше, чем зарезервировано
    • Покупатель опротестовал платеж в банке. Обратитесь в поддержку,чтобы уточнить детали
    • Платеж уже подтвержден
    • Нужно настроить подтверждение платежа через СМС (3DS) — для этого обратитесь в поддержку
    • Карта покупателя неактивна
    101 Не пройдена идентификация 3DS. Ошибка прохождения 3-D Secure
    102 • Обратитесь в поддержку, чтобы уточнить детали
    • Сообщите покупателю, чтобы попробовал оплатить еще раз. Если ошибка повторится — обратитесь в поддержку
    102 Операция отклонена, пожалуйста обратитесь в интернет-магазин или воспользуйтесь другой картой. Заказ не может быть оплачен, обратитесь службу поддержки
    102 Превышен лимит на сумму выплат в месяц.
    102 Отказ. Более двух успешных оплат с одного email в неделю по проекту dolyame.ru
    102 Отказ. Более двух успешных оплат с одного phone в неделю по проекту dolyame.ru.
    102 Отказ. Более двух успешных оплат с одной карты в неделю по проекту dolyame.ru.
    102 Отказ. Более двух успешных оплат с одной карты в сутки по проекту dolyame.ru.
    102 Отказ. Более двух успешных оплат с одного устройства в сутки по проекту dolyame.ru.
    102 Отказ. Более двух успешных оплат с одного устройства в неделю по проекту dolyame.ru.
    102 Отказ. Более двух успешных оплат с одного куки/идентификатора клиентского агента в сутки по проекту dolyame.ru.
    102 Отказ. Более двух успешных оплат с одного куки/идентификатора клиентского агента в неделю по проекту dolyame.ru.
    102 Отказ. Попытка оплаты с виртуальных или мошеннических бинов по проекту dolyame.ru.
    103 Недостаточно средств на счете
    104 Ошибка выполения рекуррента
    105 Нужно настроить автоплатежи по Maestro — для этого обратитесь в поддержку
    106 Карта не поддерживает 3DS проверку. Попробуйте другую карту.
    107 Неверно введен CardId. Проверьте, что такая карта была ранее привязана.
    108 Оплата разрешена только по 3DS картам. Попробуйте другую карту.
    109 Не найден dsTranId для сессии
    110 Не передан cres
    111 Передан некорректный cres
    116 Недостаточно средств на карте.
    119 Превышено допустимое количество запросов авторизации операции
    120 Попробуйте повторить попытку позже
    123 Попробуйте повторить попытку позже
    125 Попробуйте повторить попытку позже
    191 Некорректный статус договора, обратитесь к вашему менеджеру
    201 Поле PaymentId не должно быть пустым.
    201 Поле paymentMethod не должно быть пустым.
    201 Поле paymentObject не должно быть пустым.
    201 Поле measurementUnit не должно быть пустым.
    202 Терминал заблокирован.
    203 Параметры запроса не должны быть пустыми.
    204 Неверный токен. Проверьте пару TerminalKey/SecretKey.
    205 Неверный токен. Проверьте пару TerminalKey/SecretKey. Указанный терминал не найден
    206 Email не может быть пустым.
    207 Параметр DATA превышает максимально допустимый размер.
    208 Наименование ключа из параметра DATA превышает максимально допустимый размер.
    209 Значение ключа из параметра DATA превышает максимально допустимый размер.
    210 Размер поля TerminalKey должен быть от {min} до {max}.
    211 Неверный формат IP.
    212 Размер поля OrderId должен быть от {min} до {max}.
    213 Размер поля Description должен быть от {min} до {max}.
    214 Поле Currency должно быть меньше или равно {value}.
    215 Размер поля PayForm должен быть от {min} до {max}.
    216 Размер поля CustomerKey должен быть от {min} до {max}.
    217 Поле PaymentId числовое значение должно укладываться в формат (<{integer} цифр>.<{fraction} цифр>).
    218 Значение PAN не является числовым.
    219 Неверный срок действия карты.
    220 Размер поля CardHolder должен быть от {min} до {max}.
    221 Значение CVV не является числовым.
    222 Поле CardId числовое значение должно укладываться в формат (<{integer} цифр>.<{fraction} цифр>).
    223 Поле RebillId числовое значение должно укладываться в формат (<{integer} цифр>.<{fraction} цифр>).
    224 Неверный формат Email.
    225 Неверный формат Email.
    226 Размер поля Email должен быть от {min} до {max}.
    227 Размер поля Phone должен быть от {min} до {max}.
    228 Размер поля MD должен быть от {min} до {max}.
    229 Размер поля PaRes должен быть от {min} до {max}.
    230 Размер поля Code должен быть от {min} до {max}.
    231 Не найден идентификатор карты.
    233 Размер поля CardId должен быть от {min} до {max}.
    234 Размер поля PAN должен быть от {min} до {max}.
    235 Размер поля RebillId должен быть от {min} до {max}.
    236 Размер поля Token должен быть от {min} до {max}.
    237 Размер поля PaymentId должен быть от {min} до {max}.
    238 Размер поля ExpDate должен быть от {min} до {max}.
    239 Размер поля CVV должен быть от {min} до {max}.
    240 Поле Amount числовое значение должно укладываться в формат (<{integer} цифр>.<{fraction} цифр>).
    241 Поле Currency должно быть больше или равно {value}.
    242 Размер поля InfoEmail должен быть от {min} до {max}.
    243 Ошибка шифрования карточных данных.
    244 Ошибка сопоставления карточных данных.
    245 Параметр AddCard не сопоставлен.
    246 Параметр SendEmail не сопоставлен.
    247 Параметр Amount не сопоставлен.
    248 Параметр CVV не сопоставлен.
    249 Параметр Currency не сопоставлен.
    250 Параметр DATA не сопоставлен.
    251 Неверная сумма. Сумма должна быть больше или равна {value} копеек.
    252 Срок действия карты истек.
    253 Валюта {value} не разрешена для данного терминала
    254 Дополнительные возможности отключены
    255 Платеж не найден
    256 Указан некорректный тип безопасной сделки Указан некорректный тип безопасной сделки
    257 Некорректное значение признака последней выплаты. Используйте значения true или false Некорректное значение признака последней выплаты. Используйте значения true или false
    258 Неверный параметр Ean13.
    259 Параметр EncryptedPaymentData не сопоставлен
    260 Максимальная длина номера телефона 30 символов
    261 Параметр Source не сопоставлен
    262 Истек срок действия родительского платежа
    308 Сумма всех позиций в чеке должна равняться сумме всех видов оплаты
    309 Поле Receipt не должно быть пустым.
    310 Дробная часть параметра Quantity не должна быть более {value} знаков
    310 Целая часть параметра Quantity не должна быть более {value} знаков
    311 Ошибка регистрации чека в Receipt Service.
    312 Ошибка получения чека из Receipt Service.
    313 Ошибка создания организации в Receipt Service.
    314 Ошибка создания кассы в Receipt Service.
    315 Касса не найдена.
    316 Максимальная длина номера телефона 19 символов.
    317 Неверное значение поля agentSign.
    318 Поле AgentSign не должно быть пустым.
    319 Поле SupplierInfo не должно быть пустым.
    320 Поле Inn в объекте SupplierInfo не должно быть пустым.
    321 Поле Receipts не должно быть пустым.
    322 Передана некорректная подпись
    323 Amount не совпадают
    324 Указанный тип отмены не может быть выполнен по операции
    325 Транзакция не найдена.
    326 Неверный amount.
    327 "Терминал не поддерживает C2C переводы или не передан Route=""C2C"" для C2C терминала"
    328 Должны присутствовать данные для списания и данные для пополнения.
    329 Email или Phone обязательны при передаче чека
    330 Сумма в запросе больше чем в оригинальной транзакции
    331 Неверный терминал
    332 Поле Fee в объекте Shops должно быть больше или равно 0
    333 Поле Amount в объекте Shops должно быть больше или равно 1
    334 Суммы в чеке и в платеже не совпадают.
    335 OrderId {value} не найден для TerminalKey {value}
    381 Возможна привязка только резидентных карт
    382 Возможна привязка только нерезидентных карт
    383 Поле markProcessingMode должно быть заполнено для маркированных товаров
    383 Поле markCode должно быть заполнено для маркированных товаров
    383 Поле sectoralItemProps должно быть заполнено для маркированных товаров
    383 Поле markQuantity должно быть заполнено для маркированных товаров
    383 Поле {value} для маркированных товаров должно принимать значение: {value}
    383 markCode.value имеет некорректное значение
    383 numerator и denominator должны быть больше 0
    383 numerator должен быть строго меньше denominator
    383 Для версии кассы ФФД 1.2 объекты AgentData и SupplierInfo должны быть переданы в Items
    384 Для C2C запрещено проводить рекуррент по данной ПС Для C2C запрещено проводить рекуррент по данной ПС
    385 Поле markQuantity передается только для маркированных товаров
    385 Поле markProcessingMode передается только для маркированных товаров
    386 markQuantity заполняется только для дробного расчета за штучный маркированный товар
    401 Внутренняя ошибка системы.
    402 Повторите попытку позже.
    403 Превышен лимит на количество пополнений в месяц.
    404 Превышен лимит на сумму пополнения через бесконтактные сервисы.
    405 Превышен лимит на сумму пополнения по виртуальной карте.
    406 Превышен лимит на сумму пополнения в месяц через мобильное приложение.
    407 Не найдено
    410 Данный тип перевода для терминала не доступен
    411 Сертификат не найден
    412 Истек срок действия сертификата
    413 Сертификат заблокирован
    414 Сертификат уже сохранен для данного терминала
    415 Дата начала срока действия сертификата еще не наступила
    416 Некорректное значение параметра SetStatus
    417 Ошибка обработки сертификата
    419 Параметр account объекта DATA должен быть заполнен корректно для MCC: 6050/6051
    500 Добавление карты к данному терминалу запрещено.
    501 Терминал не найден.
    502 Карта по requestKey не найдена.
    503 CustomerKey не найден.
    504 Не удалось провести платеж при привязке карты.
    505 Не удалось привязать карту. Внутренняя ошибка.
    506 Карта добавлена в черный список.
    507 Карта не поддерживает 3DS проверку. Попробуйте другую карту.
    508 Неверный номер карты.
    509 Не удалось выполнить отмену при привязке карты.
    510 Карта уже привязана к переданному CustomerKey.
    511 Проверка 3DS не пройдена.
    512 Не удалось выполнить запрос на проверку 3DS.
    513 Не удалось выполнить платеж после прохождения 3DS.
    514 Введена неверная сумма холдирования.
    515 Внутренняя ошибка.
    600 Карта добавлена в черный список
    600 Интернет-магазин отклонил операцию по данной карте. Обратитесь в интернет-магазин для выяснения причин отказа в платеже.
    601 Разрешены операции только по MasterCard
    603 Превышено количество попыток оплаты с данной карты
    604 Обратитесь в поддержку, чтобы уточнить детали
    619 Отсутствуют обязательные данные отправителя Не переданы персональные данные отправителя для операции emoney2card более 15000 руб.
    620 Проверьте сумму — она не может быть равна 0 Сумма операции не может быть равна 0
    623 Выплата по этому заказу уже прошла Запрещено проводить платеж с OrderId для которого уже есть успешный платеж.
    632 Превышен лимит на сумму операции Лимит на сумму пополнения emoney2card. См. лимиты
    633 Превышен лимит на количество переводов в день по иностранным картам Лимит на кол-во пополнений emoney2card для карт эмитированных нерезидентами РФ за 1 отчетный день
    634 Превышен лимит на сумму переводов по номеру карты в месяц Лимит на сумму пополнения emoney2card по номеру карты одного получателя в отчетный месяц
    637 Не хватает данных получателя или отправителя для выплаты на иностранную карту. Проверьте заполнение Отсутствуют персональные данные получателя/отправителя при переводе на иностранную карту
    642 Проверьте номер карты Карта не прошла проверку по алгоритму Луна
    648 Магазин заблокирован или еще не активирован. Обратитесь в поддержку, чтобы уточнить детали
    650 Сообщите покупателю, чтобы попробовал оплатить еще раз. Если ошибка повторится — обратитесь в поддержку
    651 Не получилось совершить платеж. Свяжитесь с поддержкой Передаваемый Request_Id не найден.
    700 Список карт Masterpass недоступен для данного магазина.
    701 Сервис MasterPass недоступен.
    702 Поле maid и saav должно быть задано в настройках терминала.
    703 Обратитесь в поддержку, чтобы уточнить детали
    800 Комиссия не найдена
    903 Повторите попытку позже
    914 Платеж не найден
    926 Сделка уже закрыта Сделка уже закрыта
    927 Сделка не найдена Сделка не найдена
    991 Для использования 3dsType необходимо установить 3ds терминал Для использования TDS роутинга необходимо пользоваться ТДС терминалом
    999 Попробуйте повторить попытку позже
    1001 Свяжитесь с банком Свяжитесь с банком, выпустившим карту, чтобы провести платеж
    1003 Неверный магазин Неверный номер магазина. Идентификатор магазина недействителен.
    1004 Банк, который выпустил карту, считает платеж подозрительным
    1005 Платеж отклонен банком, выпустившим карту Платеж отклонен банком, выпустившим карту
    1006 Платеж не прошел Свяжитесь с банком, выпустившим карту, чтобы провести платеж
    1007 Банк, который выпустил карту, считает платеж подозрительным
    1008 Банк, который выпустил карту, отклонил платеж
    1012 Банк, который выпустил карту, отклонил платеж
    1013 Банк, который выпустил карту, отклонил платеж — сумма превышает лимит по карте Сумма превышает лимит платежа вашего банка. Воспользуйтесь другой картой или обратитесь в банк
    1014 Карта недействительна Неправильные реквизиты — проверьте их или воспользуйтесь другой картой
    1015 Неверный номер карты Неверный номер карты
    1017 Попробуйте снова или свяжитесь с банком, выпустившим карту Попробуйте снова или свяжитесь с банком, выпустившим карту
    1018 Неизвестный статус платежа
    1019 Банк, который выпустил карту, отклонил платеж — сумма превышает лимит по карте
    1030 Повторите попытку позже. Не получилось оплатить. Попробуйте еще раз
    1033 Истек срок действия карты
    1034 Попробуйте повторить попытку позже Не получилось оплатить. Воспользуйтесь другой картой или обратитесь в банк, выпустивший карту
    1038 Превышено количество попыток ввода ПИН-кода — попробуйте снова или обратитесь в банк, выпустивший карту
    1039 Платеж отклонен — счет не найден
    1041 Карта утеряна Карта утеряна. Свяжитесь с банком, выпустившим карту
    1043 Банк, который выпустил карту, считает платеж подозрительным
    1051 Недостаточно средств на карте. Не получилось оплатить. На карте недостаточно средств
    1053 Платеж отклонен — счет не найден
    1054 Истек срок действия карты Неправильные реквизиты — проверьте их или воспользуйтесь другой картой
    1055 Неверный ПИН
    1057 Покупатель запретил такие операции для своей карты
    1058 Покупатель запретил такие операции для своей карты
    1059 Банк, который выпустил карту, считает платеж подозрительным
    1061 Покупатель превысил лимит платежей по своей карте
    1062 Банк, который выпустил карту, отклонил платеж
    1063 Банк, который выпустил карту, считает платеж подозрительным
    1064 Проверьте сумму
    1065 Покупатель превысил лимит платежей по своей карте
    1071 Токен просрочен Токен просрочен
    1075 Покупатель оплатил максимум раз по своей карте за день
    1076 Не получилось отменить резервирование. Обратитесь в поддержку, чтобы уточнить детали
    1077 Коды не совпадают — попробуйте снова
    1078 Данный тип операции не поддерживается картой
    1080 Плательщик ввел неверный срок действия карты
    1082 Неверный CVV Неправильные реквизиты — проверьте их или воспользуйтесь другой картой
    1085 Операция успешна Успех
    1086 Платеж отклонен — не получилось подтвердить ПИН-код
    1088 Банк, который выпустил карту, отклонил платеж
    1089 Попробуйте повторить попытку позже Не получилось оплатить. Попробуйте еще раз или обратитесь в банк, выпустивший карту
    1091 Технические работы в банке, который выпустил карту
    1092 Банк, который выпустил карту, отклонил платеж
    1093 Банк, который выпустил карту, считает платеж подозрительным
    1094 Банк, который выпустил карту, считает платеж подозрительным
    1096 Системная ошибка Системная ошибка
    1099 Способ оплаты отключен
    1116 Некорректная сумма выдачи Сумма баланса меньше суммы переданной в операции выдачи
    1119 Параметр account объекта DATA должен быть заполнен корректно для MCC: 6050/6051 Передан некорректный номер кошелька
    1125 Некорректное значение OperationInitiatorType. Должно быть одно из списка
    1126 Несопоставимые значения rebillId или Recurrent с переданным значением OperationInitiatorType
    1201 Обратитесь в поддержку, чтобы уточнить детали
    1202 Сумма платежа превышает лимит по разовой операции в этом магазине. Обратитесь в поддержку, чтобы уточнить детали
    1203 Сумма платежа превышает лимит по разовой операции или количеству операций в этом магазине. Обратитесь в поддержку, чтобы уточнить детали
    1204 Достигнут лимит по суточному обороту. Чтобы изменить лимит, обратитесь в поддержку
    1205 Магазин не принимает карты этой страны. Обратитесь в поддержку, чтобы уточнить детали
    1207 Сообщите покупателю, чтобы попробовал оплатить еще раз. Если ошибка повторится — обратитесь в поддержку
    1217 Воспользуйтесь другой картой или обратитесь к продавцу Воспользуйтесь другой картой или обратитесь к продавцу
    1218 Воспользуйтесь другой картой или обратитесь к продавцу Воспользуйтесь другой картой или обратитесь к продавцу
    1235 Для карт «Мир» нужно настроить подтверждение платежей по СМС 3DS 2.0. Обратитесь в поддержку, чтобы уточнить детали
    1316 Запрещено проведение авторизации Запрещено проведение авторизации с использованием 3DS
    1502 Недостаточно средств на счете компании Insufficient funds
    1503 Некорректный статус счета, обратитесь в поддержку Invalid account status
    2014 Не пройдена идентификация 3DS
    2015 Mерчант с таким именем и паролем не найден.
    2200 Превышено допустимое количество запросов авторизации операции
    3001 Оплата через QrPay недоступна
    3002 Недостаточный баланс счёта для отмены.
    3003 Отмена платежа в связи с мошенничеством.
    3004 Способ СБП недоступен для магазина.
    3005 Оплата через СБП не доступна
    3006 Банк получателя не может принять возврат. Выберите другой банк.
    3007 Отказ в проведении операции от СБП.
    3008 У получателя нет расчетного счета в этом банке. Выберите другой банк.
    3009 Отказ в проведении операции от СБП или банка получателя.
    3010 У получателя нет расчетного счета в этом банке. ФИО некорректное.
    3011 Оплата через E2C недоступна
    3012 Привязка счета не найдена
    3013 Рекуррентные платежи недоступны
    3014 AccountToken не найден
    3015 Неверный статус AccountToken
    3016 Невозможно создать QR
    3017 Переданное значение RedirectDueDate вне допустимого диапазона.
    3018 Список банков не найден.
    3019 Не включен СБП в личном кабинете
    3028 Банк покупателя отклонил возврат. Попросите покупателя обратиться туда или выберите другой его банк
    3029 Слишком много неудачных попыток за час. Попробуйте снова через час или выберите другой банк покупателя По требованиям НСПК в час допустимо проводить не более 1 попытки возврата по операции
    3030 Слишком много неудачных попыток за сутки. Попробуйте еще раз завтра или выберите другой банк покупателя По требованиям НСПК в день допустимо проводить не более 5 попыток возврата по операции
    3031 Банк покупателя отклонил возврат. Попросите покупателя обратиться туда или выберите другой его банк
    3101 Оплата по MirPay недоступна для магазина
    3102 DeepLink для оплаты по MirPay не создан
    8001 Операция запрещена для рассрочки
    8002 Tinkoff Credit Broker недоступен. Повторите попытку позже.
    8003 Операция запрещена для покупки долями.
    8004 BNPL недоступен. Повторите попытку позже.
    9001 Попробуйте повторить попытку позже
    9999 Внутренняя ошибка системы.
    - Количество товара должно быть больше нуля
    - Максимальная длина rawcode 223 символов
    - Касса принимает значение markCode только с типом rawcode
    - Для данной кассы ожидалось одно из itemCode или markСode
    - Для данной кассы ожидалось либо itemCode, либо markCode
    - Для данной кассы предусмотрена передача только markСode

    Тестовые карты

    Вы можете использовать любой срок действия для тестовой карты. Можно произвести несколько тестовых привязок с разными сроками действия и потом с помощью метода GetCardList посмотреть, какие карты привязаны. Тестовые карты используются при проведении операций на тестовой среде

    Описание параметра TransStatus находится в описании параметров ответа cres (JSON/JWE cres объект)

    Список тестовых карт для оплаты через протокол 3ds2.0

    Поведение карты TransStatus Описание PAN
    Ошибка оплаты
    Ошибка при списании
    Нет - 2201382000000021
    expDate: 12/25
    cvv: 123
    Ошибка оплаты
    Недостаточно средств
    Нет - 2201382000000831
    expDate: 12/25
    cvv: 123
    Успешная оплата
    3ds 2.0
    Frictionless Flow
    Нет AUTHENTICATION_SUCCESSFUL
    Успешное прохождение аутентификации без ввода пароля
    2201382000000013
    expDate: 12/25
    cvv: 123
    Успешная оплата
    3ds 2.0
    Challenge flow
    C CHALLENGE_REQURIED
    Требуется полное прохождение 3DS с редиректом на acsURL. Открытие формы для ввода одноразового пароля (OTP)
    2201382000000047
    expDate: 12/25
    cvv: 123
    Метод аутентификации на ACS: Static Passcode. Ввести верный пароль 1qwezxc
    Ошибка оплаты
    3ds2.0
    Restricted
    R ACCOUNT_VERIFICATION_REJECTED
    Эмитент отклонил аутентификацию
    2201382000000005
    expDate: 12/25
    cvv: 123
    Ошибка оплаты
    Frictionless Flow
    Not Authenticated
    N NOT_AUTHENTICATED
    Карта не поддерживает 3DS
    2201382000000021
    expDate: 12/25
    cvv: 123
    Успешная оплата
    Card not Enrolled (Attempt)
    A ATTEMPTS_PROCESSING_PERFORMED
    Эмитент недоступен или не поддерживает 3DS v2.1. Платежная система разрешает провести Pay, но эмитент мог отклонить авторизацию
    2201382000000039
    expDate: 12/25
    cvv: 123

    Список тестовых карт для оплаты без 3ds

    Поведение карты TransStatus Описание PAN
    Успешная оплата Нет - 2200770239097761
    expDate: 12/25
    cvv: 123

    Карты Mock-сервиса (если не работает тестовая карта)

    Поведение карты TransStatus Описание PAN
    Успешная оплата Y AUTHENTICATION_SUCCESSFUL_REASON_18
    Успешное прохождение аутентификации без ввода пароля c заполненной transStatusReason High confidence, т.е. высокая уверенность в надежности
    2201382000000591

    Правила расчета возмещений по операционному реестру

    При наличии РКО от Тинькофф Банка выплаты производятся в календарные дни. При отстутсвии – в дни работы расчетно-кассового центра по графику Центробанка.

    Возмещение считается за один календарный день.

    Тип операции Пояснение Плюс/минус
    Debit Операция оплаты Плюс
    Credit Операция возврата Минус
    Fee Комиссия по операции оплаты (в том числе неуспешной) Минус
    CancelRefund Отмена возврата Плюс
    Chargeback Опротестование операции эмитентом Минус
    2Chargeback Арбитражное опротестование эмитентом Минус
    Chargeback_Reversal Отмена опротестования операции эмитентом Плюс
    2Chargeback_Reversal Отмена арбитражного опротестования операции эмитентом Плюс
    CR_Chargeback Возврат операции Refund от эмитента (карта или договор закрыты) Плюс
    Representment Обратное опротестование Chargeback Тинькофф Плюс
    Representment_Reversal Отмена обратного опротестования 2Chargeback Тинькофф Минус
    AUTH_FAIL Неуспешная авторизация. Сама операция в расчете не участвует. Участвует только комиссия за них. -
    CreditClientCorrection FeeColl (Ручное урегулирование операции с банкомэмитентом по договоренности или при списании с Тинькофф по клирингу) Минус
    DebitClientCorrection FeeColl (Ручное урегулирование операции с банкомэмитентом по договоренности или при списании с Тинькофф по клирингу) Плюс
    CreditCorrection Списание с ТСП претензии клиента банка Тинькофф Минус
    DebitCorrection Зачисление ТСП претензии клиента банка Тинькофф Плюс

    Обратная связь

    По техническим вопросам обратитесь на почту acq_help@tinkoff.ru.
    Для предоставления обратной связи и по вопросам улучшения обслуживания и предоставляемого сервиса обратитесь к вашему личному менеджеру

    История изменений

    Описание изменений Дата
    Создан документ 26.05.2023
    В описание параметра deviceChannel для метода FinishAuthorize добавлено уточнение, что значение 02 - Browser (BRW) используется по умолчанию 16.02.2024
    Раздел "Рекомендации при интеграции" переименован в "Инструкции по безопасности при интеграции" и дополнен описанием про корректность токена и использование новейших версий CMS 19.02.2024
    Раздел "Инструкции по безопасности при интеграции" дополнен описанием про использование ПО для интеграции, полученного не с сайта https://www.tinkoff.ru/kassa/develop/ 20.02.2024