Подключение к API

Кошелёк Pay API

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

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

• 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 Кошелёк передает партнёру в процессе имплементации Конфиг на уровне кассы
partnerPassword	Общий, если у кассы есть онлайн-хост	Логин авторизации HTTP Basic Authentication Кошелёк передает партнёру в процессе имплементации Конфиг на уровне кассы
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, либо может передаваться в каждом запросе/checkout.
subscriptionPurpose	СБП	Назначение привязки счета пользователя для оплат в магазинах ТСП. Будет отображаться в банковском приложении пользователя. Согласовывается между ТСП и Кошельком при подключении к Pay API.
postbackUrl (deprecated)	Общий, если у кассы есть онлайн-хост	URL, используемый кассой для приёма статуса транзакции от сервера Кошелёк Pay.

Авторизация запросов

Взаимодействие осуществляется по протоколу HTTPS. Для авторизации запросов к Pay API необходимо использовать HTTP Basic Authentication (RFC 7617). Данные для авторизации запросов передаются в HTTP-заголовке Authorization.

Используемая версия протокола TLS — не ниже 1.2.

Требования к кодировкам

Как в запросах, так и в ответах используется кодировка UTF-8.

Формат и структура сообщений

Все методы API ожидают тип данных в заголовке: Content-Type: application/json и возвращают тело ответа в формате "application/json".