Протокол взаимодействия#

Раздел описывает порядок вызова методов API при оплате заказа через «Подели».

Поддерживаются два сценария:

  • Онлайн — Клиент оформляет заказ на сайте или в приложении Магазина-Партнёра.

  • Офлайн — Клиент оплачивает покупку на кассе по QR-коду.

Названия методов и статусов см. в описании API и статусной модели. Операции получения информации, отмены и возврата выполняются одинаково для обоих сценариев.

Онлайн-покупка#

Заказ создаётся методом CREATE. Тип оплаты определяется параметром order.isTwoStagePayment:

Значение

Схема оплаты

false

Одностадийная — первый платёж списывается сразу после одобрения заказа.

true

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

Одностадийная оплата#

После создания заказа участие Магазина-Партнёра не требуется — остаётся дождаться нотификации об оплате.

Последовательность работы:

  1. Создайте заказ методом CREATE, указав order.isTwoStagePayment = false.

  2. Перенаправьте Клиента на URL, полученный в ответе метода.

  3. В случае одобрения оплаты на URL, указанный в notificationUrl при вызове CREATE, придёт HTTP-нотификация со статусом APPROVED.

  4. После успешного списания первого платежа придёт HTTP-нотификация со статусом COMPLETED. Заказ считается успешно оплаченным.

Двухстадийная оплата#

При двухстадийной оплате первый платёж резервируется на карте Клиента, а фактическое списание выполняется только после подтверждения заказа Магазином-Партнёром. Такая схема рекомендуется, если состав заказа может измениться после оформления (например, отсутствует часть товара при сборке).

Последовательность работы:

  1. Создайте заказ методом CREATE, указав order.isTwoStagePayment = true.

  2. Перенаправьте Клиента на URL, полученный в ответе метода CREATE.

  3. В случае одобрения на URL, указанный в notificationUrl при вызове CREATE, придёт HTTP-нотификация со статусом APPROVED.

  4. Затем придёт HTTP-нотификация со статусом WAIT_FOR_COMMIT — первый платёж захолдирован и ожидает подтверждения от Магазина-Партнёра.

  5. Подтвердите оплату методом COMMIT. Если состав корзины изменился (не все позиции попали в итоговый заказ), передайте в COMMIT секцию order/items с подтверждёнными позициями. На этом же этапе заказ можно отменить методом CANCEL.

  6. После успешного подтверждения заказа придёт HTTP-нотификация со статусом COMPLETED. В этом статусе заказ считается успешно оплаченным.

Офлайн-покупка (по QR-коду)#

Сценарий для оплаты на кассе офлайн-магазина. Заказ создаётся методом CREATE_OFFLINE. Офлайн-заказы всегда оформляются по одностадийной схеме оплаты.

Последовательность работы:

  1. Клиент показывает QR-код из приложения «Подели».

  2. Кассир сканирует QR-код. ПО кассы извлекает из него external_id Клиента и вызывает метод CREATE_OFFLINE.

  3. В системе «Подели» создаётся заказ и запускается скоринг.

  4. При успешном скоринге заказ переходит в статус APPROVED, после чего Клиент оплачивает первый платёж в приложении.

  5. Опрашивайте статус заказа методом INFO с интервалом не более 10 секунд до перехода заказа в финальный статус (COMPLETED или REJECTED).

  6. После получения статуса COMPLETED выдайте товар и сформируйте кассовый чек на полную сумму заказа.

Работа с заказом#

Описанные ниже операции работают одинаково и для онлайн-, и для офлайн-заказов.

Получение информации по заказу#

Для получения актуального состояния заказа используйте метод INFO.

Время жизни заказа#

Неоплаченный заказ имеет ограниченный срок жизни, установленный для Магазина-Партнёра. По умолчанию срок жизни заказа составляет 6 часов. Если за это время заказ не перешёл в статус COMPLETED (например, Магазин-Партнёр не подтвердил оплату при двухстадийной схеме), он автоматически отменяется.

При этом:

  • на notificationUrl отправляется HTTP-нотификация CANCELLED;

  • затем заказ автоматически переходит в финальный статус REJECTED.

Отмена заказа#

До списания денежных средств заказ можно отменить методом CANCEL.

Отмена доступна в статусах:

  • CREATED

  • SCORING

  • APPROVED

  • WAIT_FOR_COMMIT

После отмены:

  • заказ закрывается;

  • резерв средств (если был создан) снимается.

Результат операции возвращается синхронно в ответе метода, HTTP-нотификация не отправляется.

Примечание

Если платёж находится в обработке, отмена заказа в статусе APPROVED может быть временно недоступна. В этом случае метод CANCEL вернёт HTTP-код 423. Повторите запрос позднее или дождитесь изменения статуса заказа.

Возврат#

Для оформления возврата по оплаченному заказу используйте метод REFUND.

В запросе перечислите возвращаемые товары в секции order.refund.items.

Итоговая сумма возврата рассчитывается автоматически как сумма всех возвращаемых позиций.

Внимание

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

Пример. Заказ на 4000 ₽, Клиент внёс первый платёж 1000 ₽ — остаются три платежа по 1000 ₽. Магазин-Партнёр оформляет возврат на 900 ₽: каждый из оставшихся платежей уменьшается на 300 ₽.

Платёж

До возврата

После возврата

1-й — оплачен

1000 ₽

без изменений

2-й

1000 ₽

700 ₽

3-й

1000 ₽

700 ₽

4-й

1000 ₽

700 ₽