Refunds

Return money to a shopper after a checkout has been captured. Refunds are issued from the Maytes merchant portal — your integration doesn't call a refund API. What your integration does need to handle is the aftermath: a refunded checkout changes status, and your order records should follow.

Partial refunds are coming

Today a refund returns the full captured amount. Support for partial refunds is on its way.

A few ground rules:

• Only a captured checkout can be refunded. For an order that's merely authorized, cancel it instead — no money has moved yet.
• The shopper always gets 100% back, returned to the same card they paid with.
• Refunds settle asynchronously with the payment provider — the checkout passes through a brief refunding state before landing on refunded.

---

What your integration sees

When a refund is issued in the portal, the checkout's status transitions captured → refunding → refunded, and the GET checkout response carries the refund fields:

{
  "data": {
    "checkout_uuid": "0192a8f2-...",
    "status": "refunded",
    "amount": 4500,
    "currency": "AUD",
    "refunded_amount": 4500,
    "merchant_processor_fee": 0,
    "merchant_service_fee": 0,
    "last_refund_at": "2026-09-14T10:14:33.000Z"
  }
}

Field	What it means
status	refunding while settling, refunded once the payment provider confirms.
refunded_amount	The amount returned to the shopper (minor units). 0 while pending; matches the captured amount once settled.
last_refund_at	ISO timestamp of the confirmed refund. null while pending.
merchant_processor_fee	Reserved for processor cost billed to you on the refund. Currently always 0 — refund fee billing is not yet applied.
merchant_service_fee	Reserved for the Maytes service fee billed to you on the refund. Currently always 0.

Shopper always gets 100% back

If refund fee billing is introduced, merchant_processor_fee and merchant_service_fee will be amounts billed to you — never deductions from what the shopper gets back.

Keeping your records in sync

Treat refunded as terminal: the order is unpaid again and the shopper has their money. Two easy ways to pick it up:

1. Reactively — whenever your systems read a checkout (support tooling, reconciliation jobs), branch on status and handle refunding/refunded alongside the other lifecycle states.
2. At refund time — if your team issues the refund, have your ops process update the order record then, polling GET /checkouts/{uuid} until status is refunded if you want settlement confirmation.

There is no refund webhook event — the refund is initiated by your own team in the portal, so there's no unprompted state change your integration needs pushing to it.

What's next

• Capture & order status — the lifecycle these states belong to, and cancel for pre-capture release.
• API reference — the full get-checkout response schema.