Pay API v1.2.0
API для оплаты покупок в торговых точках, подключённых к Koshelek Pay API.
Общие сведения
Руководство предназначено для торгово-сервисных предприятий (ТСП), интегрирующих платёжный сервис Koshelek Pay для организации оплаты товаров и услуг в точках обслуживания клиентов.
О версиях Pay API
- Изменения в Pay API фиксируются на странице История изменений.
- Интеграция с новыми партнёрами осуществляется по последней версии Pay API.
- Провайдеры платежей «СБП» и «Долями» доступны начиная с версии Pay API 0.9.0.
Изменения: Pay API v1.1.0 → v1.2.0
Запрос списка возможных провайдеров платежей
- Асинхронный вариант получения списка (соответствует коду ответа HTTP:
201) не используется в новых интеграциях (deprecated).
Получение списка доступных провайдеров платежей
- Запрос не используется в новых интеграциях (deprecated).
Подключение к API
Провайдером API выступает сервер Кошелька. Потребителями API являются кассовое ПО и узлы ЦОД ТСП. Партнёру передаются следующие параметры для подключения к Koshelek Pay API:
| Параметр | Описание |
|---|---|
| Login | Имя пользователя и пароль для авторизации запросов API (используется HTTP Basic Authentication). |
| Password | Пароль для авторизации запросов API. |
| API Base URL (test) | URL для тестового подключения: https://api-test.koshelek.app/ |
| API Base URL (production) | URL для промышленного подключения: https://api.koshelek.app/ |
API Base URL уникален для каждого партнёра. Например, для партнёра с именем name API 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, используемый кассой для приёма статуса транзакции от сервера Koshelek 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, либо может передаваться в каждом запросе POST ...merchant/checkout. |
subscriptionPurpose |
СБП | Назначение привязки счёта пользователя. Согласовывается между ТСП и Кошельком при подключении к Pay API. |
Авторизация
Взаимодействие осуществляется по протоколу HTTPS. Для авторизации запросов к Pay API необходимо использовать HTTP Basic Authentication (RFC 7617). Данные для авторизации запросов передаются в HTTP-заголовке Authorization.
Note
Используемая версия протокола TLS: не ниже 1.2.
Кодировки
Как в запросах, так и в ответах используется кодировка UTF-8.
Формат и структура сообщений
Все методы API ожидают тип данных в заголовке: Content-Type = application/json и возвращают тело ответа в формате application/json.
Коды HTTP
🟢 HTTP: 200
В случае успешной обработки запроса, со стороны узла платформы Кошелька будет возвращён тип данных, описанный в документации запроса, и HTTP-код 200.
Поле errorCode
В отдельных сценариях возврат HTTP-кода 200 может сопровождаться передачей сообщения об ошибке. Такое сообщение будет содержаться в теле ответа, в поле errorCode. Ниже приведена расшифровка возможных значений поля errorCode.
1. Для сценария оплаты:
| errorCode | Расшифровка |
|---|---|
NOT_ENOUGH_LIMIT_TO_PAY |
Превышен лимит для совершения операции. |
TOTAL_AMOUNT_IS_TOO_SMALL |
Сумма покупки ниже установленного лимита (составляет 4 рубля). |
EXTERNAL_PROVIDER_ERROR |
Общий код ошибки провайдера платежей. |
SUBSCRIPTION_IS_NOT_FOUND |
Привязанный счёт пользователя не найден (платёж через СБП с привязанного счёта пользователя). |
PAYMENT_DECLINED_BY_EXTERNAL_PROVIDER |
Платёж отклонён банком (платёж через СБП с привязанного счёта пользователя). |
2. Для сценария возврата:
| errorCode | Расшифровка |
|---|---|
PAYMENT_TRANSACTION_IS_NOT_PAID |
Возврат отклонён, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось. |
TERMINAL_STATE_OF_PAYMENT_TRANSACTION |
Возврат отклонён по одной из причин:
|
PAYMENT_TRANSACTION_IS_BEING_REFUNDED_ALREADY |
Возврат отклонён, т.к. есть незавершённая транзакция отмены. Дождитесь завершения процесса возврата по транзакции отмены с refTransactionId незавершённой предыдущей транзакции отмены. |
REQUESTED_REFUND_AMOUNT_IS_GREATER_THAN_AVAILABLE |
Возврат отклонён, т.к. запрошенная сумма к возврату превышает сумму оплаты по транзакции оплаты с данным transactionId. |
EXTERNAL_PROVIDER_ERROR |
Общий код ошибки провайдера платежей. |
UNEXPECTED_REFUND_AMOUNT_LEFT_FROM_EXTERNAL_PROVIDER |
Возврат отклонён, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось. |
PAYMENT_ORDER_IS_NOT_FOUND |
Только для транзакций СБП. Не найдено платёжное поручение в банке ТСП при выполнении операции возврата. |
🔴 HTTP: 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 |
Транзакция в обработке. |