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

Провайдером API выступает сервер Кошелька. Потребителями API являются кассовое ПО и узлы ЦОД ТСП.
Параметры подключения
Партнеру (ТСП) передаются следующие параметры для подключения к Кошелёк Pay API:
Параметр
Описание
Login
Имя пользователя для авторизации запросов API (используется HTTP Basic Authentication).
Password
Пароль для авторизации запросов API.
API Base URL 
(test)
URL для тестового подключения:
https://api-test.koshelek.app/<partner-name>
API Base URL (production)
URL для промышленного подключения:
https://api.koshelek.app/<partner-name>
API Base URL уникален для каждого партнёра. Например, для партнёра с именем name Base URL будет выглядеть так:
API Base URL (test): https://api-test.koshelek.app/name​
API Base URL (production): https://api.koshelek.app/name​
Партнёру необходимо предусмотреть возможность оперативного изменения следующих параметров сервиса, взаимодействующего с Pay API (вынесением их в отдельный конфигурационный файл или иным способом):
Login
Password
API Base URL (test, production)
Stores:storeId (см. описание параметра ниже)
Terminals:terminalId (см. описание параметра ниже)
В информационном обмене с партнёром (ТСП) используется ряд параметров, идентифицирующих ТСП. Параметры перечислены в таблице ниже. Цветом обозначены параметры, передаваемые в случае, если оплата осуществляется через Систему быстрых платежей (СБП):
Параметр
Контекст
Описание
brandName
Общий
Фирменное торговое наименование ТСП.
legalName
Общий
Полное наименование юридического лица или ИП партнера.
Stores: storeId
Общий
Полный список торговых точек ТСП с их адресами. Идентификатор storeId присваивается Кошельком для каждой торговой точки. Его необходимо передавать в каждом запросе.
postbackUrl
Общий, если у кассы есть онлайн-хост
URL, используемый кассой для приема статуса транзакции от сервера Кошелёк Pay.
partnerLogin
Общий, если у кассы есть онлайн-хост
Имя пользователя для авторизации запросов к postbackUrl (используется HTTP Basic Authentication).
partnerPassword
Общий, если у кассы есть онлайн-хост
Пароль для авторизации запросов к postbackUrl (используется HTTP Basic Authentication).
Terminals: terminalId
Общий
Список идентификаторов кассовых терминалов terminalId. Значение присваивается кассе самим ТСП и передается в каждом запросе; предварительно предоставлять полный список не требуется. Необходимо обеспечить уникальность terminalId в рамках одного storeId (одной торговой точки).
legalId
СБП
Идентификатор ТСП как юридического лица в СБП. Выдается банком-получателем, который подключает ТСП к СБП. Необходимо предоставить Кошельку при подключении к Pay API.
merchantId
СБП
Идентификатор торговой точки ТСП в СБП.
Выдается банком-получателем, который подключает ТСП к СБП. Необходимо предоставить Кошельку при подключении к Pay API. Необходимо однозначное (1:1) соответствие связки storeId—merchantId.
account
СБП
Счет юридического лица ТСП в банке-получателе. Необходимо предоставить Кошельку при подключении к Pay API.
memberId
СБП
Идентификатор банка-участника в СБП. Необходимо предоставить Кошельку при подключении к Pay API.
paymentPurpose
СБП
Назначение платежа. Параметр необходимо передавать при платежах с привязанного счета. Может быть согласован единожды между ТСП и Кошельком при подключении к Pay API, либо может передаваться в каждом запросе /checkout.
subscriptionPurpose
СБП
Назначение привязки счета пользователя. Согласовывается между ТСП и Кошельком при подключении к Pay 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
transactionId не найден.
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

Pay API v1.1.0

Last modified 1mo ago

Copy link

On this page

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

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

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

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

Коды HTTP