Подключение к 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
Транзакция в обработке.

Параметр	Описание
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>

Параметр	Контекст	Описание
`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.

Код	Назначение
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.2.0

Last modified 4mo ago