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

Merchant API

Merchant API — один из инструментов Т‑Кассы для приема переводов от физических лиц. С помощью Merchant API (далее MAPI) Мерчанты могут настроить прием переводов на своих сайтах

Инструкция по использованию MAPI написана для разработчиков и тех, кто хочет самостоятельно настроить вызов платежной формы Т‑Банка или реализовать прием погашений по API на своих ресурсах

При подключении по схеме AFT/комиссия снизу вы можете настроить прием погашений в своём мобильном приложении с помощью SDK:

• SDK Android,
• SDK IOS.

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

Тип подключения	Описание	Особенности вызова методов
Down Fee (AFT/комиссия снизу)	Тип подключения, при котором комиссия Т‑Кассы берется из возмещения Мерчанту
Side Fee (BROKER/комиссия сбоку)	Тип подключения, при котором комиссия Т‑Кассы берется из отдельного счета, а возмещения Мерчанту отправляются на специальный брокерский счет
Up Fee (ATOP/комиссия сверху)	Тип подключения, при котором возмещение Мерчанту выплачивается в полном объеме, а комиссию эквайера оплачивает клиент Мерчанта	Для мерчантов с PCI DSS после вызова метода Init необходимо вызвать метод GetFee.

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

Если у вас нет сертификации PCI DSS, вы можете использовать платежную форму Т‑Кассы. В этом случае, все операции, связанные с обработкой критичных данных производятся на стороне Т‑Кассы. Мерчанту достаточно настроить интеграцию с MerchantAPI и инициализировать перевод. Клиент будет перенаправлен на платежную форму, в которую он сможет ввести данные карты. Когда перевод завершится, клиент снова увидит сайт Мерчанта. Подключение по этому типу возможно с использованием методов, описанных в данной документации без пометки «Для Мерчантов с 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	Разрешено	Запрещено

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

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

Токен в MAPI - это строка, в которой Мерчант зашифровал данные своего запроса с помощью пароля из Личного кабинета мерчанта.

Подпись запроса формируется индивидуально для каждого запроса на основе передаваемых в нем параметров в виде пар Ключ-Значение. В формировании запроса не участвуют объекты и массивы, а также передаваемые в них параметры.

Рассмотрим на примере процесс шифрования тела запроса:

{
    "TerminalKey": "TinkoffBankTest",
    "PaymentId": "2304882",
    "Amount": 19200
}

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

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

[{"TerminalKey": "TinkoffBankTest"},{"PaymentId": "2304882"},{"Amount": "19200"}]

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

[{"TerminalKey": "TinkoffBankTest"},{"PaymentId": "2304882"},{"Amount": "19200"},{"Password": "usaf8fw8fsw21g"}]

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

[{"Amount": "19200"},{"Password": "usaf8fw8fsw21g"},{"PaymentId": "2304882"},{"TerminalKey": "TinkoffBankTest"}]

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

"19200usaf8fw8fsw21g2304882TinkoffBankTest"

5. Применить к строке хеш-функцию SHA-256

"d20308febb1c333c26d6b1e138d71d0be922475a97e69f41ee3eb0c525fa0f1c"

6. Добавить получившийся результат в значение параметра Token в тело запроса и отправить запрос

{
    "TerminalKey": "TinkoffBankTest",
    "PaymentId": "2304882",
    "Amount": 19200,
    "Token":"d20308febb1c333c26d6b1e138d71d0be922475a97e69f41ee3eb0c525fa0f1c"
}

Прием переводов осуществляется вызовом методов с передачей параметров методом POST в формате JSON. Все методы и передаваемые параметры являются чувствительными к регистру

Для POST-запроса в заголовке должен присутствовать Content Type: application/json URL: https://securepay.tinkoff.ru/v2/

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

Стандартный перевод

Инициализация перевода

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

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

В ответ MAPI создаст новый перевод в статусе NEW и вернет обратно его идентификатор в параметре PaymentId

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

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

Название параметра	Тип данных	Описание
threeDSMethodNotificationURL	string	Обратный адрес, на который будет >отправлен запрос после прохождения 3DS Method
threeDSServerTransID	string	Идентификатор транзакции из ответа метода Check3DSVersion

Браузер должен вызвать 3DS Method в скрытом iframe и передать данные в формате x-www-form-urlencoded

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

<body onload="document.form.submit()">
<form name="form" action="{ThreeDSMethodURL}" method="post" >
<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU2ZTcxMmE1LTE5MGEtNDU4OC05MWJjLWUwODYyNmU3N2M0NCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3Jlc3QtYXBpLXRlc3QudGlua29mZi5ydS92Mi9Db21wbGV0ZTNEU01ldGhvZHYyIn0">
</form>
</body>

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

{

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

}

Стандартный перевод

За проведение перевода отвечает метод — FinishAuthorize. Через него Мерчант передает в MAPI карточные данные клиента, таким образом продолжая обработку перевода

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

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

Оплата всегда проводится только по одностадийной схеме (списание автоматически подтверждается)

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

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

• CONFIRMED (при успешном сценарии),

• REJECTED (при неуспешном сценарии).

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

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

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

Завершение перевода

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

Рекуррентные переводы

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

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

Платежи в 1 клик

Опция не предусмотрена для терминалов с комиссией сверху (ATOP)

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

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

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

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

Статус	Правило перехода
NEW	MAPI получил запрос Init. После этого, он создает новый перевод в статусе NEW и возвращает обратно его идентификатор в параметре PaymentId и ссылку на платежную форму в параметре PaymentURL
FORM_SHOWED	Мерчант перенаправил клиента на страницу платежной формы PaymentURL, и страница загрузилась у клиента в браузере
AUTHORIZING	Перевод обрабатывается MAPI и платежной системой
3DS_CHECKING	Перевод проходит проверку 3D-Secure
3DS_CHECKED	Перевод успешно прошел проверку 3D-Secure
AUTHORIZED	Перевод авторизован, деньги заблокированы на карте клиента
CONFIRMING	Подтверждение перевода обрабатывается MAPI и платежной системой
CONFIRMED	Перевод подтвержден, деньги списаны с карты клиента
DEADLINE_EXPIRED	1. Клиент не завершил перевод в срок жизни ссылки на платежную форму PaymentURL. Этот срок Мерчант передает в параметре RedirectDueDate при вызове метода Init. 2. Перевод не прошел проверку 3D-Secure в срок.
REJECTED	Банк отклонил перевод
AUTH_FAIL	Перевод завершился ошибкой или не прошел проверку 3D-Secure
PAY_CHECKING	Перевод обрабатывается

Схема проведения переводов

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

* Метод Cancel может быть применен только для переводов в статусе NEW и FORM_SHOWED

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.

Схема проведения переводов

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

* Метод Cancel может быть применен только для переводов в статусе NEW и FORM_SHOWED

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

Метод Authorize

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

Метод FinishAuthorize

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нотификации — это уведомления магазину о статусе выполнения переводов

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

При совершении операций Authorize, FinishAuthorize, Confirm на адрес 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.0/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,
• 212.233.83.0/24,
• 91.194.226.181 (тестовая среда).

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

URL: Notification URL

Если вы хотите получить в нотификации информацию переданную вами в метод Init, такую как идентификатор клиента, электронную почту и телефон, обратитесь к менеджеру или в техническую поддержку, чтобы для вашего терминала включили передачу объекта "Data". Перечисленная выше информация будет возвращаться в объекте "Data", вместе с рядом других технических параметров, которые можно игнорировать.

Параметры нотификаций:

Наименование	Тип	Описание
TerminalKey	String	Идентификатор терминала, выдается Мерчанту Т‑Кассой
Amount	Number	Сумма в копейках
OrderId	String	Идентификатор перевода в системе Мерчанта
Success	Boolean	Успешность запроса
RequestKey	String	Идентификатор запроса на привязку карты
Status	String	Статус перевода
PaymentId	String	Уникальный идентификатор транзакции в системе Т‑Кассы
ErrorCode	String	Код ошибки. «0» в случае успеха
PaymentURL	String	Ссылка на платежную форму
Message	String	Краткое описание ошибки
Details	String	Подробное описание ошибки
RebillId	String	Идентификатор рекуррентного перевода
CardId	Number	Идентификатор карты в системе Т‑Кассы
Pan	String	Маскированный номер карты
ExpDate	String	Срок действия карты в формате MMYY, где YY — две последние цифры года
Data	Object	Объект с техническими и дополнительными параметрами. Примеры дополнительных параметров: CUSTOMER_KEY (string) - Идентификатор клиента в системе Мерчанта; Email (string) - Email клиента в системе Мерчанта; Phone (string) - Номер телефона клиента в системе Мерчанта;
Token	String	Подпись запроса. Формируется по такому же принципу, как и в случае запросов в Т‑Кассу

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

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

* Операция подтверждается автоматически

• Узнать статус перевода можно с помощью вызова метода GetState

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

В случае успешной обработки нотификации Мерчанту необходимо вернуть ответ 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": "TinkoffBankTest"],["OrderId": "201709"],["Success": "true"],["Status": "AUTHORIZED"],["PaymentId": "8742591"],["ErrorCode": "0"],["Amount": "9855"],["CardId": "322264"],["Pan": "430000******0777"],["ExpDate": "1122"],["RebillId": "101709"]]

2. Добавить в массив пару (Password, значение). Password – пароль для терминала, указан в Личном кабинете https://business.tbank.ru/oplata/main:

[["TerminalKey": "TinkoffBankTest"],["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": "TinkoffBankTest"]]

4. Конкатенировать значения всех пар:

985532226401122201709430000******0777Dfsfh56dgKl8742591101709AUTHORIZEDtrue1321054611234DEMO

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

b906d28e76c6428e37b25fcf86c0adc52c63d503013fdd632e300593d165766b

CODE	MESSAGE	DETAILS (опционально)
0	None
1	Параметры не сопоставлены
2	Отсутствуют обязательные параметры
3	Внутренняя ошибка системы интернет эквайринга
4	Не получится изменить статус платежа
5	Обратитесь в поддержку, чтобы уточнить детали
6	Не получилось привязать карту покупателя. Обратитесь в поддержку, чтобы уточнить детали
7	Неверный статус покупателя
8	Неверный статус транзакции
9	Переадресовываемый url пуст
11	Невозможно выполнить платеж
12	Неверный параметр RedirectDueDate
13	Оплата с мобильного телефона недоступна
13	Оплата через WebMoney недоступна
14	Платеж неверный
15	Не удалось осуществить платеж через EINV.
16	Счет был отклонен
17	Неверные введенные данные
18	Не удалось осуществить платеж через MC
19	Не удалось осуществить платеж через WebMoney
20	Ошибка повторного идентификатора заказа
21	Внутренняя ошибка вызова сервиса ACQAPI
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	Операция по иностранной карте недоступна	Операция по иностранной карте недоступна. Воспользуйтесь картой российского банка
78	Выплата на иностранную карту недоступна	Выплата на иностранную карту недоступна. Воспользуйтесь картой российского банка
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	Недостаточно средств на счете
105	Нужно настроить автоплатежи по Maestro — для этого обратитесь в поддержку
106	Карта не поддерживает 3DS проверку. Попробуйте другую карту
107	Неверно введен CardId. Проверьте, что такая карта была ранее привязана
109	Не найден dsTranId для сессии
110	Не передан cres
111	Передан некорректный cres
119	Превышено допустимое количество запросов авторизации операции
120	Попробуйте повторить попытку позже
123	Попробуйте повторить попытку позже
125	Попробуйте повторить попытку позже
191	Некорректный статус договора, обратитесь к вашему менеджеру
201	Поле PaymentId не должно быть пустым
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	Платеж не найден
257	Некорректное значение признака последней выплаты. Используйте значения true или false	Некорректное значение признака последней выплаты. Используйте значения true или false
259	Параметр EncryptedPaymentData не сопоставлен
260	Максимальная длина номера телефона 30 символов
261	Параметр Source не сопоставлен
305	Ошибка проверки поля
309	Поле Receipt не должно быть пустым
316	Максимальная длина номера телефона 19 символов
322	Передана некорректная подпись
323	Amount не совпадают
325	Транзакция не найдена
326	Неверный amount
327	Терминал не поддерживает C2C переводы или не передан Route=""C2C"" для C2C терминала
328	Должны присутствовать данные для списания и данные для пополнения
330	Сумма в запросе больше чем в оригинальной транзакции
331	Неверный терминал
335	OrderId {value} не найден для TerminalKey {value}
381	Возможна привязка только резидентных карт
382	Возможна привязка только нерезидентных карт
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	Платеж не найден
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	Системная ошибка	Системная ошибка
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	Превышено допустимое количество запросов авторизации операции
8002	T-Bank Credit Broker недоступен. Повторите попытку позже
8003	Операция запрещена для покупки долями
8004	BNPL недоступен. Повторите попытку позже
9001	Попробуйте повторить попытку позже
9999	Внутренняя ошибка системы