Transaction statuses

What each product reports, how partner states map to ours, and when to credit the user.

Each product reports its own small status set. There is no single vocabulary across products - a deposit, a card payment, and a bank transfer move through different machinery, so each set matches what its rail actually does. What every set shares is the rule that matters: in every set there is exactly one state that means “credit the user”, and you credit on that state only.

Fetch the machine-readable catalogue from GET /v1/statuses.

Ask with our id

Every call that creates something answers an id of ours, and you ask about it with that id, the same way for every product. A crypto deposit is an order: GET /v1/orders/{id} answers it, and the status calls of the other products take the id their create call returned. Keep that id; it is the thread through everything below.

Crypto deposits

Track a deposit by polling /v1/deposit/status with the source-chain receipt.

Status	Terminal	Meaning
pending	No	The deposit is in flight - submitted on the source chain, not yet delivered. Keep polling.
done	Yes	Funds were delivered on the destination chain. txHashes.delivered is set. Credit the user now.
failed	Yes	The deposit did not complete. Do not credit the user.
expired	Yes	The transfer window elapsed before delivery. The routing layer auto-refunds the source funds - there is no refund call to make. Do not credit the user.

How the routing layer’s reporting maps to these:

Routing layer reports	Rheon status
Transfer submitted, delivery leg not yet confirmed	pending
Delivery confirmed on the destination chain	done
Transfer rejected or reverted	failed
Transfer window elapsed, source funds auto-refunded	expired

Card payments

Track a card purchase by polling /v1/card/status.

Status	Terminal	Meaning
pending	No	No transaction record yet - the buyer has not been through the hosted card page.
processing	No	A record exists: the payment has started and is being settled.
completed	Yes	Settled. Credit the buyer now - and credit deliveredAmount, not the charged amount.
failed	Yes	Cancelled or rejected. Do not credit the buyer.
unknown	No	The card partner could not be read. Not a failure - keep polling.

How the card partner’s states map to these:

Card partner reports	Rheon status
No transaction record for this purchase yet	pending
Created, awaiting payment, or paid but not yet settled on-chain	processing
Settled - crypto delivered	completed
Cancelled, declined, or failed at any step	failed
A state we do not recognise, or the partner is unreadable	unknown

A state we do not recognise is reported as unknown and flagged, never quietly shown as “in progress”.

Bank transfers

Track a virtual account by polling /v1/fiat/status.

Status	Terminal	Meaning
awaiting_deposit	No	The account is open and waiting for money to arrive. Keep polling.
funded	Yes	A transfer landed, was converted, and settled to the wallet. deliveredAmount says what to credit.

The banking partner reports many more states than these two - money received but not yet settled, a transfer held for review, a refund on its way back - and every one of them is reported here as awaiting_deposit, because nothing has settled to the wallet yet. A bank transfer that fails or is refunded on the partner side never reaches funded. The account simply stays awaiting_deposit, because the account itself is still open and can be paid again.

Virtual accounts

A virtual account has no status of its own - it is permanent, and it is the money arriving into it that has a state. Poll the same /v1/fiat/status and read the table above: the account sits at awaiting_deposit between payments and reports funded each time a transfer settles.

Because the account is reusable, funded is not the end of its life. Treat each settlement as its own event rather than closing the account after the first one.

Payouts

Card payouts, bank payouts, and payouts from a virtual account share one status set. Poll card payout status, bank payout status, or take the webhook.

Status	Terminal	Meaning
pending	No	Quoted and created, waiting for the user’s stablecoin to arrive at the deposit address.
converting	No	The stablecoin landed and is being converted to fiat.
sent	No	The payout left the partner. Not arrived - see the warning below.
settled	Yes	The money reached the card or bank account. This is the state to tell the user about.
rejected	Yes	The partner refused it. reason says why.
returned	Yes	It was sent and came back, typically wrong or closed beneficiary details. reason says why.

sent is not settled. sent means the payout left the partner; card schemes and bank rails take from minutes to several working days to post it. Telling a user the money has arrived at sent produces support tickets.

When to credit the user

Credit only on the crediting state of each product - done for a crypto deposit, completed for a card payment, funded for a bank transfer or virtual account, settled for a payout. That is the single signal that funds actually landed. Everything else is either still moving or means nothing was delivered.

Tracking

Poll the status endpoint of each product from your backend until the status is terminal. Keep polls a few seconds apart to stay under your rate limit.

For anything your backend must trust (crediting a user, releasing an order), rely on a terminal status you fetched yourself - not on client-side UI state.