Get refund

API contract v1.0.0

On this page

getRefund

GET/v1/refunds/{refund_id}

Required scopesrefunds:read

Retrieves a single refund. Success, failure and rejection each produce a queryable status and send a notification. returned means the refunded funds came back after the refund had been confirmed as succeeded, and returned_amount is the returned principal; the original success is kept on record. Platform exception refunds (where the platform returns a duplicate charge, or an overcharge caused by an amount mismatch, to the cardholder's original payment method) aren't returned by the open API: retrieving one returns 404, and they don't count toward the Payment's refunded_amount or refund_status.

Request headers

Request headers	Required	Format	Description
Authorization	Yes	Bearer <API_KEY>	Server-side key, to be used only on the merchant's server. The merchant and environment are derived from the key. A missing, invalid, revoked or expired key returns 401.

Request example

curl

curl -X GET 'https://api.fluxan.co/v1/refunds/<REFUND_ID>' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

Placeholders to replace

<REFUND_ID>: The id returned when you create a refund (starts with ref_)
<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal

Note

Server API keys must only be used on your own server, so the docs site doesn't offer interactive API testing. Get a test key: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)

Responses

The refund details.

Example

JSON

{
  "id": "ref_demo_001",
  "version": 1,
  "payment_id": "pay_demo_001",
  "merchant_refund_no": "REFUND-DEMO-001",
  "amount": 2500,
  "currency": "USD",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "returned_amount": 0,
  "failure": null,
  "metadata": {
    "ticket": "CS-DEMO-001"
  },
  "created_at": "2026-09-24T02:00:00Z",
  "completed_at": "2026-09-24T02:00:09Z",
  "request_id": "req_demo_025"
}

Response fields

Returns an object. See the object section for field descriptions.

Name	Type	Required	Description
`id`	string	Required	Platform refund ID. Example: `ref_demo_001`
`version`	integer(int64)	Required	Object version, which increases with every effective business change (status, failure reason, returned amount). Compare versions to discard older events, and don't order events by status name. Constraints: `≥ 1` Example: `1`
`payment_id`	string	Required	Original payment ID. Example: `pay_demo_001`
`merchant_refund_no`	string	Required	Merchant refund ID, unique within one merchant and environment. Example: `REFUND-DEMO-001`
`amount`	integer(int64)	Required	Refund principal, in the smallest currency unit. Constraints: `≥ 1` Example: `4000`
`currency`	string	Required	Refund currency, inherited from the original payment. Constraints: `Format ^[A-Z]{3}$` Example: `USD`
`status`	string	Required	Refund status. pending_review: accepted and waiting for review; the funds stay reserved processing: approved and submitted, or the provider's result is being confirmed; the funds stay reserved succeeded: the provider confirmed the refund succeeded; the reserved funds become a final deduction failed: the refund clearly did not succeed; the reserved funds are released rejected: rejected in review and not submitted to the provider; the reserved funds are released canceled: canceled by an authorized person before submission to the provider; the reserved funds are released returned: all or part of the funds were actually returned after a refund that had been confirmed as succeeded `pending_review`: Accepted and waiting for review; the funds stay reserved `processing`: Approved and submitted, or the provider's result is being confirmed; the funds stay reserved `succeeded`: The provider confirmed the refund succeeded; the reserved funds become a final deduction `failed`: The refund clearly did not succeed; the reserved funds are released `rejected`: Rejected in review and not submitted to the provider; the reserved funds are released `canceled`: Canceled by an authorized person before submission to the provider; the reserved funds are released `returned`: All or part of the funds were actually returned after a refund that had been confirmed as succeeded More values may be added in the future. Don't treat a status you don't recognize as success. Example: `pending_review`
`reason`	string	Required	Refund reason. Example: `requested_by_customer`
`returned_amount`	integer(int64)	Required	The cumulative principal actually returned after the refund succeeded. Constraints: `≥ 0` Example: `0`
`failure`	RefundFailureNullable	Required	The reason when status is failed or rejected; otherwise null.
`code`	string	Required	Failure reason code. Example: `refund_rejected`
`message`	string	Required	Sanitized description. Example: `The refund request didn't pass review.`
`metadata`	object	No	Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request. Constraints: `Up to 20 keysMax value length 200` Example: `{"business_order_type":"one_time_purchase"}`
`created_at`	string(date-time)	Required	The time the request was accepted. Example: `2026-09-23T10:00:00Z`
`completed_at`	string(date-time)Nullable	Required	The time the refund entered succeeded, failed, rejected or canceled; null if it hasn't ended yet. Example: `null`
`request_id`	string	Required	Unique identifier of this request, used for troubleshooting and support. Example: `req_demo_001`

Possible error codes

HTTP	Error code	When it occurs	How to handle
404	not_found	An incorrect ID; using a test key to look up a live object; looking up a platform exception refund (not returned by the open API)	Check the ID and the environment of the key you used; the platform doesn't reveal whether another merchant's object exists
401	unauthenticatedCommon	No `Authorization` header was sent; the key was copied incompletely; the old key expired after a rotation; the key was revoked	Check your credentials: on the API Key page in the merchant portal, verify the key's status and environment
403	forbiddenCommon	Creating a refund with a read-only key; calling `getEvent` without the read scope for the event's business area; if the request's source IP isn't on the key's allowlist, the more specific `ip_not_allowed` is returned	Use a key that has the required scope; don't work around the restriction
429	rate_limitedCommon	A rate limit per merchant and per key; switching keys doesn't get around the merchant's overall limit	Wait for `Retry-After` seconds, then retry with the original idempotency key
500	internal_errorCommon	—	Retry with the original idempotency key, or query by merchant order ID / refund ID; never charge again with a new key
502 / 503	upstream_unavailableCommon	A provider or platform dependency failed, and the platform can't confirm whether this request took effect	Same as above

Notes

returned means the refunded funds came back after the refund had been confirmed as succeeded. The original success is kept on record, and returned_amount is the returned principal.
failure appears only when the status is failed or rejected.
Platform exception refunds aren't returned by this endpoint. Retrieving one returns 404.

Related events: refund.succeeded, refund.failed, refund.returned
Error codes and HTTP status

Was this page helpful?