Accept XRP on the XRP Ledger

Some of your customers hold XRP and want to pay with it. The XRP Ledger settles a payment in a few seconds, which means the awkward gap between "customer clicked pay" and "funds are mine" is short by design. halfin accepts XRP on the XRP Ledger behind the same fiat-anchored invoice you use for every other asset: you bill in USD or EUR, the customer pays the XRP equivalent at a locked rate, and you reconcile the fiat figure you started with.

Why a merchant takes XRP at all

XRP is a native asset with its own ledger, not a token riding on a smart-contract chain. The XRP Ledger was built around moving value, and it shows in the experience: a payment reaches consensus and becomes final in roughly the time it takes to read a confirmation screen. For a checkout, that timescale is the whole point — the customer is not staring at a spinner, and you are not holding an order open for an hour waiting on confirmations.

There is a second, quieter reason. A slice of crypto-paying customers simply keep their balance in XRP and would rather not swap into a stablecoin to pay you. If your checkout only speaks USDT and BTC, those customers either bounce or do a manual conversion first and pay late. Offering XRP removes that step. The asset reaches your halfin balance, the invoice settles against your billed fiat amount, and what happens to that balance afterward — hold it, convert it, pay it out — is a separate decision you make on your own schedule.

XRP is a volatile asset, not a stablecoin. That volatility is exactly why the fiat anchor matters: you never quote a customer "send me some XRP" and hope it lands near the right dollar value. The invoice fixes the rate at activation and tells the customer a precise XRP amount to send.

The rate is locked, so XRP's volatility is not your problem

Pricing in a volatile asset is where naive crypto checkouts fall apart. If you quote an XRP amount at draft time and the customer pays ten minutes later, the dollar value of that XRP has moved — and somebody is short. halfin handles XRP the same way it handles every asset: you state the amount in fiat, and halfin converts to XRP and locks that quote when the invoice activates.

From activation, the payable XRP amount is fixed for the life of the invoice. The customer sees a concrete number to send — a specific quantity of XRP to a specific address — and a countdown. If they pay inside the window, the XRP they send settles to the exact fiat figure you billed. If the window elapses, the invoice expires instead of silently re-pricing against a newer rate, and you decide whether to re-issue at the current quote. You carry no FX exposure between quote and payment, and neither does the customer.

• You bill in USD or EUR — the fiat amount is the source of truth, not the XRP quantity.
• The XRP quote locks at activation and is fixed until the invoice is paid or expires.
• An expired invoice is marked expired, not quietly re-quoted at a new rate.
• Underpaid and overpaid amounts are recorded against the invoice, not stranded.

Fast finality, still credited safely

Fast finality is a property of the XRP Ledger, not a shortcut halfin takes. The ledger reaches consensus quickly and a validated transaction is settled — but halfin still credits XRP through the same disciplined path it uses for every rail. Crediting is reorg-aware and respects a per-chain confirmation policy: the deposit is matched to your invoice, the network's settlement condition is satisfied, and only then is the invoice marked paid and the balance credited.

The reason this matters is consistency. Your backend reacts to an invoice reaching paid the same way whether the customer paid in XRP, BTC, or USDT on Tron — the event shape is identical, the lifecycle stages are identical, and the "paid" you see is an amount that actually held. You are not writing a special-case fulfillment branch because XRP confirms differently. It confirms faster; it does not confirm by a different set of rules.

XRP next to the rest of the supported assets

XRP is one rail among several. A single fiat-anchored invoice can present any supported asset, and the customer settles in whichever one they hold — XRP on the XRP Ledger, BTC on Bitcoin, a stablecoin on Tron or Solana. The table below is the real supported surface, so you can see where XRP sits relative to the alternatives and what each rail is good for.

The pattern that repeats across the table is the one that makes a multi-asset checkout maintainable: native asset on its native chain, stablecoins on the chains where the gates actually run, and the same fiat anchor underneath all of it. XRP slots into that without a separate integration.

Present XRP through hosted checkout or your own UI

The shortest path to taking XRP is hosted checkout: halfin renders the payment page, shows the customer the XRP amount, the destination address, and the countdown, and tracks the payment to completion. You point the customer at the page and react to the result. Nothing about the XRP rail leaks into your frontend — you are presenting an invoice, and the invoice happens to be payable in XRP.

If you render your own payment UI, the same invoice object is available against the API, and you display the XRP amount and address yourself. Either way the lifecycle is identical, and either way your backend learns the outcome the same way: a signed webhook. Verify the HMAC signature before you act on the event, then fulfill, email, or update your records. The canonical events you will see on an XRP payment are the same ones every invoice emits — activated, paid, underpaid, overpaid, expired.

Create an XRP-payable invoice with one call

Taking XRP is not a separate endpoint or a special flag. You create a fiat-anchored invoice exactly as you would for any asset; the supported assets — XRP included — are drawn from the platform's real gate list. Authenticate with a scoped API key, post the fiat amount and currency, and pass an idempotency key so a retried request never creates a duplicate invoice.

Monetary values are strings end to end — never floats — so the amount goes over the wire as a string. The exact response shape, and how to scope an invoice to a specific asset or network, are defined in the docs and the @halfin/sdk-merchant types; the point here is that one authenticated call gives you a payable invoice that a customer can settle in XRP on the XRP Ledger.

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-000000000001"
  }'

# halfin locks the fiat-to-XRP rate at activation, pins the payable
# XRP amount, and returns an invoice you present via hosted checkout
# and then track with signed webhook events.
# See docs.thehalfin.com for the full request and response schema.