How payments work
The life of a Railbed payment, from the checkout to the USDC in your wallet, and what each status means for the order behind it.
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 see the card providers that can take this payment in their country, ranked by Smart Routing. 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.
- The USDC is forwarded to your wallet. Your share goes straight to the payout wallet saved in your dashboard, on the Polygon network. 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 | 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. Review it in the dashboard, where you can accept it as paid |
failed | Declined. Test mode only for now: live providers don't report declines | Let the buyer try again with a new session |
expired | Nobody paid within the session's time (24 hours for API sessions) | Treat as abandoned, but keep listening: money that arrives late still settles and the payment becomes paid or held |
A payment link the merchant cancels before the payer has gone to a card provider also reads expired, with canceled_at set.
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 90% of the order's value in USD. Anything less is held for your review rather than paid, so an order is never fulfilled on a large shortfall by accident. Orders in EUR, GBP, CAD or AUD are converted to USD at the rate when the buyer starts.
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 are handled by the provider that charged the card, under its own terms.
Timing
| Step | Typical time |
|---|---|
| Checkout session lifetime (API) | 24 hours from creation |
| Payment link lifetime | 1–30 days, 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 |
| Webhook retries | For about a day: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then 12 hours |