Refunds

Refund a paid invoice. Operator approves every refund before broadcast. Partial refunds supported — total refunds cannot exceed the original net credited amount.

POST /api/v1/merchant/invoices/{invoice_public_id}/refunds

Required scope: refunds.write. Required header: Idempotency-Key. The invoice must be in paid or partially_refunded state.

Body

Field	Type	Notes
`amount`	string	Decimal. ≤ remaining refundable.
`refund_address`	string	Address to send the refund to.
`refund_address_memo`	string	For memo-capable networks.
`reason`	string	Internal note. ≤ 500 chars.
`customer_visible_reason`	string	Shown in webhook payload. ≤ 500 chars.

Example

curl

curl -X POST https://api.swapss.lol/api/v1/merchant/invoices/INV-0123456789/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5.00",
    "refund_address": "TH...example",
    "reason": "Customer asked to cancel"
  }'

Lifecycle

pending_approval → approved → submitted → confirmed. On confirmed the parent invoice is rolled up to refunded when all of the net amount has been refunded, or partially_refunded if there's remainder. Failures return the locked amount to your available balance.

GET /api/v1/merchant/refunds

Paginated list. Filters: status, asset.

GET /api/v1/merchant/invoices/{public_id}/refunds

All refunds for one invoice.