Подключение к API
Требования для подключения партнера
Провайдером API выступает сервер Кошелька. Потребителями API являются кассовое ПО и узлы ЦОД ТСП.
Партнеру (ТСП) передаются следующие параметры для подключения к Кошелёк Pay API:
Параметр | Описание |
---|---|
Login | |
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 буд ет выглядеть так:Партнёру необходимо предусмотреть возможность оперативного изменения следующих параметров сервиса, взаимодействующего с Pay API (вынесением их в отдельный конфигурационный файл или иным способом):
- Login
- Password
- API Base URL (test, production)
- Stores:
storeId
(см. описание параметра ниже) - Terminals:
terminalId
(см. описание параметра ниже)
В информационном обмене с партнёром (ТСП) используется ряд параметров, идентифицирующих ТСП. Параметры перечислены в таблице ниже. Цветом обозначены параметры, передаваемые в случае, если оплата осуществляется через Систему быстрых платежей (СБП):
Параметр | Контекст | Описание |
---|---|---|
brandName | Общий | Фирменное торговое наименование ТСП. |
legalName | Общий | Полное наименование юридического лица или ИП партнера. |
Stores: storeId | Общий | Полный список торговых точек ТСП с их адресами. Идентификатор storeId присваивается Кошельком для каждой торговой точки. Его необходимо передавать в каждом запросе. |
postbackUrl | Общий, если у кассы есть онлайн-хост | URL, используемый кассой для приема статуса транзакции от сервера Кошелёк Pay. |
partnerLogin | Общий, если у кассы есть онлайн-хост | |
partnerPassword | Общий, если у кассы есть онлайн-хост | |
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"
.В случае успешного выполнения запроса со стороны узла 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 | Транзакция в обработке. |
Last modified 4mo ago