Подключение к API

Провайдером API выступает сервер Кошелька. Потребителями API являются кассовое ПО и узлы ЦОД ТСП.
Параметры подключения
Партнёру (ТСП) передаются следующие параметры для подключения к Кошелёк Pay API:
Параметр
Описание
host:port
Адрес и порт узла Кошелька, предоставляющего API.
login:password
Имя пользователя и пароль для авторизации запросов API
(используется HTTP Basic Authentication).
Test URL
URL для тестового подключения:
​https://api-test.koshelek.app/​
Production URL
URL для промышленного подключения:
​https://api.koshelek.app/​
В информационном обмене с партнёром (ТСП) используется ряд параметров, идентифицирующих ТСП. Параметры перечислены в таблице ниже. Цветом обозначены параметры, передаваемые в случае, если оплата осуществляется через "Систему быстрых платежей":
Параметр
Контекст
Описание
brandName
Общий
Фирменное торговое наименование ТСП.
legalName
Общий
Полное наименование юридического лица или ИП партнера
Stores
Общий
Полный список торговых точек с их адресами. Для каждой торговой точки Кошелёк выдает идентификатор storeId, который будет необходимо передавать в каждом запросе.
postbackUrl
Общий, если у кассы есть онлайн-хост
URL, используемый кассой для приёма статуса транзакции от сервера Кошелёк Pay.
partnerLogin
Общий, если у кассы есть онлайн-хост
Имя пользователя для авторизации запросов HTTP Basic Authentication (см. выше).
partnerPassword
Общий, если у кассы есть онлайн-хост
Пароль для авторизации запросов HTTP Basic Authentication (см. выше).
merchantId
СБП
Идентификатор, присвоенный ТСП системой СБП.
Выдается банком, с которым партнёр заключает договор на эквайринг счета для операций по СБП (банк-получатель).
account
СБП
Счет юридического лица ТСП в банке-получателе.
memberId
СБП
Идентификатор банка-участника в "Системе быстрых платежей", обслуживающего ТСП.
Terminals
Общий
Список идентификаторов кассовых терминалов terminalId. Значение присваивается кассе самим ТСП и передается в каждом запросе; предварительно предоставлять полный список не требуется.
Terminals
СБП + Тинькофф Банк в качестве эквайера
Аналогично общему случаю, но для каждого terminalId ТСП должен предварительно предоставить связку из двух параметров:
terminalKey — ключ (идентификатор кассового терминала, присвоенный банком-эквайером).
password — значение (пароль для данного terminalKey).
Параметры будут использоваться сервером Кошелька для авторизации подключения к Tinkoff API при оплате.
Авторизация запросов
Взаимодействие осуществляется по протоколу HTTPS. Для авторизации запросов к Pay API необходимо использовать HTTP Basic Authentication (RFC 7617). Данные для авторизации запросов передаются в HTTP-заголовке "Authorization".
Используемая версия протокола TLS — не ниже 1.2.
Требования к кодировкам
Как в запросах, так и в ответах используется кодировка UTF-8.
Формат и структура сообщений
Все методы API ожидают тип данных в заголовке: Content-Type ="application/json" и возвращают тело ответа в формате "application/json".
Коды HTTP
В случае успешного выполнения запроса, со стороны узла Cardsmobile будет возвращен тип данных, описанный в документации запроса, и HTTP-код 200.
Код
Назначение
200
Возвращается в случае успешного выполнения запроса API.
422
В случае ошибки обработки запроса будет возвращен HTTP-ответ с кодом 422, содержащий JSON-объект, описывающий возникшую ошибку. В частности, этот объект содержит строковое сообщение с описанием причины ошибки на русском языке.
Структура объекта, описывающего ошибку:
Поле
Тип
Назначение
code
String
Код ошибки.
details
String
Описание ошибки (необязательное поле, может отсутствовать).
Коды ошибок
Код
Описание
UNKNOWN_SESSION_ID
cardSession не существует/не прошел валидацию.
UNKNOWN_TRANSACTION_ID
tansactionId не найден.
UNKNOWN_PARTNER_ID
merchant не найден.
WRONG_TRANSACTION_STATE_CHANGE
Невозможен перевод транзакции в ожидаемое состояние.
PAYMENT_TRANSACTION_IS_NOT_PAID
Нет оплаты по транзакции оплаты.
CANCEL_REFUNDING_BY_BANK
Возврат отменен банком.
TRANSACTION_FOR_SESSION_ID_ALREADY_EXISTS
Транзакция уже существует для сессии.
TRANSACTION_FOR_SESSION_ID_ALREADY_PAYED
Транзакция уже обработана.
TRANSACTION_IN_PROCESSING
Транзакция в обработке.

Кошелёк Pay API - Previous

Обзор сценариев API

Next - Кошелёк Pay API

Запросы API

Last modified 19d ago

Copy link

Contents

Параметры подключения

Авторизация запросов

Требования к кодировкам

Формат и структура сообщений

Коды HTTP