Hosted checkout

Create a checkout session for each order on your server, send the buyer to Railbed's hosted page, and bring them back to your store once they've paid.

On this page

How it works

Your server creates a checkout session for the order and redirects the buyer to its url. (Or your page opens the same url in a pop-up over itself.) Railbed's page asks for the buyer's email, shows the card providers that can take this payment in their country (the recommended one first), and opens the chosen provider in a new tab. The checkout tab waits there while the buyer pays, then sends them to your success_url.

  1. Order placed. Your server saves the order, then calls POST /v1/checkout_sessions.
  2. Redirect. Your server sends the buyer to the session's url.
  3. Payment. The buyer pays on the provider's page, in its own tab.
  4. Return. The Railbed tab sees the payment confirmed and sends the buyer to your success_url.
  5. Fulfilment. Your server fulfils the order from the payment.paid webhook or GET /v1/payments/:id, never from the return alone.

Create the session

Create one session per order attempt, with an Idempotency-Key saved alongside the order before you call. A retry after a timeout then returns the same session instead of creating a second one.

// POST /checkout on your server, after saving the order
app.post('/checkout', async (req, res) => {
  const order = await orders.create({
    userId: req.user.id,
    sku: 'pro-monthly',
    price: '49.00',
    currency: 'USD',
  });

  const response = await fetch('https://pay.railbed.io/v1/checkout_sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `order_${order.id}`,
    },
    body: JSON.stringify({
      amount: order.price,
      currency: order.currency,
      description: 'Pro Membership · monthly',
      reference: `order_${order.id}`,
      customer_email: req.user.email,
      metadata: { user_id: String(req.user.id) },
      success_url:
        `https://yourstore.com/orders/${order.id}/thanks?payment={PAYMENT_ID}`,
      cancel_url: `https://yourstore.com/cart`,
    }),
  });
  if (!response.ok) {
    return res.status(502).send(
      'Checkout is unavailable. Try again in a moment.',
    );
  }
  const session = await response.json();

  await orders.update(order.id, { paymentId: session.id });
  res.redirect(303, session.url);
});

Return URLs

FieldWhen the buyer sees it
success_urlOnce the payment is confirmed, the Railbed checkout tab sends the buyer here. {PAYMENT_ID} and {REFERENCE} in the address are replaced with the payment's id and your reference
cancel_urlA link back to your store, named after your business, while the buyer is paying and after a decline or an expiry

Both are optional, up to 1,000 characters, and can't contain a username or password or be a Railbed page (a checkout's link, say). In Live mode they must be public https:// addresses: localhost, private network addresses and local names are refused, since a buyer couldn't open them. Test mode also accepts http:// and localhost. Without a success_url, the buyer sees Railbed's own confirmation.

Open it in a pop-up instead

Sending the buyer to the session's url is the default: it needs only server code and works in every browser and app. If your site or web app would rather keep buyers on its own page, it can open the same url in a pop-up over itself. Your server still creates the session; your page shows it.

Railbed's page (the default)A pop-up on your page
Your codeServer onlyServer, plus a few lines in the page buyers pay from
BuyersLeave your page while they pay, and come back to your success_urlStay on your page. The card provider still opens in its own tab
Where it worksEvery browser, in-app browsers and mobile appsWebsites and web apps. A mobile app opens the url in the browser instead
When a browser can't open a new tab, as in some in-app browsersThe provider opens in the checkout's tabThe provider opens in place of your page

Return the session's url to your page instead of redirecting, then open it with Railbed.open from the embed script:

Open the session over your page
<script src="https://pay.railbed.io/embed.js" async></script>
<script>
  async function pay(orderId) {
    // Your server creates the session, as above, and returns its url.
    const res = await fetch('/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ orderId }),
    });
    const { url } = await res.json();
    if (!window.Railbed) return location.assign(url); // still loading: use the page
    Railbed.open(url).then(
      () => showOrderStatus(orderId), // closed: ask your server whether it's paid
      () => location.assign(url),     // not a session url: use the page
    );
  }
</script>
  • One at a time. Railbed.open(url) shows one pop-up and returns a promise that resolves when the buyer closes it; calling it again meanwhile returns the same promise. If one of your buy buttons already has its pop-up open, it opens nothing and resolves at once. It accepts a session url from the host that serves embed.js (https://pay.railbed.io/p/pay_…) or the session's id (pay_…), and rejects anything else. The promise resolves with { status, session }, where status is paid, held, failed, expired or closed; it's a hint for your page, not proof of payment. The embedded checkout guide has the npm package's openCheckout.
  • After payment. Once the payment is confirmed, your whole page goes to your success_url, as it would from Railbed's page. Without a success_url, the pop-up shows the confirmation and your page stays.
  • While paying. As long as the buyer is paying in the provider's tab, the pop-up asks before it closes.
  • cancel_url. Its link takes your whole page there. In a pop-up you can leave it out: buyers close the pop-up instead.
  • Content Security Policy. If your site sets one, allow https://pay.railbed.io in script-src and frame-src.

Closing the pop-up, like reaching your success_url, isn't proof of payment: fulfil from the webhook or GET /v1/payments/:id.

What the buyer sees

  • The order. Your business name and logo, the description and the price, in the currency you set.
  • Their email. Prefilled when you send customer_email. Providers use it for their receipt.
  • Their details, when you ask for them with collect: name, phone, date of birth, addresses, an email-list box or questions of your own. What customer and order already hold is filled in; what's required must be given before the provider opens.
  • Card providers. Only those that serve the buyer's country, take the currency and accept the amount, and that you haven't turned off in Integrations → Card providers, in your order there with the best match first. The buyer pays on the provider's page; Venmo is the exception, paid from the Venmo app with the details Railbed's own page shows.
  • Crypto, only if you turned on crypto payments in Settings: the buyer can send stablecoins instead, with card still first. Providers this buyer already tried for the order come last, marked You tried this, and are never the recommended one.
  • Waiting. The checkout tab says to finish paying in the provider's tab and updates by itself. If the browser blocks the new tab, the provider opens in the same tab instead. A buyer who comes back before the payment arrives is asked whether they finished, with Choose another way to pay first (what they see).
  • The result. Paid, being reviewed (held), declined or expired, each with a clear next step. An expired session whose buyer reached a provider tells them not to pay again, since money still on its way settles it.

A session can be paid for 24 hours. After that it's expired; create a new one if the buyer comes back.

When there's no provider

Providers have minimum amounts and regional limits. An amount under every provider's minimum is refused when the session is created (400 invalid_amount, naming the smallest card payment), so a buyer never reaches a page nobody can take. When no provider can take a payment for the buyer in front of it, the checkout says why: nobody serves their country, or every provider that could is unavailable for now. Orders of a few dollars have the fewest providers; the create response's warnings say so (Provider minimums).

Updated · This page as Markdown