One ledger, one native asset
The XRP Ledger is a purpose-built value-transfer network, and like Bitcoin it keeps the asset story simple: XRP is its single native asset. A customer paying in XRP is paying with the ledger's own currency, not a token issued by a smart contract on top of it. There is no second deployment of XRP on a competing chain, no token standard to disambiguate — when a customer says they are paying in XRP, the rail is unambiguous, which is the opposite of a stablecoin like USDT that lives on Tron, Ethereum, and Solana at once.
That is why the XRP page on the asset side and this network page describe the same money from two angles. The asset view is about why a customer reaches for XRP, how the fiat-anchored invoice prices it, and how you take it. This network view is about the protocol that moves it — the consensus mechanism that decides when an XRP payment is final. For a payment processor the network mechanics are the load-bearing part, because they are what separate a transaction that has been submitted from one that has actually settled.
XRP is also a base-layer asset on its own ledger: an XRP payment is native XRP moving on the XRP Ledger, not a wrapped representation riding on another chain. The payer is never asked to bridge or to trust an issuer's version of XRP. That keeps the trust model narrow — the thing you and the customer rely on is the XRP Ledger's validator network agreeing on which ledger version is canonical.
Consensus, not mining: how the XRP Ledger closes a payment
The XRP Ledger does not settle by proof-of-work mining. Instead, a network of validators runs a consensus protocol: they exchange the set of candidate transactions, agree on which ones belong in the next ledger version, and close that ledger together. A transaction that the validators agree on is applied into a validated ledger; one that does not reach agreement is not. There is no race between competing miners producing blocks at the same height, which is the property that makes XRP Ledger finality fast and clean rather than confirmation-by-confirmation.
Because settlement is consensus-driven, an XRP payment moves through a different shape of lifecycle than a Bitcoin one. A submitted transaction is in flight until it is included in a closed, validated ledger; once it is validated, it is settled. halfin sees the submission and can report it as confirming, then marks the payment settled once the network's settlement condition is met. The wait is short by the network's design, but halfin still exposes it as observable states rather than assuming the moment of submission equals the moment of settlement.
The practical upshot for an integration: the only state that should trigger fulfilment is the settled one. An XRP payment that has been broadcast but not yet validated into a closed ledger is in flight, not money you can act on — the same discipline halfin applies on every rail, just over a shorter window because the XRP Ledger validates quickly.
| Stage | What it means on the XRP Ledger | Settlement status |
|---|---|---|
| Submitted | The transaction is broadcast to validators but not yet in a validated ledger. | Seen, not settled — it has not been agreed into a closed ledger. |
| In consensus | Validators are agreeing on the next ledger version that may include it. | Confirming — outcome not yet final. |
| Validated | The transaction is applied into a closed, validated ledger version. | Final on the ledger — eligible to credit. |
| Settlement condition met | halfin's XRP gate confirms the deposit against its per-chain policy. | Settled — credited reorg-aware to your balance. |
Finality on the XRP Ledger
Validation on the XRP Ledger is the moment a payment becomes final: once a transaction is applied into a validated ledger version, it is settled and the network does not reorganize it away the way an early-block proof-of-work transaction can be unwound. That is the source of the XRP Ledger's reputation for fast finality — settlement is a consensus outcome reached in seconds, not a probability that climbs as blocks stack on top.
halfin does not take that as a reason to skip its usual discipline. XRP is credited through the same path as every other rail: the deposit is matched to your invoice, the network's settlement condition is satisfied, and crediting is reorg-aware and respects a per-chain confirmation policy. In practice that resolves quickly for XRP, but it follows the same set of rules — fast finality is a property of the ledger, not a shortcut in how halfin marks a payment paid. The figure you see as settled is one that actually held in a validated ledger.
You do not implement any of this yourself. Submission watching, validation tracking, and settlement enforcement all live inside halfin's XRP gate. Your integration reacts to a small set of states through the dashboard, the REST API, or a signed webhook, and the contract is the same on XRP as everywhere else: treat the pre-settlement states as in flight, and only the settled state as money you can act on.
The XRP Ledger fee characteristic
Every transaction on the XRP Ledger pays a small network fee, and that fee is paid by the sender to the network — it is a property of the XRP rail, not a halfin charge. The fee exists primarily as an anti-spam measure rather than as a market auction for scarce block space, so the cost to transact is characteristically low and the experience is a fast, cheap send rather than a bid for priority. The fee can rise when the network is under unusual load, but the everyday character of the rail is inexpensive settlement.
For a payer this is the practical feel of the XRP Ledger: a payment confirms quickly and costs little to send. It is why a customer who already holds XRP will reach for it rather than swapping into another asset first, and why XRP can be a low-friction option on smaller amounts. None of this changes what you book — the fee is the customer's transaction cost to the network, separate from the fiat amount your invoice locked.
The XRP Ledger also requires an account to hold a minimum amount of XRP as a reserve to exist on the ledger. This is a wallet-side concern for the payer, not something your invoice controls or that affects the amount that lands on the invoice's address. From halfin's side the only thing that matters is that the correct XRP amount arrives and validates; how the payer's account is funded and reserved is its own business.
How halfin accepts and pays out on the XRP Ledger
Acceptance on the XRP Ledger runs through the same surfaces as every other rail, with the consensus mechanics handled underneath. You bill a fiat amount and the customer chooses to pay in XRP; halfin issues an XRP Ledger deposit destination, locks the rate so the booked figure does not drift while the customer fetches their wallet, watches the network for the matching payment, and credits the deposit reorg-aware once it validates and meets the settlement condition. The same XRP gate sits behind an invoice, a hosted-checkout page, and a static deposit address — you pick the surface that matches the flow rather than rebuilding on-chain plumbing.
Settlement flows the other way too. A single payout or a mass payout batch sends XRP to a destination on the XRP Ledger, and an outgoing payment validates the same way an inbound one does — submitted, agreed by consensus, applied into a closed ledger. Payouts are deliberate, authorised actions; an XRP Ledger payment does not reverse itself, so returning funds to a customer is an explicit refund rather than a chargeback. The network's finality is the same property that makes a validated inbound payment safe to act on.
The create call below commits to no asset or network — it bills a flat fiat figure, and the customer's choice of XRP at pay time resolves the XRP Ledger rail. The amount is a string end to end, never a float, and an idempotency_key in the request body keeps a retried call from creating a duplicate invoice. The rate locks when the invoice activates, and the resolved asset and network come back on the invoice record and on each signed webhook event, so your ledger always knows a given payment settled on the XRP Ledger. Verify the webhook's HMAC signature before acting, and read the field schemas in the docs rather than guessing them.
curl -X POST https://api.thehalfin.com/api/v1/invoices \
-H "X-API-Key: $HALFIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_fiat": "49.00",
"fiat_currency": "USD",
"deferred": true,
"description": "Pro plan — March",
"idempotency_key": "00000000-0000-4000-8000-000000000003"
}'
# The invoice commits to no network. The customer choosing XRP at pay
# time resolves the XRP Ledger rail; halfin issues an XRP destination,
# locks the rate, and credits the deposit reorg-aware once it validates
# into a closed ledger. Field schemas live at docs.thehalfin.com.