# Refunds (/reference/refunds)

## Money that went back, newest first

`GET /v1/refunds`

Both kinds. Any key kind may read; refunds are reconciliation.

### Parameters

- `limit` (query, optional, integer)
- `cursor` (query, optional, string) — Opaque cursor from the previous page's `next_cursor`.
- `invoice_id` (query, optional, string (uuid))
- `status` (query, optional, string)
- `kind` (query, optional, string, one of: overpayment, merchant)

### Responses

- `200` — Refunds.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `id` (required, string (uuid))
    - `invoice_id` (required, string (uuid))
    - `kind` (required, string, one of: overpayment, merchant)
    - `status` (required, string, one of: awaiting_address, pending, sent, confirmed, failed, skipped)
    - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
    - `asset` (required, string)
    - `contract` (optional, string | null)
    - `decimals` (optional, integer | null)
    - `amount_atomic` (required, string) — What is being returned, in atomic units of `asset` — the gross.
    - `amount` (optional, string | null) — `amount_atomic` in whole units. Display only.
    - `fee_atomic` (optional, string) — Network cost taken OUT of the refund (overpayment kind only; `0` on the merchant kind).
    - `net_atomic` (optional, string) — What the destination receives.
    - `to_address` (optional, string | null)
    - `reason` (optional, string | null) — Your note (merchant kind). Never shown to the payer.
    - `payout_id` (optional, string | null (uuid)) — The payout that carries it; read it under `GET /v1/payouts/{id}` with a payout or wallet key.
    - `tx_hash` (optional, string | null)
    - `failure_code` (optional, string | null) — Set with `status: failed` — the carrying payout's failure, rejection or cancellation.
    - `skip_reason` (optional, string | null) — Overpayment kind: why nothing was sent (`uneconomical`, `policy_keep`, …).
    - `network_fee_paid_by` (optional, string, one of: payer, molnpay) — `payer` on the overpayment kind (out of the refund); `molnpay` on the merchant kind, as on every payout — your plan's payout fee applies from the prepaid balance.
    - `created_at` (required, string (date-time))
    - `sent_at` (optional, string | null (date-time)) — When the carrying payout was created.
    - `completed_at` (optional, string | null (date-time)) — When it confirmed on chain, or failed.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## GET /v1/refunds/{id}

`GET /v1/refunds/{id}`

### Parameters

- `id` (path, required, string (uuid))

### Responses

- `200` — The refund.
  - `object` (required, string)
  - `id` (required, string (uuid))
  - `invoice_id` (required, string (uuid))
  - `kind` (required, string, one of: overpayment, merchant)
  - `status` (required, string, one of: awaiting_address, pending, sent, confirmed, failed, skipped)
  - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
  - `asset` (required, string)
  - `contract` (optional, string | null)
  - `decimals` (optional, integer | null)
  - `amount_atomic` (required, string) — What is being returned, in atomic units of `asset` — the gross.
  - `amount` (optional, string | null) — `amount_atomic` in whole units. Display only.
  - `fee_atomic` (optional, string) — Network cost taken OUT of the refund (overpayment kind only; `0` on the merchant kind).
  - `net_atomic` (optional, string) — What the destination receives.
  - `to_address` (optional, string | null)
  - `reason` (optional, string | null) — Your note (merchant kind). Never shown to the payer.
  - `payout_id` (optional, string | null (uuid)) — The payout that carries it; read it under `GET /v1/payouts/{id}` with a payout or wallet key.
  - `tx_hash` (optional, string | null)
  - `failure_code` (optional, string | null) — Set with `status: failed` — the carrying payout's failure, rejection or cancellation.
  - `skip_reason` (optional, string | null) — Overpayment kind: why nothing was sent (`uneconomical`, `policy_keep`, …).
  - `network_fee_paid_by` (optional, string, one of: payer, molnpay) — `payer` on the overpayment kind (out of the refund); `molnpay` on the merchant kind, as on every payout — your plan's payout fee applies from the prepaid balance.
  - `created_at` (required, string (date-time))
  - `sent_at` (optional, string | null (date-time)) — When the carrying payout was created.
  - `completed_at` (optional, string | null (date-time)) — When it confirmed on chain, or failed.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — `refund_not_found`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.