Не отправляйте всю сумму на первую найденную карту. Откройте историю оплаты заказа и выпишите каждое «плечо»: карта, подарочный сертификат, внутренний баланс, бонусы. Для каждого сохраните исходную сумму, валюту, внешний 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 refund | Refund 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. Компенсирующая операция нужна только после достоверного результата, не после отсутствия ответа.
- Зафиксировать allocation и operation IDs до первого внешнего вызова.
- Создать операции по плечам с идемпотентными ключами.
- Сохранить provider IDs и ответы отдельно, не затирая историю попыток.
- При unknown запросить фактический объект у провайдера.
- Закрыть бизнес-возврат после сверки общей суммы и всех состояний.
Контрольный сценарий включает повторный возврат
В тестовом окружении оплатите один заказ двумя способами, сделайте частичный возврат, оборвите ответ карточного API и повторите команду. Должны появиться ровно одна карточная операция и одно восстановление сертификата. Затем выполните второй частичный возврат: алгоритм использует оставшиеся лимиты обоих плеч.
Для разбора подготовьте обезличенный список payment legs, правило allocation, суммы в minor units, operation/provider IDs и статусы. Полные номера карт, коды сертификатов и API secrets не нужны. Этого достаточно, чтобы отделить ошибку расчёта от потерянного ответа или неверного статуса.