​
Overview

A transaction is how value moves through Lumx. There are three types:
  • On-Ramp — convert fiat to a stablecoin and deliver it to a wallet.
  • Off-Ramp — convert a stablecoin to fiat and pay it out via a rail.
  • Transfer — move a stablecoin from one customer to another or to an external wallet.
Use any supported fiat, asset, network, and rail configured for your account. Refer to supported currencies, blockchains, and rails.

​
Transaction anatomy

Every transaction returns a consistent envelope with type-specific details. 
{
	"id": "uuid",
	"customerId": "uuid",
	"type": "ON_RAMP | OFF_RAMP | TRANSFER",
	"request": {
		/* input params for this transaction */
	},
	"state": {
		"status": "AWAITING_FUNDS | PROCESSING | SUCCESS | FAILED..",
		"payment": {
			/* rail-specific fields, e.g., brCode for Pix */
		},
		"receipt": {
			/* rate, amounts, fees (after settlement), transactionHash */
		},
		"error": {
			/* optional error object */
		}
	},
	"createdAt": "ISO-8601",
	"updatedAt": "ISO-8601"
}
Field presence is status-dependent and varies by type. See the type guides for full examples.

​
Statuses by type

​
On-Ramp

  • AWAITING_FUNDS — waiting for the customer’s deposit on the selected payment rail (state.payment.*).
  • TRANSFERRING_FIAT — deposit identified; confirming fiat settlement.
  • TRADING — funding confirmed; converting source fiat currency to the target stablecoin.
  • TRANSFERRING_STABLECOIN — sending stablecoin to the destination wallet.
  • SUCCESS — stablecoin delivered; state.receipt.* and, when applicable, state.blockchain.*.
  • FAILED — transaction failed/expired; see state.error if present.
  • REFUNDING — transaction has failed and funds will be sent back to the bank account of origin
  • REFUNDED — funds have been successfully sent back

​
Off-Ramp

  • TRANSFERRING_STABLECOIN — pulling funds from the source stablecoin.
  • TRADING — funding confirmed; converting source stablecoin to the target fiat currency.
  • TRANSFERRING_FIAT — fiat payout in progress.
  • SUCCESS — fiat settled on the selected payment rail; state.receipt.*.
  • FAILED — transaction failed/expired; see state.error.
  • REFUNDING — transaction has failed and funds will be sent back to the wallet
  • REFUNDED — funds have been successfully sent back

​
Transfer

  • PROCESSING — on-chain submission/confirmation in progress.
  • SUCCESS — transfer confirmed on-chain; state.blockchain.transactionHash and blockExplorerUrl.
  • FAILED — transfer failed (e.g., insufficient funds, invalid address, network error); see state.error.

​
Lifecycles (at a glance)

  • On-Ramp: create → deposit instructions → customer funds fiat → deliver stablecoin.
  • Off-Ramp: create → provide payout details → customer funds stablecoin → pay out fiat.
  • Transfer: create → on-chain transfer → confirm.

​
Exchange rates & amounts

Transactions may use floating or locked exchange rates:
  • Floating — priced at execution; simpler UX; no lock premium.
  • Locked — guaranteed for a short window; comes with an exchangeRateId and expiresAt; may include a lock premium that depends on lock duration and market conditions.
See: Floating Exchange Rate • Locked Exchange Rate.

​
Fees

Both transaction and rate responses show transparent fees:
  • Lumx fees — percentage (bps) and/or flat, in a defined currency.
  • Partner fees — optional via partnerFeeId.
Final delivered amounts are reflected in state.receipt.* on success.

​
Retries

Safe to poll by transaction ID and/or subscribe to webhooks for status changes. See Webhooks.

​
Common errors

  • Payments/Funding: payment_expired, insufficient balance/funding not received.
  • Delivery/Payout: invalid delivery address/payout fields, rail constraints.
  • Transfers: invalid address format, insufficient funds, network errors.
Handle errors by showing clear UI, offering retry (new quote or new payment), and preventing duplicate submissions (idempotency).

​
Best practices

  • Pick the simplest pricing: use floating unless your UI or workflow needs a guaranteed amount.
  • Short locks (if using locked): keep timeLock minimal to reduce premium and expiry risk.
  • Show timers where relevant (payment window, lock countdown).
  • Validate early: wallet addresses, payout fields, balances, and limits.
  • Observe limits & compliance: KYC/KYB, sanctions/KYT, AML alerts.