Merit · OMS · Proposal · 7 Oct 2026
When one seller cancels one item of a multi-item order, the customer must get back that item's value only. No rail in our chain can do that today. This page shows the end goal, the rules that never change, and four phases. Phase 1 needs only OMS work.
An order can mix card, Merit points and, for Al Fursan, Miles. Each rail has a different owner, and none can return part of a payment today.
Moyasar's API accepts a partial amount. Our Payment Service Refund API is full order only; partial amounts are deferred. More than one refund per payment is not confirmed. 30-day window.
Payment Service · HamdPost-commit refund returns the whole authorisation. No partial amount.
TamerInterim adapter is being built now. Comarch's refund call takes reward lines with quantity and points, so partial looks possible. Not tested.
E-Commerce adapter, then PX · HabeebPay with wallet works, single leg only. Wallet credit and wallet refund are not built.
Payment ServiceA person at the seller cancels the item in the portal, before shipment.
reason code SELLER_CANCELLED (proposed)The seller's system rejects or cancels the item, or the fulfilment call fails for good.
reason code SELLER_API_CANCELLED (proposed)Legacy avoids this with one item per order. We do not copy that: one payment per item means many card charges, many fees, and no shared shipping.
A cancellation becomes a refund obligation in OMS. The obligation splits pro-rata across the tenders the customer paid with, and each rail returns its share. One ledger records all of it.
Dashed line: wallet credit is a fallback for what the card cannot take (outside 30 days, or a second refund on one payment). It is not the default.
Card first turns points into cash. Pay SAR 300 card plus SAR 200 points, cancel a SAR 200 item, get SAR 200 cash back: a points cash-out and a fraud path. Points first has the reverse problem. Pro-rata keeps the customer where they started and reconciles cleanly.
Original tender · item level, any amount, many times · pro-rata split · automatic, ops sees exceptions only · one refund ledger · seller payout settled · customer sees it in the app.
These are OMS logic and need no downstream team. They are the first thing to build, and no later phase changes them.
What the customer paid for the item after item discounts, plus its pro-rata share of any order-level promo.
If a seller cancellation takes the order below a promo minimum spend, Merit does not claw the promo back. The customer did nothing wrong.
Refunded only when the last item of a shipment is cancelled before dispatch. A partial cancellation keeps the fee, because the shipment still goes out.
Pro-rata across the legs the order was paid with. Points round down, per DEC-0120. The remainder goes to the card leg.
A cancelled item creates a refund obligation at once, with amount and split. The payout path changes by phase. The obligation does not.
A seller that cancels, by portal or by API, is not paid for the item and pays no commission on it. Penalties are out of scope.
The default is the example from the proposal: SAR 500 order, SAR 300 card, SAR 200 in points, the seller of a SAR 100 item cancels.
Points are shown at SAR value. The real system rounds to whole points, down, and gives the remainder to the card leg.
Each phase only adds a way to pay out the obligation. OMS logic built in Phase 1 stays as it is.
| Phase | What the customer gets | Who builds | Blocked by |
|---|---|---|---|
| 0 | Nothing yet | Nobody, five answers | Moyasar, Tamer, Comarch, Legal, Ops |
| 1 | Card money back after the order closes; points may be pending | OMS only | Ops owner |
| 2 | Automatic refunds per rail, store credit fallback | Payment Service, Exchange, adapter or PX | Each team's capacity |
| 3 | Instant, per item, visible in the app, seller settled | Payment Service, Settlement, B2C | Moyasar multi-refund, Settlement owner |
The colour of each box shows who acts. The two checks in the middle are what let us work inside the current limits: one refund per payment, within 30 days.
Limits of Phase 1: one manual step per refund; the customer waits for the order to close (up to 7 days); the points leg may wait for Phase 2; one partial refund per payment.
Store credit was the first idea in the standup. Three facts make it slower, not faster.
Wallet credit is a deferred Payment Service item. Store credit needs downstream work before it works at all.
A SAR 60 credit can only pay a whole order of SAR 60 or less. It cannot top up a card payment.
Muneeb and Wshah's point: the customer will ask for cash. Every credit becomes a payout request, and payouts run on old world services.
Phase 2, for what the card cannot take: outside 30 days, or a second refund on one payment. Gated by the Legal answer.
Two constraints are on record but not proven. If either is wrong, the plan changes, so these go first.
| # | Question | Owner | Why it matters |
|---|---|---|---|
| Q1 | How many refunds can one Moyasar payment take? A partial amount is confirmed in Moyasar's API docs (Wshah, 7 Oct); the docs are silent on more than one. | Zarar, with the Payment Service team | One: consolidate per order, as Phase 1 does. Many: Phase 3 is easy. |
| Q2 | Can Merit Exchange refund part of an authorisation, or credit N points to a member? | Tamer | Decides the points leg in Phase 1. |
| Q3 | Does Comarch support partial Miles reversal? Likely yes: its Refund an Order endpoint takes a list of reward lines with quantity and points. Not tested. | Tahsin, Aditya or Akshay, in #proj-legacy-to-ecom-sol-migration | The adapter is built now. Partial must be in it from day one. |
| Q4 | Can a card refund go out as store credit without consent under Saudi consumer rules? | Legal | Store credit as fallback, or only as a customer choice. |
| Q5 | Who executes the manual refund task in Phase 1? | Ops | Phase 1 has a manual step. |
Next: Zarar and Khawar review, Zarar checks Q1 against the Moyasar API, then a session with Tamer on Q2. After the review this becomes the separate Partial Refund PRD.