Skip to main content
POST
Request a Fiat Refund
Fiat refunds are an opt-in feature that must be enabled for your account by the Ripio team. While it is disabled, every request returns 403 Forbidden with the error code 20056 (FiatRefundNotEnabledException), and refundable is always false on your orders.

Authorizations

Authorization
string
header
required

Access token obtained via /oauth2/token/. Use as Authorization: Bearer <access_token>.

Headers

X-Ripio-User-Ip
string

Optional. The public IP address of the end user's device (IPv4 or IPv6), captured on your frontend and forwarded by your backend — never your server's own address. Used for traceability and fraud prevention. An address that is not a valid IPv4 or IPv6 discards the end-user context of the request, without failing it. See Forwarding end-user context.

Maximum string length: 45
X-Ripio-User-Agent
string

Optional. The User-Agent of the end user's browser or app, not your backend's HTTP client. Longer values are truncated to 500 characters. See Forwarding end-user context.

Maximum string length: 500
X-Ripio-User-Device-Id
string

Optional. A stable identifier of the end user's device, as your app or frontend defines it. Longer values are truncated to 200 characters. See Forwarding end-user context.

Maximum string length: 200

Path Parameters

customerId
string<uuid>
required

Unique identifier for the customer.

orderId
string<uuid>
required

Unique identifier for the order.

Body

application/json

Body of a fiat refund request. Send fiatAccountId only when refundDestinationRequired is true.

fiatAccountId
string<uuid>

Identifier of an ENABLED fiat account of the same customer, where the money is returned. Rejected by providers that refund to the account the customer paid from.

Example:

"3c9f1f0e-6a2d-4a7c-9f1e-2b8d4c5a6e7f"

Response

A refund already exists for this deposit; nothing new was created.

Acknowledgement of a fiat refund request. The request is idempotent, so a 200 returns whatever refund already existed for the deposit — read initiatedBy before presenting it as the customer's own request.

refundId
string<uuid>

Unique identifier of the refund.

status
enum<string>

Current state of the refund: PENDING (registered, not yet sent to the provider), PROCESSING (sent, awaiting confirmation), COMPLETED (the money reached its destination), REJECTED (the request was declined — see rejectionReason — and nothing was sent) or FAILED / CANCELLED (the attempt did not go through; contact Ripio support).

Available options:
PENDING,
PROCESSING,
COMPLETED,
REJECTED,
FAILED,
CANCELLED
depositUuid
string<uuid>

Identifier of the deposit being refunded.

initiatedBy
enum<string>

Who originated the refund this response is about: PARTNER (your API call), WIDGET (the end user, from the widget), SYSTEM (returned automatically by Ripio) or OPS (registered by Ripio's support team on the customer's behalf).

Available options:
PARTNER,
WIDGET,
SYSTEM,
OPS