How payments work
The life of a Railbed payment, from the checkout to the money in your wallet, and what each status means for the order behind it.
On this page
The journey of one payment
- Your server creates a checkout session for an order: amount, currency, description and your reference. Nothing is charged yet, and nothing is reserved.
- The buyer starts paying. On Railbed's hosted page (or your own screen) they enter an email (and any details your checkout asks for) and see the card providers that can take this payment in their country: in the order you saved in Integrations → Card providers, or ranked by Smart Routing, or straight to one provider if you chose that. Starting assigns the payment a one-time deposit address and locks the fee and the order's value in USD.
- The buyer pays on the provider's page. The provider (Stripe, Coinbase, PayPal and others) runs its own card checkout and any identity check it requires, then buys USDC with the card payment and sends it to the payment's deposit address.
- Your share is forwarded to your wallet. It goes straight to the payout wallet saved in your dashboard (or the other saved wallet an invoice pays), on the network the provider paid on: Polygon for almost every provider, and another network for a few, such as Apple Pay on Ethereum. Railbed never holds it.
- Railbed checks the settlement before calling the payment paid: the right amount reached the right wallet, and the transaction hasn't been counted before. Then the payment becomes
paid, and your webhooks and API report it.
The buyer's checkout tab waits while they pay and sends them to your success_url once the payment is confirmed. Providers don't send buyers back on their own, so your order should never depend on the redirect: fulfil from the webhook or the API.
Statuses
| Status | Meaning | What to do |
|---|---|---|
open | Created, or started but not yet handed to a provider | Wait. The buyer hasn't paid |
pending | The buyer went to a provider to pay, or was shown a crypto address | Wait. How long depends on the provider; see timing |
paid | The money arrived and passed Railbed's checks | Fulfil the order, once |
held | Money arrived but failed a check, usually because less arrived than expected | Don't fulfil yet. The dashboard shows it as Needs your decision, where you can accept it as paid, or Not received when it can't be accepted (hold_acceptable: false) |
failed | Terminal Test failure. Live providers do not report declines | Let the buyer try again with a new session |
expired | Nobody paid within the session's time (24 hours for API sessions, or 2 hours after the buyer last went to a provider if that's later) | Treat as abandoned, but keep listening: money that arrives late still settles and the payment becomes paid or held |
A session or invoice link canceled before the buyer has gone to a provider (with POST /v1/checkout_sessions/:id/cancel or in the dashboard) also reads expired, with canceled_at set, and sends payment.canceled. Money that still arrives settles it.
What arrives in your wallet
Providers charge the buyer the order's price in their currency and deliver USDC for it. The amount that arrives (value_coin) is lower than the price because the provider keeps its own fee and spread. From that, a 1% network fee and the Railbed fee shown in your dashboard come off, and the rest (merchant_received) is forwarded to your wallet. The fee that applies is locked when the buyer starts paying, so a later fee change never affects a payment already in progress.
A payment counts as paid when what arrived is at least 85% of the order's value in USD (Railbed's current setting). Anything less is held for your decision rather than paid, so an order is never fulfilled on a large shortfall by accident. Orders in EUR, GBP, CAD, AUD, INR or SEK are converted to USD at the rate when the buyer starts; a payment still unpaid a day after it started is converted again when the buyer next goes to pay.
Crypto payments
Card always comes first. A business that turns on crypto payments in Settings also lets buyers on the hosted page send USDC or USDT on Polygon, Base, Arbitrum, Optimism, BNB Chain or Ethereum to a one-time deposit address, forwarded to the payout wallet like a card sale, and, on networks where the business saved a wallet of its own (Bitcoin, Solana, TRON and others), that network's coin straight to that wallet. Such a payment has method: "crypto" and its network in settlement.network, and it's judged by the same rule: its value in USD against the order. An API session reaches crypto only on its hosted url.
Card payments on other networks
Buyers can use Apple Pay and Google Pay through providers such as Stripe, which pay on Polygon like any card. A few providers pay into the payment's deposit address on another network instead, and your share is forwarded on that network to the same wallet address:
| Provider | What arrives | Prices it takes |
|---|---|---|
| Apple Pay, as a provider of its own | USDC or USDT on Ethereum (erc20_usdc, erc20_usdt) | USD, EUR or GBP |
| Alipay and WeChat Pay | USDT on Ethereum (erc20_usdt) | USD, EUR or GBP; first for buyers in mainland China, Hong Kong and Macau |
| Rampnow | ETH on Ethereum (eth), valued in USD at the payment network's price when it arrives | USD or GBP |
| Cash App | USDT on BNB Chain (bep20_usdt), for buyers in the US | Any |
| Venmo, paid on Railbed's own pay card | PayPal USD on Ethereum (erc20_pyusd), sent by the buyer from the Venmo app | Any, at its US dollar value, for buyers in the US |
Google Pay as a provider of its own is paused for now; buyers still pay with Google Pay through card providers such as Stripe.
Railbed offers these providers only where they work for you:
- An ordinary wallet. In Live, they're offered only while your payout wallet is an ordinary self-custody wallet, whose address is the same on every network. A smart contract wallet such as a Safe never gets them, because it may not exist on those networks.
- Larger orders on Ethereum. Forwarding from Ethereum costs more, and the cost comes out of your share, so Apple Pay, Alipay, WeChat Pay, Rampnow and Venmo take an order only when forwarding costs at most 3% of it: about 75 USD when forwarding costs 2.25 USD, and only a few dollars when it costs cents. Rampnow's smallest order also covers the network's own minimum for ETH. Integrations → Card providers shows today's figure.
- Smart Routing behind them on Ethereum. A checkout set to One provider can name Apple Pay, Alipay, WeChat Pay, Rampnow or Venmo only with the Smart Routing fallback on.
What arrives is judged like any card payment, by its value in USD against the order, so a payment is never held because of the coin or the network it came on. If forwarding costs more than expected, less reaches your wallet, but the payment still counts as paid when the buyer paid in full.
In Test mode, Apple Pay, Alipay and WeChat Pay are on the list from about 75 USD and Rampnow from 6 USD, and their simulated money arrives as erc20_usdc, erc20_usdt and eth; Cash App's arrives as bep20_usdt, and Venmo's, from about 3 USD for buyers in the US, as erc20_pyusd.
Identity checks
Each provider decides whether to ask the buyer for identification, usually based on amount, country and history. Smart Routing ranks the providers least likely to ask first, but it can't promise that a provider won't. The buyer's identity details stay with the provider.
Refunds and disputes
A settled payment can't be reversed by Railbed: the money is already in your wallet. To refund a buyer, send the funds back yourself. Card disputes and chargebacks go to the provider that charged the card, and a settled payment can't be pulled back from your wallet.
Timing
| Step | Typical time |
|---|---|
| Checkout session lifetime (API) | 24 hours from creation, or 2 hours after the buyer last went to a provider if that's later |
Invoice link lifetime (/v1/payment_links) | 1 day to a year (7 days by default), chosen when it's created |
| Card payment on the provider's page | A few minutes |
| Settlement after the provider sends USDC | As soon as the forwarding is reported; if that report is late, Railbed checks unsettled payments on a schedule for up to two days. Money that arrived on Ethereum or BNB Chain waits about 15 minutes for that report; after that the next check judges it like any payment, and a late report fills in the details |
| Webhook retries | For about a day: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then 12 hours |