Testing

Test mode simulates payments end to end, with no card charged and no money moved. Make payments succeed, fall short or be declined on demand, send sample webhook events, and go live with confidence.

On this page

Test mode

Test mode is a complete, separate copy of your account. Test keys start with rb_test_, and everything they create is simulated: checkouts, payments, settlement and webhooks all behave as in Live mode, but no card is charged and no money moves. Switch the dashboard between Test and Live from the business block at the top of the sidebar: open it and turn Test mode on or off.

Test modeLive mode
Secret keysrb_test_…rb_live_…
Card paymentsSimulated on Railbed's test provider pageReal, on the provider's page
SettlementSimulated, with the same checks as liveUSDC to your payout wallet
Webhook endpointsAny https:// address (for your own computer, a tunnel)Public https:// addresses only
WebhooksReal, signed HTTP requests to your endpointsThe same
POST /v1/payments/:id/simulateAvailableRefused
AI agentsThe default when you approve oneOnly if you choose Live when you approve it

Test and live data never mix: a test key can't read or change a live payment, and each mode has its own endpoints and keys.

Simulate an outcome as a buyer

Only your own team can pay a Test page, so a Test link shared by mistake can never look like it took a payment. First turn Test payments on in your browser: open a checkout from its Share tab, or an invoice from its Send it card, in Test mode and choose Open it to try a payment (Owner, Manager and Developer roles), or, for API sessions, choose Turn on Test payments in this browser under API keys on Developers or on the API setup screen, in Live or Test mode (Owner and Developer roles). That browser can then simulate payments for seven days. Anyone else who opens a Test page is told it's a test page and can't pay. Shopify and WooCommerce Test checkouts keep their own preview links.

Then open a test session's url (or any Test checkout or invoice) in that browser, enter an email and choose Pay. The test provider page offers three outcomes:

  • Simulate successful payment: about 97% of the order's value arrives, as a real provider's fee would leave it, and the payment becomes paid.
  • Simulate an underpayment: half arrives, so the payment is held (Needs your decision in the dashboard), exactly as a live shortfall would be.
  • Simulate declined card: the payment stays open. Return to checkout and choose another way to pay on the same payment.

Venmo and crypto payments are simulated on Railbed's own pay card instead, as paid or underpaid; Venmo's simulated money arrives in full, as the buyer would send it.

On orders worth about 75 USD or more in USD, EUR or GBP, the Test list also has Apple Pay, Alipay and WeChat Pay. Apple Pay's simulated money arrives as USDC on Ethereum (erc20_usdc) and the other two's as USDT there (erc20_usdt), as it would in Live, where it's offered to any ordinary payout wallet (details). Google Pay as a provider of its own is paused, in Test as in Live. From 6 USD (or the same in GBP) the Test list has Rampnow, whose simulated money arrives as ETH on Ethereum (eth) at a fixed test price of 2,239 USD an ETH. Cash App's simulated money arrives as USDT on BNB Chain (bep20_usdt). For buyers in the US, from about 3 USD, the Test list has Venmo, whose simulated money arrives as PayPal USD on Ethereum (erc20_pyusd). Buyers in Canada paying 100 CAD or more also see Interac e-Transfer.

Simulate an outcome from your server

To test without a browser, start the session and simulate the outcome through the API. Use declined to test trying another provider on the same payment. Use failed to test a terminal failure and its payment.failed webhook.

# Start it (the buyer would normally do this by choosing a provider)
curl -X POST \
  https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN/start \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_email": "buyer@example.com" }'

# Choose an outcome: "paid", "underpaid", "declined" or "failed"
curl -X POST \
  https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN/simulate \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

Simulated money runs through the same settlement checks and webhooks as a live payment. A declined outcome records the card decline without a failed webhook or a final payment state, so the same session can be retried. Simulating again on a finished payment returns it unchanged. See Simulate a payment for the details.

Send sample webhook events

In Developers, choose Send test event on a Test endpoint and pick any event. Railbed sends a signed, realistic event with a made-up payment, order and customer (the payment's metadata.sample is "true", the order is ord_sample and the customer cus_sample, and none of them is in your account or the API), then shows the exact body your server received and how it answered. Live endpoints can receive a ping only, so a live system never sees a payment that didn't happen. Invoice events send a made-up invoice (and, for invoice.paid and invoice.partially_paid, the payment toward it). A receiver that reads the payment back gets 404 for a sample: acknowledge samples with 2xx rather than failing them.

Every delivery, test or real, appears in the endpoint's delivery log with its body, and can be sent again.

Receive webhooks on your own computer

Railbed sends webhooks from the internet, so it can't reach a server that only listens on your computer. While you build, expose your local server through a tunnel that gives it a public https:// address (for example Cloudflare Tunnel or ngrok), and add that address as a Test endpoint. When the tunnel's address changes, edit the endpoint: pending retries go to the new address.

A test plan worth running

Before going live, check that your integration handles each of these without a human:

ScenarioHow to cause itExpected result
A normal paymentSimulate paidOrder fulfilled once
The same event twiceResend a delivery from the delivery logNothing changes the second time
An underpaymentSimulate underpaidOrder not fulfilled; payment.held received
A card declineSimulate declinedOrder not fulfilled; buyer can retry another provider on the same session
A terminal failureSimulate failedOrder not fulfilled; payment.failed received; a new session is needed
A buyer who never paysCreate a session and leave itOrder not fulfilled; payment.expired after 24 hours
A lost create responseSend the same create request twice with one Idempotency-KeyOne payment, the same id both times
A second try at one orderCreate two sessions with the same order.id and new keys, and pay the secondOne order, both payments in its payment_ids, fulfilled once
A paid order sent againCreate another session for an order.id that's paid409 order_paid; the buyer isn't asked to pay twice
Your server is downPoint the endpoint at a failing address, then fix itDeliveries retry; Retry now in the log delivers it
A forged webhookSend a request with a wrong signatureYour endpoint rejects it with a 4xx

Going live

  1. Add your payout wallet in Settings. It must be a self-custody wallet you control, not an exchange deposit address. An ordinary wallet works for every provider; a smart contract wallet such as a Safe works on Polygon only, so it doesn't get the providers that pay on other networks.
  2. Turn off Test mode in the sidebar's business block so the dashboard is in Live, and create a live key and live webhook endpoints. Live endpoints need public https:// addresses.
  3. Put the live key and the live endpoint's signing secret on your production server. Keep the test ones for your test environment. An AI agent you connected in Test stays in Test: if it should work on live data, connect it again and choose Live.
  4. Take one small real payment and follow it through: payment.paid received, the order fulfilled once, USDC in your wallet.

Updated · This page as Markdown