Integrate FX Swaps - RalioPay Docs

Sandbox base URL: https://sandbox-revo-api.raliopay.com

Prerequisites

The FX feature must be enabled on your account profile, with pricing configured for each currency pair you want to test. In sandbox this is provisioned by the RalioPay team — contact support if a pair you need returns This FX quote cannot be processed at the moment. Please contact support.
A user with verified KYC/KYB and two active accounts in different currencies (e.g. an EUR wallet and a USD wallet).
The origin account must have balance. You can fund it with a sandbox payin.
To receive the FX webhook events, register your webhook endpoint and subscribe it to swap_processing, swap_completed, and swap_failed.

Full test flow

Locate the two accounts

Call List user accounts and note the accountId of the origin wallet (aid in the URL) and of the destination wallet (recipient.accountId in the body).

Create a quote

Lock a rate for 60 seconds:

curl -X POST "https://sandbox-revo-api.raliopay.com/api/v1/account/users/{uid}/accounts/{aid}/fx-quotes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAmount": 100000,
    "recipient": { "accountId": "e582cef6-a320-4d0d-afda-446ba16725ac" }
  }'

Response

{
  "quoteId": "q1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
  "origin": { "amount": 100000, "currency": "EUR" },
  "destination": { "amount": 106607, "currency": "USD" },
  "fee": {
    "amount": 1500,
    "currency": "EUR",
    "breakdown": { "systemFee": 1000, "merchantFee": 500 }
  },
  "quote": {
    "rate": "1.0823",
    "pair": "EUR/USD",
    "timestamp": "2026-06-22T11:00:00Z",
    "validUntil": "2026-06-22T11:01:00Z"
  }
}

Execute the swap

Reference the quote within its 60-second window:

curl -X POST "https://sandbox-revo-api.raliopay.com/api/v1/account/users/{uid}/accounts/{aid}/fx-swaps" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "q1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
    "ownReference": "FX-SWAP-2026-001",
    "description": "Currency exchange EUR to USD"
  }'

The response returns the order in PENDING state with a detailUrl you can poll. Alternatively, execute without a quote at the market rate by omitting quoteId and sending recipient plus exactly one of fromAmount / toAmount:

{
  "ownReference": "FX-SWAP-2026-002",
  "description": "Currency exchange EUR to USD",
  "fromAmount": 100000,
  "recipient": { "accountId": "e582cef6-a320-4d0d-afda-446ba16725ac" }
}

Receive the webhooks

Your endpoint receives swap_processing when the swap is delegated to the provider, followed by swap_completed once the destination wallet is credited. In sandbox this happens within seconds.

Verify the result

Call Get FX swap order details with the order ID and confirm state is SETTLED and settledAt is set. The destination account balance reflects the credited amount.

Testing the expired-quote error

Create a quote, wait longer than 60 seconds, then execute with its quoteId. The API returns 422 with code QUOTE_EXPIRED — no order is created and no funds are held.

Simulating a failed swap

A FAILED swap is triggered by the external provider rejecting the execution. Simulating a failure in sandbox is coming soon. In the meantime, make sure your integration handles the swap_failed event: when it fires, the hold on the origin funds has been released and data.amounts.creditedAmount is omitted from the payload.

​Prerequisites

​Full test flow

​Testing the expired-quote error

​Simulating a failed swap

Prerequisites

Full test flow

Testing the expired-quote error

Simulating a failed swap