СБП
Общие сведения
Общие сведения
Интерфейс позволяет:
выполнять операции электронной коммерции по оплате товаров и услуг мерчанта со счетов плательщиков, подключенных к системе СБП,
выполнять операции B2С электронной коммерции по переводу средств со счета мерчанта на счета получателей, подключенные к системе СБП.
Статусы операций
Статус
Значение
Created
Операция зарегистрирована в шлюзе
Pending
Операция находится в обработке
Completed
Операция выполнена успешно
Failed
Операция отклонена
Expired
Операция невозможна, истёк срок платёжной ссылки
Авторизация
Для авторизации при каждом запросе необходимо передавать заголовки. Значения для этих заголовков выдаются с параметрами доступа.
Authorization-Key — платежный ключ;
Authorization-Password — платежный пароль
Дополнительные заголовки
Correlation-ID — значение из этого заголовка может быть использовано для поиска логов в случае каких-либо проблем.
Для передачи тела запросов необходимо использовать значение application/json для заголовка Content-Type.
Для тела ответа API может быть использовано одно из следующих значений заголовка Content-Type:
application/json — штатное выполнение операции;
application/problem+json — в случае каких-либо проблем.
Более подробную информацию о кодах ответов и моделях данных можно посмотреть в документации swagger среды Sandbox (см. Среды).
Порядок следования параметров в запросах не важен. Регистр символов в url‑адресах и параметрах запросов — важен.
Ответы API могут содержать поля, не указанные в документации. При обработке ответов такие поля должны игнорироваться клиентским кодом.
Среды
Документация swagger в среде Sandbox: 
Swagger UI
Базовые адреса сред:
Sandbox — https://sandbox.payler.com/fpapi/v1
Production — https://secure.payler.com/fpapi/v1
Коды ошибок сервера
Код
Значение
400
Bad Request
Некорректный запрос
401
Unauthorized
Отказ в авторизации
403
Forbidden
Отказ в обработке запроса
404
Not Found
Данные об операции не найдены
422
Client Error
Логическая ошибка в содержимом запроса
500
Internal Server Error
Внутренняя ошибка сервера
Платежи СБП
Общие сведения
Интерфейс позволяет выполнять операции электронной коммерции по оплате товаров и услуг мерчанта со счетов плательщиков, подключенных к системе СБП.
Платежи через СБП доступны только для мерчантов, использующих для взаимодействия с Payler схему Merchant. На платежной странице Payler выбор оплаты через СБП недоступен.
Подробнее:
Оплата осуществляется только в российских рублях с использованием динамического QR-кода или ссылки. Оплата доступна для клиентов мерчантов на рынке РФ.
В рамках оплаты через СНГБ от клиента не требуется ввод каких-либо платежных данных или авторизация на платежной форме, оплата происходит с использованием мобильного приложения банка клиента, который подключен к СБП. При этом денежные средства со счета клиента на счет мерчанта поступают моментально.
Для подключения данного способа оплаты мерчанту требуется:
Обратиться к персональному менеджеру или в службу технической поддержки Payler.
Заполнить анкету-заявление для регистрации торговой точки в СНГБ и терминала в банке эквайере.
Общий сценарий приема оплаты через СБП:
Клиент выбрал товар или услугу на сайте мерчанта и переходит к оплате.
Мерчант отображает СБП среди прочих доступных методов оплаты.
В зависимости от реализации на стороне мерчанта, клиент выбирает один из вариантов оплаты через СБП:
Отсканировать QR-code;
Перейти в мобильное приложение банка.
Если выбрано «Отсканировать QR-code»:
Браузер направляет запрос в Payler, передавая параметры авторизации и оплаты;
Payler передает QR-code в браузер;
Браузер отображает QR-code;
Клиент сканирует полученный QR-code с экрана;
Клиент оплачивает покупку через мобильное приложение банка, перейдя по ссылке из QR-code.
Если выбрано «Перейти в мобильное приложение банка»:
Браузер отображает страницу с выбором банка;
Клиент оплачивает покупку через мобильное приложение банка, перейдя по ссылке из QR-code.
НСПК оповещает Payler о смене статуса операции.
Payler направляет асинхронное уведомление (callback) о смене статуса мерчанту. Мерчант имеет возможность отправить запрос для отправки callback для получения уведомления о результате выполнения платежа или о финальном статусе операции. Отмена платежа, выполненного через СБП невозможна, доступен только возврат платежа (операция Refund). Возврат возможен только при наличии необходимой суммы с учетом комиссии на счёте мерчанта.
Если клиент после отображения QR-code выбирает иной способ оплаты, а потом снова возвращается к способу оплаты «СБП» (повторно нажимает кнопку СБП), браузер отображает ранее полученный QR-code.
Если в платёжной ссылке перед qr.nspk.ru/AD10007L01CT4Q108V28KD1448SA1L9C подставить «web» и открыть ссылку с мобильного устройства — откроется страница с выбором конкретного банковского приложения.
Типы операций
Тип
Значение
Payment
Платёж
Refund
Возврат платежа
Типы рекуррентного платежа
Тип
Значение
Payment
Привязка к счёту с проведением оплаты
Binding
Привязка к счёту без проведения оплаты
Статусы платежей
Статус
Значение
Created
Платёж создан
Pending
Платёж находится в обработке
Completed
Платёж успешно завершен
CheckCompleted
Проверка выполнена
Failed
Платеж отклонён
Returned
Выполнен полный возврат платежа
Методы API
Получение QR-кода
Метод предназначен для получения QR-кода для оплаты.
URL: /payments/qrcs
Метод: POST
Запрос
Параметры запроса:
Название
Тип
R/O
Описание
orderId
A..100
R
Идентификатор оплачиваемого заказа в системе мерчанта. Для каждого платежа нужен свой уникальный идентификатор. Допускаются только печатные ASCII‑символы
amount
N
R
Сумма в минимальной денежной единице (копейки, центы и т. д.). Если используется recurrentType = “Binding”, то значение должно быть равно 0
redirectUrl
A..1024
R
URL, на который будет перенаправлен пользователь после оплаты. Допускаются только символы в кодировке ASCII. Формат должен соответствовать спецификации RFC-3986
includeImage
B
O
Показывает, требуется ли передать в ответе QR-код в виде картинки
ttlMinutes
N..129600
R
Срок действия платёжной ссылки в минутах. Допустимые значения — от 5 минут до 90 дней (129600 мин)
paymentPurpose
A
R
Назначение (описание) платежа
recurrentPurpose
A
O*
Назначение (описание) рекуррентного платежа *обязателен, если указан recurrentType
recurrentServiceId
A..32
O*
Идентификатор услуги рекуррентного платежа *обязателен, если указан recurrentType
recurrentServiceName
A..70
O*
Наименования услуги рекуррентного платежа *обязателен, если указан recurrentType
Ответ
Параметры ответа:
Название
Тип
R/O
Описание
operationId
А
R
Идентификатор операции
paymentId
А
R
Идентификатор платежа
orderId
А
R
Идентификатор заказа в системе мерчанта
link
А
O
Url перенаправления для выполнения оплаты через мобильное приложение банка
image
А
O
QR-код в виде картинки
operationDate
А
O
Дата и время создания операции. Заполняется для успешной операции
amount
N
R
Сумма в минимальной денежной единице (копейки, центы и т. д.)
createdAt
А
R
Дата и время создания платежной ссылки
errorCode
А
O
Код ошибки. Присутствует если произошла ошибка при обработке запроса
errorMessage
А
O
Текст ошибки. Присутствует если произошла ошибка при обработке запроса
recurrentPublicId
A
O
Идентификатор рекуррентного платежа
Пример:
Возврат платежа по QR-коду
Метод предназначен для возврата суммы платежа, выполненного по QR-коду.
URL: /payments/qrcs/{paymentId}/refunds
Метод: POST
Запрос
Параметры URL:
Название
Описание
paymentId
Идентификатор платежа
Параметры запроса:
Название
Тип
R/O
Описание
amount
N
O
Сумма в минимальной денежной единице (копейки, центы и т. д.), которую следует вернуть. Если не указана, выполняется возврат полной суммы платежа
purpose
A..140
O
Назначение платежа
Ответ
Параметры ответа
Название
Тип
R/O
Описание
status
А
R
Статус операции. Возможные значения: см. Статусы операций Если ответ содержит не финальный статус операции, а ”Pending”, рекомендуется выполнять запрос Получение данных о платеже до получения финального статуса (Completed или Failed)
operationId
А
R
Идентификатор операции
paymentId
А
R
Идентификатор платежа
Пример:
Выполнение рекуррентного платежа
Метод предназначен для выполнения рекуррентного платежа.
URL: /payments/qrcs/recurrents/{recurrentPublicId}/payments
Метод: POST
Запрос
Параметры URL:
Название
Описание
recurrentPublicId
Идентификатор рекуррентного платежа
Запрос
Параметры запроса:
Название
Тип
R/O
Описание
amount
N
R
Сумма рекуррентного платежа в минимальной денежной единице (копейки, центы и т. д.)
Ответ
Параметры ответа:
Название
Тип
R/O
Описание
operationId
А
R
Идентификатор операции
paymentId
А
R
Идентификатор платежа
orderId
А
R
Идентификатор заказа в системе мерчанта
link
А
O
Url перенаправления для выполнения оплаты через мобильное приложение банка
image
А
O
QR-код в виде картинки
operationDate
А
O
Дата и время создания операции. Заполняется для успешной операции
amount
N
R
Сумма в минимальной денежной единице (копейки, центы и т. д.)
createdAt
А
R
Дата и время создания платежной ссылки
errorCode
А
O
Код ошибки. Присутствует если произошла ошибка при обработке запроса
errorMessage
А
O
Текст ошибки. Присутствует если произошла ошибка при обработке запроса
recurrentPublicId
A
O
Идентификатор рекуррентного платежа
Пример:
Изменение рекуррентного платежа
Метод предназначен для изменения рекуррентного платежа.
URL: /payments/qrcs/recurrents/{recurrentPublicId}
Метод: PUT
Запрос
Параметры URL:
Название
Описание
recurrentPublicId
Идентификатор рекуррентного платежа
Запрос
Параметры запроса:
Название
Тип
R/O
Описание
active
B
R
Активность рекуррентного платежа
Ответ
Параметры ответа:
Название
Тип
R/O
Описание
recurrentPublicId
А
R
Идентификатор рекуррентного платежа
isActive
B
R
Активность рекуррентного платежа
Пример:
Получение данных о платеже
Метод предназначен для получения данных о платеже.
URL: /payments/qrcs/{paymentId}
Метод: GET
Запрос
Параметры URL:
Название
Описание
paymentId
Идентификатор платежа
Ответ
Параметры тела ответа:
Название
Тип
R/O
Описание
id
A
R
Идентификатор платежа
orderId
A
R
Идентификатор заказа в системе мерчанта
createdAt
A
R
Дата и время создания платежа
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
operations
Ar
R
Данные операции (см. ниже)
Параметры данных операции:
Название
Тип
R/O
Описание
operationId
A
R
Идентификатор операции
paymentId
А
R
Идентификатор оплаты для повторного запроса статуса
orderId
А
R
Идентификатор заказа
link
А
O
Url перенаправления для выполнения оплаты через мобильное приложение банка
image
А
O
QR-код в виде картинки
operationDate
А
O
Дата и время создания операции. Заполняется для успешной операции
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
createdAt
А
R
Дата и время создания операции
errorCode
А
O
Код ошибки. Присутствует если произошла ошибка при обработке запроса
errorMessage
А
O
Текст ошибки. Присутствует если произошла ошибка при обработке запроса
recurrentPublicId
A
O
Идентификатор рекуррентного платежа
Пример:
Получение списка операций
Метод предназначен для получения списка операций.
URL: /payments/qrcs/{paymentId}/operations
Метод: GET
Запрос
Параметры URL:
Название
Описание
paymentId
Идентификатор платежа
Ответ
В ответе возвращается массив объектов, содержащих данные о платежах.
Параметры данных о платежах:
Название
Тип
R/O
Описание
operationId
A
R
Идентификатор операции
paymentId
А
R
Идентификатор оплаты для повторного запроса статуса
orderId
А
R
Идентификатор заказа
link
А
O
Url перенаправления для выполнения оплаты через мобильное приложение банка
image
А
O
QR-код в виде картинки
operationDate
А
O
Дата и время создания операции. Заполняется для успешной операции
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
createdAt
А
O
Дата и время создания операции
errorCode
А
O
Код ошибки. Присутствует если произошла ошибка при обработке запроса
errorMessage
А
O
Текст ошибки. Присутствует если произошла ошибка при обработке запроса
recurrentPublicId
А
O
Идентификатор рекуррентного платежа
Пример:
Получение данных операции
Метод предназначен для получения данных операции.
URL: /payments/qrcs/{paymentId}/operations/{operationId}
Метод: GET
Запрос
Параметры URL:
Название
Описание
paymentId
Идентификатор сессии при оплате
operationId
Идентификатор операции
Ответ
Параметры ответа:
Название
Тип
R/O
Описание
operationId
A
R
Идентификатор операции
paymentId
А
R
Идентификатор оплаты для повторного запроса статуса
orderId
А
R
Идентификатор заказа
link
А
O
Url перенаправления для выполнения оплаты через мобильное приложение банка
image
А
O
QR-код в виде картинки
operationDate
А
O
Дата и время создания операции. Заполняется для успешной операции
amount
N
R
Сумма в минимальной денежной единице (копейки, центы и т. д.)
createdAt
А
R
Дата и время создания операции
errorCode
А
O
Код ошибки. Присутствует если произошла ошибка при обработке запроса
errorMessage
А
O
Текст ошибки. Присутствует если произошла ошибка при обработке запроса
recurrentPublicId
A
O
Идентификатор рекуррентного платежа
Пример
Выплаты СБП
Общие сведения
Интерфейс позволяет выполнять операции B2С электронной коммерции по переводу средств со счета мерчанта на счета получателей, подключенные к системе СБП.
Роли участников СБП
Роль
Значение
PayoutReceiver
Возможность получения переводов (выплат) средств
Типы выплат
Тип
Описание
Payout
Перевод (выплата) средств
Статусы выплат
Статус
Описание
Created
Выплата зарегистрирована в шлюзе
Pending
Выплата находится в обработке
CheckCompleted
Проверка возможности проведения выплаты выполнена успешно. Выплата может быть выполнена
Completed
Выплата выполнена успешно
Failed
Выплата отклонена
Типы операций
Тип
Значение
CheckPayout
Проверка возможности выполнения перевода средств
Payout
Перевод (выплата) средств
Алгоритм использования
Для проведения выплаты необходимо знать идентификатор участника СБП, в котором находится счет пользователя. Получить идентификатор участника СБП и узнать возможно ли его использовать для выполнения выплаты можно с помощью метода Поиск участника СБП.
Процесс выполнения выплаты состоит их 2-х этапов:
Проверка возможности выполнения, см. Проверка возможности выполнения выплаты;
Выполнение выплаты, см. Выполнение выплаты.
Методы API
Для передачи тела запросов необходимо использовать значение application/json для заголовка Content-Type.
Для тела ответа API может быть использовано одно из следующих значений заголовка Content-Type:
application/json — штатное выполнение операции;
application/problem+json — в случае каких-либо проблем.
Более подробную информацию о кодах ответов и моделях данных можно посмотреть в документации swagger среды Sandbox (см. Среды).
Порядок следования параметров в запросах не важен. Регистр символов в url‑адресах и параметрах запросов — важен.
Ответы API могут содержать поля, не указанные в документации. При обработке ответов такие поля должны игнорироваться клиентским кодом.
Поиск участника СБП
Метод предназначен для поиска участника СБП. Метод позволяет выполнять поиск по названию и поддерживаемой роли. Есть возможность контролирования получения данных логотипа (если они присутствуют).
URL: /members
Метод: GET
Запрос
Параметры строки запроса:
Название
Тип
R/O
Описание
name
А
О
Название участника
includeLogo
В
О
Индикатор получения логотипа. По умолчанию — false
Ответ
В ответе возвращается массив объектов, содержащих данные найденных участников СБП.
Параметры данных участника СБП:
Название
Тип
R/O
Описание
id
A
R
Идентификатор участника СБП
name
A
R
Название участника СБП
logo
O
O
Логотип участника СБП
Параметры данных логотипа:
Название
Тип
R/O
Описание
content
A
R
Содержимое. Строка в формате Base64
contentMediaType
A
R
Тип содержимого
Пример:
Получение данных участника СБП
Метод предназначен для получения данных участника СБП. Есть возможность контроля получения данных логотипа (если они присутствуют).
URL: /members/{memberId}
Метод: GET
Запрос
Параметры URL:
Название
Описание
memberId
Идентификатор участника СБП
Параметры строки запроса:
Название
Тип
R/O
Описание
includeLogo
B
O
Индикатор получения логотипа. По умолчанию — false
Ответ
В ответе возвращается объект, содержащий данные участника СБП.
Параметры данных участника СБП:
Название
Тип
R/O
Описание
id
A
R
Идентификатор участника СБП
name
A
R
Название участника СБП
logo
O
O
Логотип участника СБП
Параметры данных логотипа:
Название
Тип
R/O
Описание
content
A
R
Содержимое. Строка в формате Base64
contentMediaType
A
R
Тип содержимого
Пример:
Проверка возможности выполнения выплаты
Метод предназначен для выполнения проверки возможности выполнения выплаты с указанными параметрами.
URL: /payouts/check
Метод: POST
Запрос
Параметры тела запроса:
Название
Тип
R/O
Описание
orderId
A..100
R
Идентификатор заказа
phone
A..50
R
Номер телефона получателя
memberId
A
R
Идентификатор участника СБП
amount
N
R
Сумма в минимальной денежной единице (копейки, центы и т. д.)
currency
A3
R
Валюта перевода. Только RUB
reference
A..100
O
Значение для отслеживания
purpose
A
O
Назначение
nameCheck
B
O
Индикатор проверки ФИО получателя.
Если передано значение true, то для успешного прохождения проверки будет требоваться совпадение переданного ФИО получателя с данными банка.
По умолчанию — false
nameFirst
A..100
O
Имя получателя
nameMiddle
A..100
O
Отчество получателя
nameLast
A..100
O
Фамилия получателя
Ответ
Параметры тела ответа:
Название
Тип
R/O
Описание
payoutId
A
R
Идентификатор выплаты
orderId
A
R
Идентификатор заказа. Соответствует переданному в запросе
operationId
A
R
Идентификатор операции
reference
A
O
Значение для отслеживания
phone
A
R
Номер телефона получателя
pam
A
O
РАМ получателя (Ф. И. О., первая буква фамилии)
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
createdAt
A
R
Дата и время создания операции
errorCode
A
O
Код ошибки
errorMessage
A
O
Сообщение с описанием ошибки
Пример:
Выполнение выплаты
Метод предназначен для выполнения выплаты после успешного проведения проверки возможности выполнения.
Выплата может быть проведена не позднее, чем через 3 минуты после успешного завершения проверки.
URL: /payouts/{payoutId}
Метод: POST
Запрос
Параметры URL:
Название
Описание
payoutId
Идентификатор выплаты
Параметры тела запроса:
Название
Тип
R/O
Описание
reference
A..100
O
Значение для отслеживания
Ответ
Параметры тела ответа:
Название
Тип
R/O
Описание
payoutId
A
R
Идентификатор выплаты
orderId
A
R
Идентификатор заказа. Соответствует переданному в запросе
operationId
A
R
Идентификатор операции
reference
A
O
Значение для отслеживания
phone
A
R
Номер телефона получателя
pam
A
O
РАМ получателя (Ф. И. О., первая буква фамилии)
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
createdAt
A
R
Дата и время создания операции
errorCode
A
O
Код ошибки
errorMessage
A
O
Сообщение с описанием ошибки
Пример:
Получение данных выплаты
Метод предназначен для получения данных выплаты.
URL: /payouts/{payoutId}
Метод: GET
Запрос
Параметры URL:
Название
Описание
payoutId
Идентификатор выплаты
Ответ
Параметры тела ответа:
Название
Тип
R/O
Описание
id
A
R
Идентификатор выплаты
orderId
A
R
Идентификатор заказа
createdAt
A
R
Время создания операции
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
currencyCode
A
R
Валюта. Только RUB
rest
N
R
Остаток
operations
Ar
R
Операции
Параметры данных операции:
Название
Тип
R/O
Описание
id
A
R
Идентификатор операции
phone
A
R
Номер телефона получателя
reference
A
O
Значение для отслеживания
pam
A
O
РАМ получателя (Ф. И. О., первая буква фамилии)
Пример:
Получение списка операций
Метод предназначен для получения списка операций.
URL: /payouts/{payoutId}/ operations
Метод отправки: GET
Запрос
Параметры URL:
Название
Описание
payoutId
Идентификатор выплаты
Ответ
В ответе возвращается массив объектов, содержащих данные операций выплаты.
Параметры данных операции:
Название
Тип
R/O
Описание
payoutId
A
R
Идентификатор выплаты
orderId
A
R
Идентификатор заказа
operationId
A
R
Идентификатор операции
reference
A
O
Значение для отслеживания
phone
A
R
Номер телефона получателя
pam
A
O
РАМ получателя (Ф. И. О., первая буква фамилии)
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
createdAt
A
R
Дата и время создания операции
errorCode
A
O
Код ошибки
errorMessage
A
O
Сообщение с описанием ошибки
Пример:
Получение данных операции
Метод предназначен для получения данных операции.
URL: payouts/{payoutId}/operations/{operationId}
Метод: GET
Запрос
Параметры URL:
Название
Описание
payoutId
Идентификатор выплаты
operationId
Идентификатор операции
Ответ
Параметры тела ответа:
Название
Тип
R/O
Описание
payoutId
A
R
Идентификатор выплаты
orderId
A
R
Идентификатор заказа
operationId
A
R
Идентификатор операции
reference
A
O
Значение для отслеживания
phone
A
R
Номер телефона получателя
pam
A
O
РАМ получателя (Ф. И. О., первая буква фамилии)
amount
N
R
Сумма операции в минимальной денежной единице (копейки, центы и т. д.)
createdAt
A
R
Дата и время создания операции
errorCode
A
O
Код ошибки
errorMessage
A
O
Сообщение с описанием ошибки
Пример
Получение баланса
Метод предназначен для получения баланса.
URL: /payouts/balance
Метод отправки: GET
Ответ
Параметры тела ответа:
Название
Тип
R/O
Описание
balance
N
R
Значение баланса в минимальной денежной единице
currency
A3
R
Валюта счета
Пример
Last updated