Create a refund

Return all or part of a payment to the payer, from your merchant balance, on the payment's own network.

POST/v1/refundsscope refunds:write

The response is the refund: succeeded (mined), pending (sent, confirmation not seen yet: it resolves on its own, never retry with a new key) or failed (nothing moved; failure_code). Your account's refund window and daily limit apply.

Body parameters

paymentstringrequired: The payment to refund (pay_…).
amountinteger: Amount to refund in USDC atoms. Defaults to everything not yet refunded. Partial refunds are allowed until the payment is fully refunded. Between 1 and 1000000000000.
reasonstring: Why you refund (kept in the refund record). Up to 500 characters.
metadataobject: Up to 20 key/value pairs (keys 1-40 characters of A-Z a-z 0-9 _ . -, string values up to 500 characters) returned unchanged. Never store secrets or personal data here.

Headers

ZyloPay-Versionstring: Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.
Idempotency-Keystringrequired: Required. A unique key per operation (a UUID v4). Retrying with the same key and body returns the first response (Idempotent-Replayed: true); a different body is refused with 409 idempotency_key_reused. Keys are kept 48 hours.

Returns

HTTP 201 with the refund object.

Errors

Status	Meaning
`400`	Invalid request (`invalid_request_error` / `idempotency_error`).
`401`	Missing, invalid, expired or revoked API key (`authentication_error`).
`403`	The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).
`409`	Conflict: idempotency key reused or in progress, or the object is in the wrong state.
`429`	Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.
`500`	Internal error (`api_error`). Retry with the same `Idempotency-Key`.

Branch on error.code. Every code is listed in error codes.

Example request

curl https://zylopay-api.fly.dev/api/v1/refunds \
  -H "Authorization: Bearer $ZYLOPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payment": "pay_1042",
    "amount": 1000000,
    "reason": "Customer returned one item",
    "metadata": {
      "return_id": "R-2211"
    }
  }'

Example response

{
  "id": "re_4Fq9LwP2mZt8Xk3Vb7Ns1HdQ",
  "object": "refund",
  "livemode": false,
  "amount": 1000000,
  "currency": "usdc",
  "payment": "pay_1042",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure_code": null,
  "failure_message": null,
  "tx_hash": "0x9e1f0c8a36f2a7b6d1e4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d",
  "source": "api",
  "metadata": {
    "return_id": "R-2211"
  },
  "network": "testnet",
  "created": "2026-09-28T15:10:04.000Z",
  "updated": "2026-09-28T15:10:05.000Z"
}

Create a refund

Body parametersCopy Anchor Link

HeadersCopy Anchor Link

ReturnsCopy Anchor Link

ErrorsCopy Anchor Link

Example requestCopy Anchor Link