ОПИСАНИЕ ПРОТОКОЛА A2C_V2 Мультирасчеты
1. Параметры выплат Параметры выплат настраиваются отдельно на каждый терминал. Таблица 1.1. Параметры выплат Название параметра Формат Описание TerminalKey 20 символов (чувствительно к регистру) Уникальный символьный ключ терминала. Устанавливается банком Success Add Card URL 250 символов (чувствительно к регистру) URL на веб-сайте продавца, куда будет переведен покупатель после успешной привязки карты Fail Add Card URL 250 символов (чувствительно к регистру) URL на веб-сайте продавца, куда будет переведен покупатель после неуспешной привязки карты Notification URL 250 символов (чувствительно к регистру) URL на веб-сайте продавца, куда будет отправлен POST запрос о статусе выполнения вызываемых методов. Только для методов Authorize, FinishAuthorize, Confirm, Cancel Валюта терминала 3 символа Валюта, в которой будут происходить списания по данному терминалу, если иное не передано в запросе Активность терминала Рабочий / Неактивный / Тестовый Определяет режим работы данного терминала Password 20 символов (чувствительно к регистру) Используется для подписи запросов/ответов. Является секретной информацией, известной только продавцу и банку. Пароль находится в личном кабинете мерчанта https://business.tbank.ru. Он совпадает с паролем от терминала интернет-эквайринга «Протокол A2C_V2 Мультирасчеты» 7 Таблица 1.2. Параметры Success Add Card URL и Fail Add Card URL Наименование Описание Success Возможные значения: true – привязка карты завершилась успешно; false – привязка карты не завершилась ErrorCode Код ошибки (0 – если ошибки не было). OrderId Номер заказа в системе Площадки. Message Заголовок ошибки (заполняется только в случае ошибки). Details Детальное описание ошибки (заполняется только в случае ошибки). Например: https://securepay.tinkoff.ru/html/payForm/e2c/html/e2cSuccess.html?Success=${Success}&ErrorCode=${E rrorCode}&Message=${Message}&Details=${Details}&PaymentId=${PaymentId}&TranDate=${TranDate}&B ackUrl=${BackUrl} «Протокол A2C_V2 Мультирасчеты» 8 2. Методы приема платежей 2.1. Общая информация Выдача средств осуществляется вызовом методов с передачей параметров методом GET или POST в зависимости от метода. Все методы и передаваемые параметры являются чувствительными к регистру. Порядок передачи параметров в запросе значения не имеет. Для POST запроса в заголовке должен присутствовать Content-Type: application/json Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2 Боевой URL: https://securepay.tinkoff.ru/e2c/v2 *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала. Для настройки и подключения TLS-cертификата от НУЦ Минцифры используйте инструкцию. «Протокол A2C_V2 Мультирасчеты» 9 2.2. Схема проведения платежа На схеме показаны статусы платежа и возможные методы, которые могут быть вызваны, если платеж находится в данном статусе. Полный список возможных статусов операции: • NEW — новая сессия, • AUTHORIZING — авторизация, • CHECKING — проверка данных, • CREDIT_CHECKING — на стадии обработки, • COMPLETING — операция выполняется, • REJECTED — операция отклонена, • CHECKED — проверка прошла успешно, • COMPLETED — операция успешно выполнена. «Протокол A2C_V2 Мультирасчеты» 10 2.3. Метод Init Метод для схем PCI DSS \ Без PCI DSS Описание: Инициирует платежную сессию. Примечание: При выплате по СБП не требуется использовать метод Payment. Выплата происходит в рамках одного метода Init. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/Init/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/Init/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 2.3.1. Параметры запроса на выплату Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком OrderId String Да Номер заказа в системе Площадки IP String Нет IP-адрес клиента PaymentRecipientId String Да Идентификатор будущего получателя выплаты (номер телефона, email или иной идентификатор). Ограничение по длине значения: 16 символов. DealId Number Да Идентификатор сделки LevelOfConfidence String Нет Уровень проверки получателя выплаты. Параметр необходим только в том случае, если его передачу потребовал отдел рисков на этапе подключения. Возможные значения: "low", "moderate", "high" FinalPayout Boolean Нет Признак финальной выдачи. Если передан в значении true - сделка автоматически закроется после выплаты DigestValue String Да** Значение хеша в Base64 SignatureValue String Да** Значение подписи в Base64 X509SerialNumber String Да** Серийный номер сертификата «Протокол A2C_V2 Мультирасчеты» 11 Token String Нет** Подпись запроса CardId String Да* Идентификатор карты пополнения, привязанной с помощью метода AddCard. CardData String Да* Данные карты пополнения Phone String Да* Номер телефона получателя Формат: 11 цифр Пример: 70123456789 SbpMemberId Number Да* Идентификатор банка-получателя в СБП Получить список идентификаторов банка можно через Метод GetSbpMembers PartnerId String Да* ID партнера магазина Мультирасчётов, которому предназначается выплата. Партнер должен быть зарегистрирован в системе Банка (подробнее в документации). Передается значение из shopCode, полученного при регистрации партнера. Amount Number Да Сумма в копейках. Минимальное значение —100 Currency Number Нет Код валюты ISO 4217 (например, 643). Если передан Currency, и он разрешен для Продавца, то транзакция будет инициирована в переданной валюте. Иначе будет использована валюта по умолчанию для данного терминала. DATA Object Нет JSON объект, содержащий дополнительные параметры в виде “ключ”:“значение”. При передаче параметра CustomerKey, переданные в Data параметры привяжутся к пользователю. Максимальная длина для каждого передаваемого параметра: − Ключ – 20 знаков; − Значение – 100 знаков. Максимальное количество пар «ключзначение» не может превышать 20. senderAccountInfo Object Нет Объект для передачи данных отправителя (необходим для выплат на иностранные карты) recipientAccountInfo Object Нет Объект для передачи данных получателя (необходим для выплат на иностранные карты) «Протокол A2C_V2 Мультирасчеты» 12 * условная обязательность передачи: – CardId для выплаты на привязанную карту – или CardData для выплаты по зашифрованным данным карты – или набор параметров Phone и SbpMemberId для выплаты по СБП – или PartnerId для выплат Партнеру ** передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Таблица 2.3.2. Параметры CardData Наименование Тип Обязательность Описание PAN Number Да Номер карты ExpDate Number Нет Месяц и год срока действия карты в формате MMYY CardHolder String Нет Имя и фамилия держателя карты (как на карте) CVV String Нет Код защиты (с обратной стороны карты) Объект CardData собирается в виде списка «ключ=значение» (разделитель «;»), зашифровывается открытым ключом (X509 RSA 2048), получившееся бинарное значение кодируется в Base64. Открытый ключ генерируется в Т-Бизнес. Для получения открытого ключа для шифрования CardData можете написать на acq_help@tbank.ru или обратиться к сотруднику, который вам помогал с процессом выпуска терминала. Пример значения элемента формы CardData: PAN=4300000000000777;ExpDate=0523;CardHolder=IVAN PETROV;CVV=111 Привязка карты, переданной в объекте CardData, должна происходить в момент вызова Init к указанному CustomerKey (если он был передан) Таблица 2.3.3. Параметры объекта senderAccountInfo Наименование Тип Обязательность Описание addressInfo Object Обязателен для нерезидентов Блок адресных данных отправителя address String Да Адрес отправителя apartment String Да Номер квартиры отправителя «Протокол A2C_V2 Мультирасчеты» 13 building String Да Номер дома отправителя city String Да Город отправителя country String Да Код страны по стандарту ISO street String Да Улица отправителя postalCode String Да Почтовый индекс отправителя personInfo Object Обязателен для нерезидентов Блок персональных данных отправителя firstName String Да Имя lastName String Да Фамилия middleName String Да Первая буква отчества. При отсутствии отчества передается пробел dateOfBirth String Да Дата рождения citizenship String Да Гражданство passportInfo Object Обязателен для нерезидентов Блок паспортных данных series String Да Серия паспорта number String Да Номер паспорта issueDate String Да Дата выдачи паспорта accountNumber String Да Номер счета Пример заполнения объекта senderAccountInfo: "senderAccountInfo": { "addressInfo": { "address": "100000 Russia Moscowovie Moscow Titushkino 1 111", "apartment": "111", "building": "1", "city": "Moscow", "country": "643", "street": "Titushkino", "postalCode": "100000" }, «Протокол A2C_V2 Мультирасчеты» 14 "personInfo": { "firstName": "Nikolay", "lastName": "Petrov", "middleName": "A", "dateOfBirth": "21.12.2000", "citizenship": "RUS" }, "passportInfo": { "series": "00", "number": "000000", "issueDate": "12.12.2023" }, "accountNumber": "5546329130144633" } Таблица 2.3.4. Параметры объекта recipientAccountInfo Наименование Тип Обязательность Описание personInfo Object Да Блок персональных данных получателя firstName String Да Имя lastName String Да Фамилия middleName String Да Первая буква отчества. При отсутствии отчества передается пробел dateOfBirth String Да Дата рождения citizenship String Да Гражданство Пример заполнения объекта senderAccountInfo: { "TerminalKey": "TerminalKeyE2C", "recipientAccountInfo": { "personInfo": { "firstName": "Darja", "lastName": "Shulgan", "middleName": "A", "dateOfBirth": "21.12.2000", "citizenship": "RUS" } } «Протокол A2C_V2 Мультирасчеты» 15 Пример запроса для выплат на карту: { "TerminalKey": "TerminalKeyE2C", "OrderId": " TestOrder ", "CardId": "11111", "Amount": 1751, "PaymentRecipientId": "+7 999123456”, "DealId": "112233", "LevelOfConfidence": "moderate”, "FinalPayout": true, "Token": "17b0ac0170ec685cd9e3fc57948d21aeb45778c2c7da54140e9f258cb0a68ba1", "senderAccountInfo": { "addressInfo": { "address": "Moscow 5 259", "apartment": "259", "building": "5", "city": "Moscow ", "country": "643", "street": "Moscow ", "postalCode": "215010" }, "personInfo": { "firstName": " Отправитель ", "lastName": " Тест ", "middleName": " Тестович ", "dateOfBirth": "01.01.1990", "citizenship": "RUS" }, "passportInfo": { "series": "00 11", "number": "123456", "issueDate": "01.01.2010" }, }, "recipientAccountInfo": { "personInfo": { "firstName": " Получатель ", "lastName": " Тест", "middleName": " Тестович", "dateOfBirth": "01.01.2000", "citizenship": "BLR" } } Пример запроса для выплат СБП: { "TerminalKey": "TerminalKeyE2C", «Протокол A2C_V2 Мультирасчеты» 16 "OrderId": "testSBP 10", "Phone": "79998887766", "SbpMemberId": "100000000004", "FinalPayout": "true", "Amount": 100, "DealId": "9043456", "PaymentRecipientId": "79066589133", "Token": "e24fd85c4c20e85d2eab5f65e8b2066c83970b" } Пример запроса для выплат Партнеру: { "TerminalKey": "TerminalKeyE2C", "OrderId": "TestOrder", "Amount": 1751, "PartnerId": "523456”, "DealId": "112233", "FinalPayout": true, "Token": "cb70d75fff815c433b17297593e66eb33d0dd90ec5933b24272820cc564e7dca" } Ответ Формат ответа: JSON Таблица 2.3.5 Параметры ответа при выплате на карту Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком Amount Number Да Сумма в копейках OrderId String Да Номер заказа в системе Площадки Success bool Да Успешность операции Status String Да Статус транзакции PaymentId String Да Уникальный идентификатор транзакции в системе Банка CardId String Нет Идентификатор карты в системе Банка MaskedFio String Нет Маскированные данные ФИО получателя (для выплат по СБП) ErrorCode String Да Код ошибки, «0» - если успешно Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки «Протокол A2C_V2 Мультирасчеты» 17 Примеры ответа: { "Success": true, "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "Status": "CHECKED", "PaymentId": "2353039", "OrderId": " PaymentTestN ", "Amount": 100000 } Пример ответа при выплате по СБП: { "TerminalKey": "TerminalKeyE2C", "OrderId": "Номер заказа", "PaymentId": "4443333222211", "Amount": "10000", "Success": "true", "Status": "COMPLETING", "ErrorCode": "0", "MaskedFio": "Иван И." } Статус платежа при выплате на карту или выплате Партнеру: • при успешном сценарии: CHECKED • при неуспешном: REJECTED при выплате по СБП: • при успешном сценарии: COMPLETED • при неуспешном: REJECTED • временный статус обработки: COMPLETING «Протокол A2C_V2 Мультирасчеты» 18 2.4. Метод Payment Метод для схем PCI DSS \ Без PCI DSS Описание: Пополняет карту. Примечание: При выплате по СБП не требуется использовать метод Payment. Выплата происходит в рамках одного метода Init. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/Payment/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/Payment/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 2.4.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком PaymentId String Да Уникальный идентификатор транзакции в системе Банка DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата Token String Нет* Подпись запроса * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "PaymentId": "700000085140", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } «Протокол A2C_V2 Мультирасчеты» 19 Ответ Формат ответа: JSON Таблица 2.4.2. Параметры ответа Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком OrderId String Да Номер заказа в системе Площадки Success bool Да Успешность операции (true/false) Status String Да Статус транзакции PaymentId String Да Уникальный идентификатор транзакции в системе Банка ErrorCode String Да Код ошибки, «0» - если успешно Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": "true", "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "Status": "COMPLETED", "PaymentId": "10063", "OrderId": "21050" } Статус операции: • при успешном сценарии и одностадийном проведении платежа: COMPLETED • при неуспешном: REJECTED • операция обрабатывается: CREDIT_CHECKING* *операция будет находиться во временном статусе CREDIT_CHECKING в течении первых 10-20 минут. В течение этого времени можно вызвать метод GetState для уточнения конечного статуса выплаты, отличного от CREDIT_CHECKING, а именно: COMPLETED/REJECTED/CHECKED «Протокол A2C_V2 Мультирасчеты» 20 2.5.Метод GetState Метод для схем PCI DSS \ Без PCI DSS Описание: Возвращает статус платежа. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/GetState/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/GetState/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 2.5.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком PaymentId String Да Уникальный идентификатор транзакции в системе Банка IP String Нет IP-адрес клиента DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата Token String Нет* Подпись запроса * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "PaymentId": "700000085101", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } «Протокол A2C_V2 Мультирасчеты» 21 Ответ Формат ответа: JSON Таблица 2.5.2. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком OrderId String Да Номер заказа в системе Площадки Success Boole Да Успешность операции (true/false) Status String Да Статус транзакции Amount Number Нет Сумма отмены в копейках PaymentId String Да Уникальный идентификатор транзакции в системе Банка ErrorCode String Да Код ошибки, «0» - если успешно Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": "true", "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "Status": "NEW", "PaymentId": "10063", "OrderId": "21057" } Возможные статусы транзакции: Статус Промежуточный? Значение NEW Нет Платеж зарегистрирован в шлюзе, но его обработка в процессинге не начата CHECKING Да Платеж на этапе проверки данных «Протокол A2C_V2 Мультирасчеты» 22 CHECKED Нет Данные проверены COMPLETING Да Начало зачисления денежных средств COMPLETED Нет Денежные средства зачислены на карту получателя REJECTED Нет Платеж отклонен Банком CREDIT_CHECKING* Да На стадии обработки. В течение 60 минут операции присвоится конечный статус согласно схеме * операция обрабатывается и будет находиться во временном статусе CREDIT_CHECKING в течении первых 10-20 минут. В течение этого времени можно вызвать метод GetState для уточнения конечного статуса выплаты: COMPLETED/REJECTED/CHECKED. «Протокол A2C_V2 Мультирасчеты» 23 2.6.Метод GetSbpMembers Метод для схем PCI DSS \ Без PCI DSS Описание: Получение списка идентификаторов банков, участвующих в СБП. Запрос Боевой URL: https://securepay.tinkoff.ru/a2c/sbp/GetSbpMembers Метод: POST Таблица 2.6.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком Token String Нет* Уникальный идентификатор транзакции в системе Банка DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "Token": "19b67a3be6500f17ccb607e5f874f614" } Ответ Формат ответа: JSON Таблица 2.6.2. Параметры ответа Наименование Тип Обязательность Описание Success Boolean Да Успешность прохождения запроса (true/false) ErrCode String Да Код ошибки, «0» - если успешно «Протокол A2C_V2 Мультирасчеты» 24 Message String Нет Краткое описание ошибки Members Object Да Таблица 2.6.3. Параметры объекта Members Наименование Тип Обязательность Описание MemberId String Да Код участника в СБП MemberName String Нет Наименование участника MemberNameRus String Да Наименование участника на русском Пример ответа: { "Success": true, "ErrorCode": "0", "Members": [ { "MemberId": "100000000004", "MemberName": "T-Bank", "MemberNameRus": "Т-Банк" }, { "MemberId": "100000000004", "MemberName": "T-Bank", "MemberNameRus": "Т-Банк" }, { "MemberId": "100000000004", "MemberName": "T-Bank", "MemberNameRus": "Т-Банк" } ] } «Протокол A2C_V2 Мультирасчеты» 25 2.7.Метод CancelPayment Метод для схем PCI DSS \ Без PCI DSS Описание: Отмена выплаты Партнеру. Примечание: Метод применяется только по успешной выплате Партнеру в рамках открытой сделки. По умолчанию метод отключен. Чтобы подключить отмены выплат Партнеру, пожалуйста, обратитесь к персональному менеджеру. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/CancelPayment Боевой URL: https://securepay.tinkoff.ru/e2c/v2/CancelPayment *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 2.7.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком PaymentId Number Да Идентификатор сессии выплаты ЮЛ, по которой необходимо сделать возврат DealId String Да Идентификатор сделки Amount Number Нет* Сумма отмены в копейках Минимальное значение — 1 ExternalRequestId String Нет** Идентификатор операции на стороне мерчанта Token String Нет*** Уникальный идентификатор транзакции в системе Банка DigestValue String Да*** Значение хеша в Base64 SignatureValue String Да*** Значение подписи в Base64 X509SerialNumber String Да*** Серийный номер сертификата * Если параметр Amount не указан, производится полная отмена выплаты Партнеру. Отмена производится на сумму остатка по сессии. «Протокол A2C_V2 Мультирасчеты» 26 ** Если поле заполнено, то перед проведением отмены выплаты проверяется запрос на отмену выплаты с таким ExternalRequestId: • если такой запрос уже есть, то в ответе вернется текущее состояние платежной операции; • если такого запроса нет, то произойдет отмена выплаты. Если поле не передано или пустое (""), то запрос будет обработан без проверки ранее созданных возвратов. *** Передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "PaymentId": "4713907670", "DealId": "112233", "Amount": 3000, "ExternalRequestId": "1234567890" "DigestValue": "cb70d75fff815c433b17297593e66eb33d0dd90ec5933b24272820cc564e7dca", "SignatureValue": "cb70d75fff815c433b17297593e66eb33d0dd90ec5933b24272820cc564e7dca", "X509SerialNumber": "2613832945" } Ответ Формат ответа: JSON Таблица 2.7.2. Параметры ответа Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком OrderId String Да Номер заказа в системе Площадки Success Boolean Да Успешность прохождения запроса (true/false) Status String Да Статус транзакции PaymentId Number Да Уникальный идентификатор транзакции в системе Банка OriginalAmount Number Да Сумма в копейках до операции отмены NewAmount Number Да Сумма в копейках после операции отмены ExternalRequestId String Нет Идентификатор операции на стороне мерчанта ErrorCode String Да Код ошибки, «0» - если успешно «Протокол A2C_V2 Мультирасчеты» 27 Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": true, "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "Status": "PART_CREDIT_CANCELED", "ExternalRequestId": "1234567890", "PaymentId": "4713907670", "OriginalAmount": 10000, "NewAmount": 7000, "OrderId": "2124144154" } Статус операции: • при обработке запроса — CREDIT_CANCELING или CANCEL_CHECKING • при успешном выполнении сессия переходит в один из статусов: CREDIT_CANCELED — при отмене на полную сумму, PART_CREDIT_CANCELED — в случае частичной отмены • при неуспешном выполнении сессия получает статус COMPLETED , если по ней не было отмен, либо PART_CREDIT_CANCELED, если имелись частичные отмены «Протокол A2C_V2 Мультирасчеты» 28 2.8. Метод getConfirmOperation Метод генерирует справку по операции. Ее можно получить на вашу электронную почту или URL вашего сервиса, куда файл со справкой придет в формате Base64. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/v2/getConfirmOperation Боевой URL: https://securepay.tinkoff.ru/v2/getConfirmOperation * Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос отправляется с боевого терминала. Метод: POST Таблица 2.8.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала. Выдается Площадке в Т-Бизнес при заведении терминала. Token String Да Подпись запроса. Для создания токена используйте только пароль и TerminalKey. PaymentIdList Array Да Номер заказа в системе Площадки. CallbackUrl String Да* URL cервиса получения справок. EmailList Array Да* Массив, который содержит перечень Email в формате String. * Передается либо CallbackUrl, либо EmailList. Пример запроса с получением справки на URL: { "TerminalKey": "TBankTest", "CallbackUrl": "http://www.tbank.ru", "PaymentIdList": [1201206437,1201206442], "Token": "f2fdd7fec8225872590e1558b7ea258c75df8f300d808006c41ab540dd7514d9 } Пример запроса с получением справки на Email: { "TerminalKey": "TBankTest", "PaymentIdList": [1201206437,1201206442], "EmailList": ["test1@tbank.ru","test2@tbank.ru"], «Протокол A2C_V2 Мультирасчеты» 29 "Token": "f2fdd7fec8225872590e1558b7ea258c75df8f300d808006c41ab540dd7514d9" } Ответ Формат ответа: JSON Таблица 2.8.2. Параметры ответа Наименование Тип Обязательность Описание Success Boolean Да Успешность запроса. ErrorCode String Да Код ошибки, «0» — если успешно. Message String Нет Краткое описание ошибки. PaymentIdList Array of objects Да JSON-массив с объектами, которые содержат информацию по запросу Таблица 2.8.3. Структура PaymentIdList Наименование Тип Обязательность Описание PaymentId String Да Уникальный идентификатор транзакции в системе Т-Бизнес. Success Boolean Да Успешность запроса. ErrorCode Number Да Код ошибки, «0» — если успешно. Message String Да Сервисное сообщение. Пример ответа: { "Success": true, "ErrorCode": 0, "Message": "OK", "PaymentIdList": [ { "Success": true, "ErrorCode": 0, "Message": "Запрос на отправку документа принят", "PaymentId": "1201206442" } ] } «Протокол A2C_V2 Мультирасчеты» 30 3. Алгоритм формирования подписи запроса 3.1. C помощью параметра Token Инструкция по формированию Token доступна по ссылке В запросе на выплаты не участвуют параметры X509SerialNumber, DigestValue, SignatureValue. Пример запроса в методе e2c/v2/Init: { "TerminalKey": "TerminalKeyE2C", "Amount": "1751", "OrderId": "autoOrd1615285401068DELb", "CardId": "70000000857", "Token": "76956ae79e4b33e9833ab09c344c638e14d772d0e423aec4db65039622b2f1b6" } 3.2. C помощью RSA сертификата: Для формирования подписи запроса необходимо: 1) Собрать массив всех передаваемых параметров в виде пар Ключ-Значение (кроме параметров DigestValue, SignatureValue, X509SerialNumber). Например: [{"TerminalKey","TerminalKeyE2C"},{"PaymentId","20150"}] 2) Сортировать по Ключам: [{"PaymentId","20150"},{"TerminalKey","TerminalKeyE2C"}] 3) Конкатенировать значения: 20150TerminalKeyE2C 4) Вычислить хэш-сумму по алгоритму SHA256 и получить результат в бинарном виде. 5) Закодировать получившееся бинарное значение в Base64 и записать значение в DigestValue 6) Подписать получившееся в п. 4 бинарное значение c помощью RSA ключа* алгоритмом RSASHA256, закодировать результат в BASE64 и записать в SignatureValue *Инструкция по получению RSA ключа доступна по ссылке. Ниже представлены примеры реализации работы с библиотекой: Язык Ссылка Java https://cdn.t-static.ru/static/documents/rsa-crypto-lib-java-mapi.zip «Протокол A2C_V2 Мультирасчеты» 31 3.3. C помощью сертификата КриптоПро: Для формирования подписи запроса необходимо: 1) Собрать массив всех передаваемых параметров в виде пар Ключ-Значение (кроме параметров DigestValue, SignatureValue, X509SerialNumber). Например: [{"TerminalKey","TerminalKeyE2C"},{"PaymentId","20150"}] 2) Сортировать по Ключам: [{"PaymentId","20150"},{"TerminalKey","TerminalKeyE2C"}] 3) Конкатенировать значения: 20150TerminalKeyE2C 4) Вычислить хэш-сумму по ГОСТ Р 34.11-2012 256 и записать значение в DigestValue (должно получиться значение в Base64). 5) Декодировать DigestValue из Base64, подписать получившееся значение по ГОСТ Р 34.10-2012 256 и записать в SignatureValue. (должно получится значение в Base64). *Инструкция по получению сертификата КриптоПро описана в п.7. Ниже представлены примеры реализации работы с библиотекой КриптоПро (CryptoPro): Язык Ссылка Версия КриптоПро С# Поддержка 2012 ГОСТ КриптоПРО CSP Java Поддержка 2012 ГОСТ КриптоПРО JCP PHP Поддержка 2012 ГОСТ КриптоПРО CSP «Протокол A2C_V2 Мультирасчеты» 32 4. Методы работы с привязанными картами и клиентами 4.1. Статусная схема привязки карт Необходимо обратить внимание, что для корректной работы методов банком должна быть разрешена привязка карт и клиентов к терминалу Продавца. В результате привязки карты к параметру CustomerKey будет привязана CardId. Описание статусов: − NEW — новая сессия; − FORM_SHOWED — показ формы привязки карты; − 3DS_CHECKING — отправка пользователя на проверку 3DS − 3DS_CHECKED — пользователь успешно прошел проверку 3DS; − AUTHORIZING — отправка платежа на 0 руб; − AUTHORIZED — платеж на 0 руб прошел успешно; − COMPLETED — привязка успешно завершена; − REJECTED — привязка отклонена. «Протокол A2C_V2 Мультирасчеты» 33 4.2. Метод AddCustomer Метод для схем PCI DSS \ Без PCI DSS Метод регистрирует покупателя в терминале Продавца. Возможна автоматическая привязка покупателя и карты, по которой был совершен платеж при передаче параметра CustomerKey в методе Init. Это можно использовать для сохранения и последующего отображения Покупателю замаскированного номера карты, по которой будет совершен рекуррентный платеж. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/AddCustomer/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/AddCustomer/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 4.2.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком CustomerKey String Да Идентификатор покупателя в системе Площадки IP String Нет IP-адрес запроса Email String Нет Email клиента Phone String Нет Телефон клиента (+71234567890) DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата Token String Нет* Подпись запроса * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", «Протокол A2C_V2 Мультирасчеты» 34 "CustomerKey": "TestCustomer20", "IP": "192.168.40.74", "Email": "autotest@test.ru", "Phone": "+71234567890", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } Формат ответа: JSON Ответ Таблица 4.2.2. Параметры ответа Наименование Тип Обязательность Описание TerminalKey String Да Платежный ключ, выдается Площадке при заведении терминала CustomerKey String Да Идентификатор покупателя в системе Площадки Success bool Да Успешность операции ErrorCode String Да Код ошибки, «0» в случае успеха Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": "true", "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "CustomerKey": "Customer1" } «Протокол A2C_V2 Мультирасчеты» 35 4.3. Метод GetCustomer Метод для схем PCI DSS \ Без PCI DSS Возвращает данные покупателя, сохраненные для терминала Продавца. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/GetCustomer/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/GetCustomer/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 4.3.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком CustomerKey String Да Идентификатор покупателя в системе Площадки IP String Нет IP-адрес запроса DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата Token String Нет* Подпись запроса * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "CustomerKey": "TestCustomer1", "IP": "192.168.40.74", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } «Протокол A2C_V2 Мультирасчеты» 36 Формат ответа: JSON Ответ Таблица 4.3.2. Параметры ответа Наименование Тип Обязательность Описание TerminalKey String Да Платежный ключ, выдается Площадке при заведении терминала CustomerKey String Да Идентификатор покупателя в системе Площадки Success bool Да Успешность операции ErrorCode String Да Код ошибки, «0» в случае успеха Email String Нет Email клиента Phone String Нет Телефон клиента (+71234567890) Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": true, "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "CustomerKey": "Customer1" } «Протокол A2C_V2 Мультирасчеты» 37 4.4. Метод RemoveCustomer Метод для схем PCI DSS \ Без PCI DSS Описание: Удаляет сохраненные данные покупателя. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/RemoveCustomer/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/RemoveCustomer/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 4.4.1. Параметры ответа Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком CustomerKey String Да Идентификатор покупателя в системе Площадки IP String Нет IP-адрес запроса DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата Token String Нет* Подпись запроса * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "CustomerKey": "TestCustomer11", "IP": "192.168.40.74", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } «Протокол A2C_V2 Мультирасчеты» 38 Формат ответа: JSON Ответ Таблица 4.4.2. Параметры ответа Наименование Тип Обязательность Описание TerminalKey String Да Платежный ключ, выдается Площадке при заведении терминала CustomerKey String Да Идентификатор покупателя в системе Площадки Success bool Да Успешность операции ErrorCode String Да Код ошибки, «0» в случае успеха Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": true, "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "CustomerKey": "Customer1" } «Протокол A2C_V2 Мультирасчеты» 39 4.5. Метод GetCardList Метод для схем PCI DSS \ Без PCI DSS Описание: Возвращает список привязанных карт у покупателя. В том числе показывает удаленные карты. Не возвращает список счетов, привязанных по номеру телефона через СБП Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/GetCardList/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/GetCardList/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 4.5.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком CustomerKey String Да Идентификатор покупателя в системе Площадки IP String Нет IP-адрес запроса DigestValue String Да* Значение хеша в Base64 SignatureValue String Да* Значение подписи в Base64 X509SerialNumber String Да* Серийный номер сертификата Token String Нет* Подпись запроса * передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) Пример запроса: { "TerminalKey": "TerminalKeyE2C", "CustomerKey": "TestCustomer1", "IP": "192.168.40.74", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } «Протокол A2C_V2 Мультирасчеты» 40 Формат ответа: Массив JSON Ответ Таблица 4.5.2. Параметры ответа Наименование Тип Обязательность Описание Pan String Да Номер карты 411111******1111 CardId String Да Идентификатор карты в системе Банка Status String Да Статус карты: A – активная, D – не активная, E – срок действия карты истек RebillId Number Да Идентификатор рекуррентного платежа ExpDate String Нет Срок действия карты Пример ответа: [ { "CardId": "894952", "Pan": "532130******5598", "Status": "A", "RebillId": "130802844", "CardType": 0, "ExpDate": "0423" }, { "CardId": "894955", "Pan": "518223******0036", "Status": "A", "RebillId": "13816414", "CardType": 0, "ExpDate": "1122" } ] «Протокол A2C_V2 Мультирасчеты» 41 4.6. Метод AddCard Метод для схем PCI DSS \ Без PCI DSS Описание: Добавляет привязанную карту к покупателю. В случае успешной привязки переадресует клиента на Success Add Card URL в противном случае на Fail Add Card URL. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/AddCard/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/AddCard/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 4.6.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Идентификатор терминала, выдается Площадке Банком CustomerKey String Да Идентификатор покупателя в системе Площадки CheckType String Нет Если CheckType не передается, автоматически проставляется значение NO. Возможные значения: 1. NO *– сохранить карту без проверок. RebillID для рекуррентных платежей не возвращается; 2. HOLD – при сохранении сделать списание на 0 руб.** RebillID возвращается для терминалов без поддержки 3DS. 3. 3DS – при сохранении карты выполнить проверку 3DS и выполнить списание на 0 р. В этом случае RebillID будет только для 3DS карт. Карты, не поддерживающие 3DS, привязаны не будут 4. 3DSHOLD – при привязке карты выполняем проверку, поддерживает карта 3DS или нет. Выполняется списание на 0р. PayForm String Нет Название шаблона формы привязки «Протокол A2C_V2 Мультирасчеты» 42 ResidentState Boolean Нет Признак резидентности добавляемой карты: Возможные значения: • true - Карта РФ, • false - Карта не РФ, • null - Не специфицируется (универсальная карта) DigestValue String Да*** Значение хеша в Base64 SignatureValue String Да*** Значение подписи в Base64 X509SerialNumber String Да*** Серийный номер сертификата Token String Нет*** Подпись запроса * Если передан параметр CheckType=NO, на форме привязки будет только поле для заполнения номера карты. В этом случае в нотификации о привязке карты параметр ExpDate будет пустым. ** при CheckType = 3DS, для успешной работы метода AttachCard необходимо передать срок действия карты в CardData (параметр ExpDate). *** передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи)/ Пример запроса: { "TerminalKey": "TerminalKeyE2C", "CustomerKey": "TestCustomer10", "IP": "192.168.40.74", "CheckType": "NO", "DigestValue": "qfeohMmrsEvr4QPB8CeZETb+W6VDEGnMrf+oVjvSaMU=", "SignatureValue": "rNTloWBbTsid1n9B1ANZ9/VasWJyg6jfiMeI12ERBSlOnzy6YFqMaa5nRb9ZrK9wbKimIBD70v8j8eP/tKn7/g==", "X509SerialNumber": "2613832945" } Формат ответа: JSON Ответ Таблица 4.6.2. Параметры ответа Наименование Тип Обязательность Описание PaymentId Number Да Уникальный идентификатор транзакции в системе Банка PaymentURL String Да Идентификатор страницы выплаты. «Протокол A2C_V2 Мультирасчеты» 43 TerminalKey String Да Платежный ключ, выдается Площадке при заведении терминала CustomerKey String Да Идентификатор покупателя в системе Площадки RequestKey String Да Идентификатор запроса на привязку карты Success bool Да Успешность операции ErrorCode String Да Код ошибки, «0» в случае успеха Message String Нет Краткое описание ошибки Details String Нет Подробное описание ошибки Пример ответа: { "Success": "true", "ErrorCode": "0", "TerminalKey": "TerminalKeyE2C", "CustomerKey": "Customer1", "PaymentURL": "https://securepayments.tinkoff.ru/addcard/02a94edd-046c-441b-90b6-cda01f337401", "RequestKey": "8de92934-26c9-474c-a4ce424f2021d24d" } «Протокол A2C_V2 Мультирасчеты» 44 4.7. Метод AttachCard Метод для схемы PCI DSS Описание: Добавляет привязанную карту к покупателю. Метод необходимо вызывать после AddCard. В случае успешной привязки переадресует клиента на Success Add Card URL в противном случае на Fail Add Card URL. Для прохождения 3DS второй версии перед вызовом метода должен быть вызван /v2/check3dsVersion и выполнен 3DS Method, который является обязательным при прохождении 3DS по протоколу версии 2.0. Запрос Тестовый URL*: https://rest-api-test.tinkoff.ru/e2c/v2/AttachCard/ Боевой URL: https://securepay.tinkoff.ru/e2c/v2/AttachCard/ *Для возможности отправки запросов на тестовую среду напишите на почту acq_help@tbank.ru c просьбой добавить ваши IP в WL. Запрос необходимо отправлять с боевого терминала Метод: POST Таблица 4.7.1. Параметры запроса Наименование Тип Обязательность Описание TerminalKey String Да Платежный ключ, выдается Площадке при заведении терминала RequestKey String Да Идентификатор запроса на привязку карты CardData String Да Данные карты привязки* DATA Object Нет*** Ключ = значение дополнительных параметров через “|”, например, Email = a@test.ru|Phone = +71234567890. Если ключи или значения содержат в себе спец символы, то получившееся значение должно быть закодировано функцией urlencode. Максимальная длина для каждого передаваемого параметра: Ключ – 20 знаков, Значение – 100 знаков. Максимальное количество пар «ключзначение» не может превышать 20 DigestValue String Да** Значение хеша в Base64 SignatureValue String Да** Значение подписи в Base64 X509SerialNumber String Да** Серийный номер сертификата «Протокол A2C_V2 Мультирасчеты» 45 Token String Нет** Подпись запроса * алгоритм шифрования описан на стр. 10 документации. ** передается или Token (если отключена валидация подписи), или набор параметров DigestValue, SignatureValue, X509SerialNumber (при включенной валидации подписи) *** для 3DS второй версии в параметрах DATA необходимо передавать следующие параметры Таблица