Перейти к основному содержимому

СБП — Система быстрых платежей

Оплата через QR-коды — это замена интернет-эквайрингу, которая позволяет вам получать оплату от физлиц и экономить на банковских комиссиях.
Вы можете зарегистрировать вашу торговую точку в Системе быстрых платежей, генерировать QR-коды и делать возвраты через API.

Для работы с Системой быстрых платежей должны быть выданы разрешения EditSBPData ReadSBPData.

Немного определений​

Динамический QR-код — одноразовый QR-код с уникальным идентификатором.
По этому коду можно принять оплату только один раз, и сумма платежа прописывается при создании.
По умолчанию срок действия динамического QR-кода составляет 72 часа, но его можно увеличить или уменьшить, поменяв время в минутах в параметре ttl.

Кассовый QR-код — подтип статического QR-кода, имеющий признаки динамического QR-кода. При создании кассовой ссылки создаётся идентификатор QR-кода, по которому можно проводить неограниченное количество оплат.
После каждой оплаты продавцу будет необходимо активировать ссылку заново.
Срок действия кассового QR-кода по умолчанию 5 минут. Если передать атрибут ttl, его можно увеличить до 20 минут.

Статический QR-код — многоразовый QR-код с одним идентификатором. Код действует бессрочно и по нему можно провести неограниченное количество оплат.
Статический QR-код можно создать с указанием цены — покупатели будут платить только указанную сумму. Или вы можете при создании QR-кода не задавать сумму оплаты: тогда она сможет быть разной при каждой операции, но покупателю придётся вводить её вручную.

B2B QR-код — одноразовый QR-код с уникальным идентификатором, который используется для приёма платежей исключительно от ИП и организаций.
Каждый такой код уникальный: принять платёж на сумму, указанную при его создании, можно только один раз.
По умолчанию B2B QR-код действует 72 часа, но срок можно увеличить или уменьшить, указав время в минутах в параметре ttl.

ТСП — это торгово-сервисное предприятие, то есть магазины или иные торговые точки.

legalId — уникальный идентификатор юрлица в Системе быстрых платежей.

merchantId — уникальный идентификатор ТСП в Системе быстрых платежей.

accountId — номер счёта и БИК через слеш, например 40802810802000000008/044525104.

Как зарегистрировать юрлицо и торговые точки​

Чтобы проверить, зарегистрирована ли ваша компания в Системе быстрых платежей, вызовите метод Get Customer Info.
Если регистрация в СБП есть, вам останется только получить информацию о legalId и merchantId и приступить к работе.

Если регистрации в СБП нет, пройдите её и создайте торговую точку одним из следующих методов:

В запросе необходимо передать:

  • customerCode — уникальный код клиента;
  • bankCode — БИК банка. У Точки это 044525104.

При регистрации в СБП юрлицу присваивается уникальный идентификатор — legalId.

Регистрация нового ТСП через метод Register Merchant.​

В запросе необходимо передать:

  • legalId — идентификатор зарегистрированного юрлица в СБП;
  • address — юридический адрес компании или адрес ТСП;
  • city — город, в котором находится ТСП;
  • countryCode — нужно указать RU;
  • countrySubDivisionCode — код региона-регистрации юридического лица, это первые две цифры кода ОКТМО;
  • zipCode — индекс;
  • brandName — название ТСП;
  • capabilities — возможности ТСП по формированию QR-кодов:
    • 001 — возможность формировать только статические QR-коды;
    • 010 — возможность формировать только динамические QR-коды;
    • 011 — возможность формировать только статические и динамические QR-коды;
    • 100 — возможность формировать только кассовые QR-коды;
    • 101 — возможность формировать только статические и кассовые QR-коды;
    • 110 — возможность формировать только динамические и кассовые QR-коды;
    • 111 — возможность формировать статические, динамические и кассовые QR-коды.
  • mcc — MCC-код, соответствующий вашей деятельности.

Мы рекомендуем указывать capabilities — 111, чтобы вам не пришлось заново проводить регистрацию ТСП, если потребуется работать с другим типом QR-кодов.
Также можно добавить contactPhoneNumber — номер телефона ТСП.

После регистрации ТСП каждой торговой точке присваивается уникальный идентификатор — merchantId.
Чтобы получить список всех ТСП и информацию по ним можно вызвать метод: Get Merchants List.

Регистрация юрлица или ТСП в СБП через Точку​

Зарегистрировать юрлицо и создать торговую точку можно в интернет-банке Точки — раздел «QR-платежи»..
Раздел доступен только руководителю и распорядителю с правом подписи.

Как сгенерировать статические и динамические QR-коды

QR-коды нужны для получения оплат от физлиц. Их можно сформировать только для торговых точек, которые уже зарегистрированы в СБП.

Для регистрации динамического или статического QR-кода выполните запрос: Register Qr Code.

В запросе необходимо передать:

  • accountId — уникальный и неизменный идентификатор счёта юрлица.
  • merchantId — идентификатор ТСП.
  • paymentPurpose — назначение платежа. Покупатель его увидит при считывании QR-кода.
  • amount — сумма платежа в копейках. Обязательно при создании динамических QR-кодов, для статических QR-кодов данное поле можно не заполнять.
  • qrcType — тип запрашиваемого QR-кода:
    • qrcType: 01 — статический QR-код;
    • qrcType: 02 — динамический QR-код.
  • imageParams — параметры изображения:
    • width — ширина изображения (>=200, по умолчанию: 300);
    • height — высота изображения (>=200, по умолчанию: 300).

При создании статических и динамических QR-кодов можно указать дополнительные поля:

  • currency — валюта операции. На данный момент можно указать только RUB.
  • sourceName — название вашей интеграции. Эту информацию покупатель не увидит, можно указывать для аналитики.
  • ttl — время действия QR-кода в минутах, можно указать от 1 до 129 600 минут. Данный параметр есть только для динамических QR-кодов. Если при создании динамического QR-кода не передать этот параметр, его срок действия составит 72 часа.
  • redirectUrl — это ссылка в формате https, перенаправляющая пользователя на выбранную страницу после проведения оплаты.

Если ваши клиенты оплачивают покупки через приложение, удобнее перенаправлять их по ссылке для оплаты, а не показывать изображение QR-кода.
Для этого в ответе метода Register Qr Code мы передаём атрибут payload.

Статус динамического QR-кода можно отследить с помощью метода Get Qr Codes Payment Status в течение периода использования QR-кода или 24 часов с момента оплаты. По истечению этого времени узнать статус не получится.
Для статических QR-кодов статус отследить не получится, так как этот QR-код всегда активен.

Как сгенерировать кассовые QR-коды

QR-коды нужны для получения оплат от физлиц. Их можно сформировать только для торговых точек, которые уже зарегистрированы в СБП.

Для регистрации кассового QR-кода выполните запрос: Register Cashbox Qrcode

В запросе необходимо передать:

  • accountId — уникальный и неизменный идентификатор счёта юрлица;
  • merchantId — идентификатор ТСП;
  • imageParams — параметры изображения:
    • width — ширина изображения (>=200, по умолчанию: 300);
    • height — высота изображения (>=200, по умолчанию: 300).

Дополнительно можно указать redirectUrl — это ссылка в формате https, перенаправляющая пользователя на выбранную страницу после проведения оплаты.

Из ответа необходимо забрать и сохранить следующие параметры:

  • qrcId — идентификатор QR-кода;
  • payload — ссылка для перенаправления пользователей;
  • image — изображение QR-кода.
    Эти параметры закрепляются для кассовой ссылки.

Чтобы принимать оплату по QR-коду, его нужно каждый раз активировать с помощью метода: Activate Cashbox Qrcode.
В запросе необходимо передать:

  • qrcId — идентификатор QR-кода, полученный в методе Register Cashbox Qrcode;
  • amount — сумма платежа в копейках.

Дополнительно в запросе можно указать:

  • currency — валюта операции. На данный момент можно указать только RUB.
  • paymentPurpose — назначение платежа. Покупатель его увидит при считывании QR-кода.
  • ttl — время действия QR-кода в минутах, можно указать от 5 до 20 минут. Если не передавать этот параметр, кассовый QR-код по умолчанию будет действовать 5 минут.
    Когда вы активируете QR-код, покупатель сможет провести оплату. После оплаты или по истечению ttl, QR-код деактивируется — необходимо вызвать метод Activate Cashbox Qrcode заново.

Если покупатель передумал совершать оплату или больше нет необходимости в активном QR-коде, можно вручную вызвать метод на деактивацию QR-кода: Deactivate Cashbox Qrcode.

При работе с кассовыми QR-кодами есть возможность изменить расчётный счёт для зачисления денег — но в рамках одной компании. Изменить расчётный счёт одной компании на счёт другой не получится.

Для изменения счёта необходимо вызвать метод Change Cashbox Qrcode Account и передать следующие параметры:

  • qrcId — идентификатор QR-кода, полученный в методе Register Cashbox Qrcode;
  • accountId — уникальный и неизменный идентификатор счёта юрлица.

Чтобы посмотреть информацию обо всех выпущенных кассовых QR-кодах, вызовите метод Get Cashbox Qrcode List.
Чтобы посмотреть информацию по конкретному кассовому QR-коду, вызовите метод Get Cashbox Qrcode.
Обратите внимание, что необязательные параметры передаются, только когда QR-код активен — по нему ещё не прошла оплата или ещё не закончился ttl.

Как сгенерировать B2B QR-коды

B2B QR-коды нужны для приёма платежей от ИП и организаций. Формировать их можно только для торговых точек, которые уже зарегистрированы в СБП.

Для регистрации B2B QR-кода выполните запрос Register B2B Qr Code с такими параметрами:

  • accountId — уникальный и неизменный идентификатор счёта юрлица;
  • merchantId — идентификатор торговой Точки в СБП (ТСП);
  • paymentPurpose — назначение платежа, которое покупатель увидит при считывании QR-кода;
  • amount — сумма платежа в копейках. Максимальная сумма для B2B QR-кода составляет 1 миллион рублей;
  • sourceName — название вашей интеграции. Покупатель его не увидит, можно указывать для аналитики;
  • takeTax — информация об НДС (True — для получения платежей с НДС, false — без НДС).

При создании B2B QR-кодов можно указать дополнительные параметры:

  • totalTaxAmount — сумма НДС в копейках. Необходимо, если в параметре takeTax стоит true.
  • ttl — время действия QR-кода в минутах, можно указать от 1 до 129 600 минут. Если при создании QR-кода не передать этот параметр, его срок действия составит 72 часа.
  • redirectUrl — ссылка в формате https, на которую нужно перенаправить пользователя после проведения оплаты.
  • uip — назначаемый получателем уникальный идентификатор платежа.

Чтобы посмотреть информацию по конкретному B2B QR-коду, вызовите метод Get B2B Qr Code.

Чтобы сразу узнать о поступлении оплаты, вы можете настроить вебхук с событием incomingSbpB2BPayment на свой URL.

Возврат через СБП​

На данный момент вернуть платежи поступившие через СБП можно только по динамическим QR-кодам.
Платежи по статическим, кассовым и B2B QR-кодам возвращаются через интернет-банк Точки.

Принятые по QR-кодам платежи в статусе Accepted можно возвращать покупателю через Систему быстрых платежей.

Возврат может быть как полным, так и частичным. Главное — чтобы его сумма не превышала сумму поступления на расчётный счёт.

  1. Получите refTransactionId

  • Если у вас подключён вебхук с событием incomingSbpPayment, то параметр -refTransactionId- мы передадим при зачислении денег.

  • Если у вас нет подключённого вебхука с событием incomingSbpPayment, используйте метод Get Payments — он найдёт платёж, который нужно вернуть.

В запросе укажите необходимый промежуток времени через поля fromDate и toDate. Период поиска не ограничен, но удобнее искать за день, неделю или месяц — в зависимости от того, что сообщил покупатель.
Для фильтрации можете указать qrcId и page.

В ответе вам нужно взять параметры refTransactionId и qrcId — идентификатора QR-кода в СБП.

  1. Вызовите метод Start Refund — он отправляет запрос на возврат платежа по СБП. Укажите в запросе
  • accountCode и bankCode — это счёт и БИК вашей компании, то есть плательщика, со счёта которого происходит возврат.
  • amount — сумма возврата. Указывается в рублях, а не копейках.
  • qrcId — идентификатор QR-кода по которому зачислились деньги.
  • purpose — назначение платежа — можно не заполнять, если ваш покупатель резидент РФ. Если платёж нужно вернуть нерезиденту, обязательно заполните поле кодом валютной операции {VO99020}.
  1. Отследите статус возврата платежа с помощью метода Get Refund Data .
    Финальный успешный статус — Accepted. Если возврат не прошёл, будет статус Rejected.