List refunds

GET/v1/refundsscope refunds:read

Query parameters

limitintegerdefault 20: Page size, 1-100.
cursorstring: The next_cursor of the previous page. Omit for the first (newest) page. Up to 1024 characters.
created_gtestring (date-time): Only objects created at or after this time (ISO 8601).
created_ltstring (date-time): Only objects created before this time (ISO 8601).
paymentstring: Only refunds of this payment (pay_…).
statusstring: One of: pending, succeeded, failed

Headers

ZyloPay-Versionstring: Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.

Returns

HTTP 200 with a list object: data holds up to limit refund objects, newest first; has_more and next_cursor drive pagination.

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`).
`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?payment=pay_1042" \
  -H "Authorization: Bearer $ZYLOPAY_SECRET_KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List refunds

Query parametersCopy Anchor Link

HeadersCopy Anchor Link

ReturnsCopy Anchor Link

ErrorsCopy Anchor Link

Example requestCopy Anchor Link