Refunds
Refund a succeeded payment, fully or partially.
A refund is asynchronous. Only succeeded payments can be refunded.
Secret key required
Refunds require the secret key (sk...).
Marketplaces: acting on behalf of a subaccount
Platforms can refund a connected subaccount's payment by sending an X-Sync header alongside
their own key (requires the refunds capability) — see Subaccounts for
the full contract and error cases.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /refunds | Create a refund |
GET | /refunds | List refunds |
GET | /refunds/{id} | Retrieve a refund |
Lifecycle
Refund lifecycle
pendingprocessingsent to operator, webhook refund.processingsucceededwebhook refund.succeeded
Terminal statesfailedwebhook refund_failedcancelledwebhook refund.cancelled
Events
| Event | Trigger |
|---|---|
refund_created | Refund created (note: underscore, not dot-separated) |
refund.processing | Refund submitted to the operator |
refund.succeeded | Refund confirmed |
refund_failed | Refund failed (note: underscore, not dot-separated) |
refund.cancelled | Refund cancelled |