Refunds
Refund a succeeded payment, fully or partially.
A refund is asynchronous. Only succeeded payments can be refunded.
private key required
Refunds require the private 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 |
Refunds scoped to one payment
To list only the refunds on a specific payment, use GET /payments/{id}/refunds instead — same objects, pre-filtered. This
page (/refunds) is the canonical, top-level resource: use it to create a refund or look one
up by its own id.
Lifecycle
Events
| Event | Trigger |
|---|---|
refund.created | Refund created |
refund.processing | Refund submitted to the operator |
refund.succeeded | Refund confirmed |
refund.failed | Refund failed |
refund.cancelled | Refund cancelled |