Оплата через QR-терминал#

Отдельный сценарий оплаты партнёрам, предоставляющим платёжные терминалы субпартнёрам. Для стандартной интеграции используйте методы из описания API.

Термины#

Термин

Описание

Магазин-Партнёр

Банк-партнёр, который предоставляет субпартнёрам терминалы для приёма оплаты

Субпартнёр

Продавец, который пользуется терминалами банка-партнёра. Идентифицируется логином (MID)

Терминал

Устройство, на котором Клиент оплачивает покупку в магазине Субпартнёра. Идентифицируется параметром terminalId (TID)

Процесс покупки#

  1. Клиент в офлайн-магазине Субпартнёра сообщает кассиру об оплате через QR-терминал.

  2. Кассир выбирает на терминале способ оплаты «Подели» — терминал вызывает метод CREATE_TERMINAL.

  3. В «Подели» создаётся заказ (статус CREATED); в ответе метода терминал получает ссылку redirectUrl.

  4. Терминал формирует из полученной ссылки QR-код и периодически опрашивает статус заказа методом INFO до перехода заказа в терминальный статус.

  5. Клиент сканирует QR-код и переходит на страницу оформления заказа «Подели» — запускается скоринг (статус SCORING).

  6. При одобрении (статус APPROVED) Клиент оплачивает первый платёж; заказ переходит в статус COMPLETED — товар можно выдавать.

Статусная модель совпадает с офлайн-сценарием — см. статусную модель заказа.

CREATE_TERMINAL — создание заказа на терминале#

POST https://api-sand.podeli.ru/partners/v1/orders/create_terminal

Заголовки запроса

Все заголовки обязательны.

Заголовок

Тип

Описание

Content-Type

string

Тип контента: application/json

Authorization

base64

Basic Auth: логин и пароль Магазина-Партнёра в формате логин:пароль, закодированные в base64

X-Correlation-ID

string(36)

Идентификатор запроса в формате UUID v4. Для каждого нового HTTP-запроса передавайте новое значение

Параметры запроса

Поле

Тип

Обяз.

Описание

subpartnerInfo

object

✓

Субпартнёр

└─ login

string

✓

Логин субпартнёра (MID)

order

object

✓

Заказ

├─ amount

number(18,2)

✓

Сумма для оплаты через «Подели», в рублях с точностью до двух знаков

├─ prepaidAmount

number(18,2)

—
Сумма аванса, внесённого Клиентом через другие способы оплаты, в рублях

с точностью до двух знаков

├─ isTwoStagePayment

boolean

✓
Схема оплаты первого платежа. Для терминального сценария передавайте

false (одностадийный платёж)

├─ latitude

number

—

Широта

├─ longitude

number

—

Долгота

├─ mall

string

—

Торговый центр

├─ address

string

—

Адрес магазина

├─ cashRegisterNumber

string

—

Номер кассы

├─ cashierNumber

string

—

Номер кассира

└─ comment

string

—

Комментарий

terminalId

string(36)

✓

Идентификатор терминала (TID)

comment1

string(500)

—

Комментарий Магазина-Партнёра

comment2

string(500)

—

Комментарий Магазина-Партнёра

Заголовки ответа

Заголовок

Тип

Описание

X-Correlation-ID

string

Идентификатор исходного запроса (для связи ответных сообщений)

Тело ответа

Поле

Тип

Обяз.

Описание

order

object

✓

Заказ

└─ id

string

✓

Идентификатор заказа. Уникален в рамках партнёра

redirectUrl

string

✓
Ссылка-редирект на страницу сервиса «Подели» — используется для формирования

QR-кода на терминале

error

object

—

Описание ошибки (поля code, text)

Примеры

{
  "subpartnerInfo": {
    "login": "submerchant_01"
  },
  "order": {
    "amount": 5000.00,
    "prepaidAmount": 0.0,
    "isTwoStagePayment": false,
    "mall": "ТРЦ Сити Молл",
    "address": "ул. Первая, 5",
    "cashRegisterNumber": "1234567890",
    "cashierNumber": "0987654321"
  },
  "terminalId": "1234"
}

{
  "order": {
    "id": "937c7802-5c24-4a4b-81af-1837e8be2a23"
  },
  "redirectUrl": "https://pokupka-sand.podeli.ru/login?guid=2add8220-0da6-4ef0-94d5-854ca4f920d8&amountAll=5000.0&amountFirst=1250.00&flowId=1"
}

Статус-коды и коды ошибок метода

Код

Код ошибки

Значение

200

—

Заявка создана

400

invalid_request

Ошибка валидации тела/параметров запроса (в т.ч. пустое значение X-Correlation-ID)

401

not_authorized_partner_login, not_authorized_partner_expired

Аутентификация не пройдена: неверный логин/пароль, партнёр отключён или истёк срок договора

422

—

Ошибка бизнес-логики: в текущем состоянии заявки нельзя выполнить это действие

429

req_number_exceeded

Превышен лимит запросов к серверу

500

unknown_error

Неизвестная ошибка

Формат ошибки

При ошибке тело ответа содержит объект error с полями code (код ошибки) и text (текст ошибки):

{
  "error": {
    "code": "not_authorized_partner_login",
    "text": "Ошибка аутентификации: неверный логин/пароль"
  }
}

Особенности терминального сценария#

  • Опрос статуса. После вызова CREATE_TERMINAL опрашивайте статус заказа методом INFO до перехода заказа в терминальный статус.

  • Возврат. При оформлении возврата методом REFUND обязательно передавайте в секции order/refund/addParams параметры с ключами MID (логин субпартнёра) и TID (идентификатор терминала) — без них метод вернёт ошибку none_additional_params (422). Если MID в возврате не совпадает с MID в заказе, метод вернёт ошибку not_allowed_refund_order (422) — заказ принадлежит другому субпартнёру. Идентификатор возврата формируется на стороне «Подели», поле order/refund/id передавать не требуется.

  • Отмена. Заказ отменяется стандартным методом CANCEL.