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

  1. Your server creates a checkout session for an order: amount, currency, description and your reference. Nothing is charged yet, and nothing is reserved.
  2. 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.
  3. 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.
  4. 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.
  5. 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

StatusMeaningWhat to do
openCreated, or started but not yet handed to a providerWait. The buyer hasn't paid
pendingThe buyer went to a provider to pay, or was shown a crypto addressWait. How long depends on the provider; see timing
paidThe money arrived and passed Railbed's checksFulfil the order, once
heldMoney arrived but failed a check, usually because less arrived than expectedDon'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)
failedTerminal Test failure. Live providers do not report declinesLet the buyer try again with a new session
expiredNobody 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:

ProviderWhat arrivesPrices it takes
Apple Pay, as a provider of its ownUSDC or USDT on Ethereum (erc20_usdc, erc20_usdt)USD, EUR or GBP
Alipay and WeChat PayUSDT on Ethereum (erc20_usdt)USD, EUR or GBP; first for buyers in mainland China, Hong Kong and Macau
RampnowETH on Ethereum (eth), valued in USD at the payment network's price when it arrivesUSD or GBP
Cash AppUSDT on BNB Chain (bep20_usdt), for buyers in the USAny
Venmo, paid on Railbed's own pay cardPayPal USD on Ethereum (erc20_pyusd), sent by the buyer from the Venmo appAny, 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

StepTypical 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 pageA few minutes
Settlement after the provider sends USDCAs 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 retriesFor about a day: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then 12 hours

Updated · This page as Markdown