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

Pay API v1.2.1

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

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

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

О версиях Pay API

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

Изменения: Pay API v1.2.0 → v1.2.1

Объект invoice

  • Параметр taxAmount: отменена обязательность передачи параметра.

Подключение к 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 уникален для каждого партнёра. Например, API Base URL для партнёра с именем name будет выглядеть так:

Параметр Значение
API Base URL (test) https://api-test.koshelek.app/name
API Base URL (production) https://api.koshelek.app/name

Идентификаторы, участвующие в информационном обмене

В информационном обмене с партнёром (ТСП) используется ряд параметров, идентифицирующих ТСП. Параметры перечислены в таблице ниже. Параметры со значением «СБП» в столбце «Контекст» используются в платежах через Систему быстрых платежей (СБП).

Параметр Контекст Описание
brandName Общий
  • Название бренда (фирменное торговое наименование ТСП).
  • Должно совпадать с именем, которое указывалось ТСП при регистрации в СБП (Merchant), т.к. пользователь будет также видеть это название в «Истории операций» своего банковского приложения.
  • Необходимо предоставить Кошельку при подключении к Pay API.
    		•
    legalName Общий
  • Название организации (юридического лица / ИП) партнёра.
  • Необходимо предоставить Кошельку при подключении к Pay API.
    		•
    Stores:storeId Общий
  • ID магазина.
  • Назначается Кошельком.
  • Ожидается в запросах от партнёров и передаётся в ответах (параметр storeId).
  • Настройка на уровне кассы.
    		•
    partnerLogin Общий, если у кассы есть онлайн-хост
  • Логин авторизации (HTTP Basic Authentication).
  • Назначается Кошельком при подключении к Pay API.
  • Конфигурируется на уровне кассы.
    		•
    partnerPassword Общий, если у кассы есть онлайн-хост
  • Пароль авторизации (HTTP Basic Authentication).
  • Назначается Кошельком при подключении к Pay API.
  • Конфигурируется на уровне кассы.
    		•
    Terminals:terminalId Общий
  • ID кассы.
  • Назначается партнёром.
  • Опционально ожидается в запросах от партнёров и передается в ответах (параметр terminalId).
  • Передаётся в сверках.
  • Настройка на уровне кассы.
    		•
    legalId СБП
  • Идентификатор организации, к которому выполнена регистрация ТСП (Merchant) в СБП.
  • Необходимо предоставить Кошельку при подключении к Pay API.
    		•
    merchantId СБП
  • Идентификатор торговой точки (ТСП) партнера в СБП.
  • Выдаётся банком-получателем, который подключает ТСП к СБП.
  • Необходимо предоставить Кошельку при подключении к Pay API.
  • Необходимо однозначное (1:1) соответствие связки storeId:merchantId.
    		•
    account СБП
  • Номер счёта юридического лица ТСП в банке-получателе, на который должны поступать денежные средства пользователей при оплате в Кошельке через СБП.
  • Необходимо предоставить Кошельку при подключении к Pay API.
    		•
    memberId СБП
  • Идентификатор банка-участника в СБП, который зарегистрировал организацию в СБП (выдал merchantId), и в котором у организации находится счёт (account).
  • Необходимо предоставить Кошельку при подключении к Pay API.
    		•
    paymentPurpose СБП
  • Назначение платежа — для платежей пользователя в магазине партнёра с привязанного пользователем счета в СБП.
  • Может быть согласован единожды между ТСП и Кошельком при подключении к Pay API, либо может передаваться в каждом запросе POST /checkout.
    		•
    subscriptionPurpose СБП
  • Назначение привязки счёта пользователя для оплат в магазинах ТСП.
  • Будет отображаться в банковском приложении пользователя.
  • Согласовывается между ТСП и Кошельком при подключении к Pay API.
    		•
    postbackUrl
    (deprecated)    		 Общий, если у кассы есть онлайн-хост URL, используемый кассой для приёма статуса транзакции от сервера Koshelek Pay.

    Авторизация

    Взаимодействие осуществляется по протоколу 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 code Назначение
    200 В случае успешной обработки запроса, со стороны узла платформы Кошелька будет возвращён тип данных, описанный в документации запроса, и HTTP-код 200.
    422 В случае ошибки обработки запроса, со стороны узла Кошельком будет возвращён HTTP-ответ с кодом 422, содержащий JSON-объект, описывающий ошибку. В частности, этот объект содержит строковое сообщение с описанием причины ошибки на русском языке.

    Структура объекта, описывающего ошибку:

    Поле Тип Обязательность Назначение
    code String Да Код ошибки (см. ниже).
    details String Нет Описание ошибки.

    Коды ошибок

    Код Описание Рекомендации кассиру
    EXTERNAL_PROVIDER_ERROR Общий код ошибки провайдера платежей. Попробуйте ещё раз или выберите другой способ оплаты
    UNKNOWN_SESSION_ID cardSession не существует / не прошёл валидацию. Повторно отсканируйте карту лояльности и повторите
    UNKNOWN_TRANSACTION_ID transactionId не найден. Попробуйте ещё раз или выберите другой способ оплаты
    UNKNOWN_PARTNER_ID merchant не найден. Техническая ошибка. Обратитесь к администратору, т.к. магазин не найден
    WRONG_TRANSACTION_STATE_CHANGE Невозможен перевод транзакции в ожидаемое состояние. Попробуйте ещё раз или выберите другой способ оплаты
    PAYMENT_TRANSACTION_IS_NOT_PAID Нет оплаты по транзакции оплаты. Попробуйте ещё раз через "X" минут или обратитесь к администратору (Примечание: “X” — конфигурируемый параметр)
    CANCEL_REFUNDING_BY_BANK Возврат отменён банком. Возврат отменён банком
    TRANSACTION_FOR_SESSION_ID_ALREADY_EXISTS Транзакция уже существует для сессии. Техническая ошибка. обратитесь к системному администратору
    TRANSACTION_FOR_SESSION_ID_ALREADY_PAYED Транзакция уже обработана. Техническая ошибка. обратитесь к системному администратору
    TRANSACTION_IN_PROCESSING Транзакция в обработке. Оплата уже проведена
    NOT_ENOUGH_LIMIT_TO_PAY Превышен лимит для совершения операции. Слишком большая сумма чека оплаты Долями. Попробуйте оплату СБП или смешанную оплату.
    TOTAL_AMOUNT_IS_TOO_SMALL Сумма покупки ниже установленного лимита. Сумма чека слишком маленькая
    SUBSCRIPTION_IS_NOT_FOUND Привязанный счёт пользователя не найден (платёж через СБП с привязанного счёта пользователя). Привязка счёта СБП не найдена. Попробуйте оплату Долями.
    PAYMENT_DECLINED_BY_EXTERNAL_PROVIDER Платёж отклонён банком (платёж через СБП с привязанного счёта пользователя). Проверьте достаточность средств или попробуйте оплату Долями
    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. Сумма возврата превышает сумму оплаты
    UNEXPECTED_REFUND_AMOUNT_LEFT_FROM_EXTERNAL_PROVIDER Возврат отклонён, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось. Возврат отклонён, покупка не завершена
    PAYMENT_ORDER_IS_NOT_FOUND Только для транзакций СБП. Не найдено платежное поручение в банке ТСП при выполнении операции возврата. Возврат отклонён, т.к. магазин не поддерживает возвраты. Обратитесь к администратору.