Statuses and assets
Relay exposes an overall payment status, an independent settlement status, and—on reusable customer wallets—separate deposit and transfer statuses. Keep these state machines separate in your integration.
Payment status#
| Value | Meaning |
|---|---|
pending | The payment exists and has not reached a more specific funding state. |
pending_verification | Relay has evidence that requires additional verification. |
awaiting_confirmation | An observed transaction has not met the required finality threshold. |
awaiting_offset | Eligible confirmed funding is below the target and more funds are required. |
successful | The incoming payment target is funded. Outgoing settlement can still be pending. |
completed | Relay's post-funding workflow reached completion/submission. Check settlementStatus for final settlement evidence. |
failed | Payment processing reached a failed state. Inspect settlement independently if funds were already confirmed. |
cancelled | The payment was cancelled. |
The exact transition path varies by payment type and network. Integrations should accept a valid state without assuming every payment visits every earlier state.
Settlement status#
| Value | Meaning |
|---|---|
not_started | No outgoing settlement has been submitted. |
submitted | Relay recorded an outgoing transaction and is checking its on-chain result. |
settled | Outgoing settlement was verified. |
failed | Settlement was verified as failed or exhausted safe processing attempts. |
review_required | The broadcast, resources, or accounting outcome is ambiguous and requires reconciliation before another send. |
Some historical records can contain legacy settlement values. Treat unknown values as non-final, log them, and reconcile through retrieval or Relay support.
Accounting state#
| Value | Meaning |
|---|---|
ready | The payment's immutable target and cumulative confirmed accounting are ready for automated processing. |
review_required | Accounting evidence requires operational reconciliation. |
Customer wallet deposit status#
| Value | Meaning |
|---|---|
confirmed | Incoming evidence was credited and a merchant payout was queued. |
settled | The linked merchant payout was verified on-chain. |
review_required | The deposit or its payout cannot continue automatically. |
Customer wallet transfer status#
| Value | Meaning |
|---|---|
queued | Transfer is durably queued but not broadcast. |
submitted | An outgoing hash is recorded and awaiting verification. |
settled | On-chain settlement was verified. |
review_required | Relay will not authorize a replacement send until reconciliation is complete. |
Enabled networks#
New wallet and payment work currently uses:
| Network | API value | Customer wallets | Crypto payment intents | Fiat settlement |
|---|---|---|---|---|
| TRON | tron | yes | yes | depends on active token configuration |
| Solana | solana | yes | yes | no; crypto intents only |
Ethereum, Polygon, and Stellar values can exist on historical records, but they are not enabled for new work in the current network policy. Do not infer availability from historical data or enum names.
Tokens and precision#
Customer wallet requests accept USDT and USDC, subject to active network/token configuration. The broader stored token enum also contains MATIC, TRON, ETH, and XLM for historical or specialized records; their presence does not make them available for a new request.
| Asset family | Expected precision in payment accounting |
|---|---|
| USDT / USDC | 6 decimals |
| XLM historical records | 7 decimals |
| Other historical crypto assets | generally 18 decimals |
Always use the active-assets endpoint and the payment's pinned tokenDecimals, tokenContractAddress, and chain fields when available.
Decimal handling#
Payment-object monetary fields, customer deposit amounts, fees, merchant amounts, and transfer amounts are serialized as decimal strings.
import Decimal from "decimal.js";
const confirmed = new Decimal(payment.confirmedAmount);
const target = new Decimal(payment.originalAmount);
const fullyFunded = confirmed.greaterThanOrEqualTo(target);Do not convert these values to JavaScript number before arithmetic. The standalone fiat-rate endpoint currently returns its indicative rate as a JSON number; convert it to your decimal type from its string representation and treat the created intent's stored quote as authoritative.
Event ordering#
Webhook delivery order is not guaranteed. Use resourceVersion to avoid moving a local payment projection backward. A settlement event can arrive after a funded event, and a retry of the funded event can arrive after that newer settlement event. Event id handles duplicate delivery; resourceVersion handles resource ordering.