Перейти к содержанию

Pay API v1.1.0

API для оплаты покупок в торговых точках, подключённых к Koshelek Pay API.

Общие сведения

Руководство предназначено для торгово-сервисных предприятий (ТСП), интегрирующих платёжный сервис Koshelek Pay для организации оплаты товаров и услуг в точках обслуживания клиентов.

О версиях Pay API

  • Изменения в Pay API фиксируются на странице История изменений.
  • Интеграция с новыми партнёрами осуществляется по последней версии Pay API.
  • Провайдеры платежей «СБП» и «Долями» доступны начиная с версии Pay API 0.9.0.

Изменения: Pay API v1.0.0 → v1.1.0

Возврат оплаты

  • Request body: добавлен параметр currency.

Объект item

  • Добавлены параметры measure, currency.
  • Параметр quantity: дополнено описание параметра.

Объект slip

  • Добавлен параметр currency.
  • Параметр operationId: обновлено описание параметра (значение присваивается провайдером платежей для операций возврата).

Объект checkoutInvoice

  • Добавлен параметр currency.

Объект invoice

  • Добавлен параметр currency.

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