Подключение к API
Требования для подключения партнёра
Провайдером API выступает сервер Кошелька. Потребителями API являются кассовое ПО и узлы ЦОД ТСП.
Параметры подключения
Партнёру (ТСП) передаются следующие параметры для подключения к Pay API:
| Параметр | Описание |
|---|---|
| host:port | Адрес и порт узла Кошелька, предоставляющего API. |
| login:password | Имя пользователя и пароль для авторизации запросов API (используется HTTP Basic Authentication). |
| Test URL | URL для тестового подключения: |
| Production URL | URL для промышленного подключения: |
В информационном обмене с партнером (ТСП) используется ряд параметров, идентифицирующих ТСП. Параметры перечислены в таблице ниже. Цветом обозначены параметры, передаваемые в случае, если оплата осуществляется через Систему быстрых платежей (СБП):
| Параметр | Контекст | Описание |
|---|---|---|
brandName |
Общий | Фирменное торговое наименование ТСП. |
legalName |
Общий | Полное наименование юридического лица или ИП партнера. |
Stores: storeId |
Общий | Полный список торговых точек ТСП с их адресами. Идентификатор storeId присваивается Кошельком для каждой торговой точки. Его необходимо передавать в каждом запросе. |
postbackUrl |
Общий, если у кассы есть онлайн-хост | URL, используемый кассой для приема статуса транзакции от сервера Koshelek Pay. |
partnerLogin |
Общий, если у кассы есть онлайн-хост | Имя пользователя для авторизации запросов к postbackUrl (используется HTTP Basic Authentication). |
partnerPassword |
Общий, если у кассы есть онлайн-хост | Пароль для авторизации запросов к postbackUrl (используется HTTP Basic Authentication). |
Terminals: terminalId |
Общий | Список идентификаторов кассовых терминалов terminalId. Значение присваивается кассе самим ТСП и передается в каждом запросе; предварительно предоставлять полный список не требуется. Необходимо обеспечить уникальность terminalId в рамках одного storeId (одной торговой точки). |
legalId |
СБП | Идентификатор ТСП как юридического лица в СБП. Выдается банком-получателем, который подключает ТСП к СБП. Необходимо предоставить Кошельку при подключении к Pay API. |
merchantId |
СБП | Идентификатор торговой точки ТСП в СБП. |
account |
СБП | Счет юридического лица ТСП в банке-получателе. Необходимо предоставить Кошельку при подключении к Pay API. |
memberId |
СБП | Идентификатор банка-участника в СБП. Необходимо предоставить Кошельку при подключении к Pay API. |
paymentPurpose |
СБП | Назначение платежа. Параметр необходимо передавать при платежах с привязанного счета. Может быть согласован единожды между ТСП и Кошельком при подключении к Pay API, либо может передаваться в каждом запросе POST /checkout. |
subscriptionPurpose |
СБП | Назначение привязки счета пользователя. Согласовывается между ТСП и Кошельком при подключении к Pay API. |
Авторизация запросов
Взаимодействие осуществляется по протоколу HTTPS. Для авторизации запросов к Pay API необходимо использовать HTTP Basic Authentication (RFC 7617). Данные для авторизации запросов передаются в HTTP-заголовке Authorization.
Info
Используемая версия протокола TLS — не ниже 1.2.
Требования к кодировкам
Как в запросах, так и в ответах используется кодировка UTF-8.
Формат и структура сообщений
Все методы API ожидают тип данных в заголовке: Content-Type: application/json и возвращают тело ответа в формате "application/json".
Коды HTTP
В случае успешного выполнения запроса со стороны узла платформы «Кошелёк» будет возвращен тип данных, описанный в документации запроса, и 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 |
Транзакция в обработке. |