Skip to main content
FX swap webhooks notify your system about lifecycle changes of currency conversions between two wallets of the same user inside the RALIO ecosystem. An FX swap debits an origin wallet in one currency and credits a destination wallet in another, at an exchange rate set by the external liquidity provider. These events allow you to:
  • Track the progress of a conversion in real time
  • Update wallet balances when the swap settles
  • Detect and react to provider rejections
  • Reconcile fees and applied rates
Only swaps with status COMPLETED represent finalized balance movements.

​
FX Swap Events

Events represent lifecycle transitions of an FX swap. An FX swap follows this state flow:

​
State Definitions

​
Available Events

The webhook data.status values (PROCESSING / COMPLETED / FAILED) differ from the REST order state (PENDING / SETTLED / FAILED) returned by the FX swap endpoints. They describe the same lifecycle.

​
FX Swap Behavior

FX swaps are internal conversions between two wallets of the same user:
  • data.swapType is always fxSwap
  • source.type and destination.type are always account
  • The source wallet is debited in the origin currency; the destination wallet is credited in the destination currency
  • Fees are charged in the origin currency
  • The applied provider rate and pair are reported in amounts.fx

​
Amount Flow (Important)

The amounts object represents how funds move through the conversion:
  • debitedAmount — Gross amount deducted from the origin wallet
  • fees — Total fees in the origin currency, with a breakdown of systemFee and merchantFee. Omitted when no fees apply.
  • amountAfterFees — Net origin amount actually converted (debitedAmount - fees.total)
  • fx — The applied pair (e.g. EUR/USD) and provider rate
  • creditedAmount — Final amount received by the destination wallet, in the destination currency. Omitted on swap_failed.
On swap_failed, the payload additionally carries a failure object with code and reason describing the provider rejection. All amounts are expressed in minor units.