Не отправляйте всю сумму на первую найденную карту. Откройте историю оплаты заказа и выпишите каждое «плечо»: карта, подарочный сертификат, внутренний баланс, бонусы. Для каждого сохраните исходную сумму, валюту, внешний transaction ID и уже возвращённый остаток.

Дальше нужна одна явная политика распределения. Например, магазин сначала восстанавливает подарочный баланс, а остаток возвращает на карту; другой бизнес распределяет возврат пропорционально строкам. Оба варианта возможны, но правило должно быть зафиксировано до расчёта и одинаково работать в UI, учёте и интеграции.

Заказ состоит из нескольких платёжных плеч

order_paid = 12000 RUB
legs:
  card:        captured 8000, refunded 0
  gift_card:   captured 3000, restored 0
  loyalty:     captured 1000, restored 0

requested_refund = 5000 RUB
policy = gift_card first, then card; loyalty follows returned items
result = gift_card 3000 + card 2000

Это условный расчёт, а не универсальный порядок для всех магазинов. Он показывает структуру: один бизнес-возврат создаёт две независимые операции. Возврат по карте идёт через платёжного провайдера, восстановление gift card — через внутренний ledger. У них разные идентификаторы, сроки и причины failure.

Способ возврата следует за исходной оплатой

Stripe указывает, что возврат отправляется на исходный payment method конкретного charge. Нельзя взять карточный refund и направить его на произвольную другую карту. Shopify также предупреждает: если заказ оплачен несколькими способами, сумма может быть разделена между исходными методами.

Внутренний сертификат или бонусный счёт не становятся банковским возвратом автоматически. Их восстановление — отдельная компенсация с собственной записью. Если бизнес разрешает заменить сертификат деньгами, оформите это как явное исключение с правом оператора и аудиторским следом, а не как скрытую ветку общего алгоритма.

Таблица состояний не даёт потерять одно плечо

ПлечоОперацияКритерий завершения
Банковская картаProvider refundRefund object имеет terminal success
Подарочная картаCredit в ledger сертификатаБаланс увеличен один раз
БонусыКомпенсирующая записьПолитика возврата выполнена по строкам
РассрочкаОперация у конкретного провайдераПодтверждён новый график или refund
Наличные/POSКассовый и операционный процессЕсть подтверждённая выдача и документ

Общий return.status становится completed только когда каждое обязательное плечо достигло допустимого конечного состояния. Состояние «card succeeded, gift pending» должно оставаться частично выполненным. Иначе оператор сообщит клиенту о полном возврате, хотя внутренний баланс ещё не восстановлен.

Расчёт защищают четыре инварианта

  • Сумма компенсаций по плечу не превышает captured amount этого плеча.
  • Сумма всех новых компенсаций равна утверждённой refundable amount заказа.
  • Каждая операция имеет стабильный business ID и выдерживает безопасный повтор.
  • Повторный частичный возврат учитывает уже completed и pending суммы, а не только success.

Не распределяйте округлённый процент независимо по каждому способу: сумма может разойтись на минимальную денежную единицу. Сначала считайте точные доли, затем назначьте остаток одному детерминированному плечу и сохраните результат расчёта. При повторе используйте сохранённое распределение, а не пересчитывайте его заново.

Сетевой таймаут не означает неуспех

Если карточный API не ответил, а gift card уже восстановлена, rollback второго шага способен создать новую ошибку: банковский refund мог всё-таки пройти. Пометьте карточное плечо unknown и выполните reconciliation по provider transaction ID. Компенсирующая операция нужна только после достоверного результата, не после отсутствия ответа.

  1. Зафиксировать allocation и operation IDs до первого внешнего вызова.
  2. Создать операции по плечам с идемпотентными ключами.
  3. Сохранить provider IDs и ответы отдельно, не затирая историю попыток.
  4. При unknown запросить фактический объект у провайдера.
  5. Закрыть бизнес-возврат после сверки общей суммы и всех состояний.

Контрольный сценарий включает повторный возврат

В тестовом окружении оплатите один заказ двумя способами, сделайте частичный возврат, оборвите ответ карточного API и повторите команду. Должны появиться ровно одна карточная операция и одно восстановление сертификата. Затем выполните второй частичный возврат: алгоритм использует оставшиеся лимиты обоих плеч.

Для разбора подготовьте обезличенный список payment legs, правило allocation, суммы в minor units, operation/provider IDs и статусы. Полные номера карт, коды сертификатов и API secrets не нужны. Этого достаточно, чтобы отделить ошибку расчёта от потерянного ответа или неверного статуса.

Проверенные источники