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.
- Order placed. Your server saves the order, then calls
POST /v1/checkout_sessions. - Redirect. Your server sends the buyer to the session's
url. - Payment. The buyer pays on the provider's page, in its own tab.
- Return. The Railbed tab sees the payment confirmed and sends the buyer to your
success_url. - Fulfilment. Your server fulfils the order from the
payment.paidwebhook orGET /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);
});# Flask: after saving the order
@app.post("/checkout")
def checkout():
order = orders.create(
user_id=current_user.id,
sku="pro-monthly",
price="49.00",
currency="USD",
)
r = requests.post(
"https://pay.railbed.io/v1/checkout_sessions",
headers={
"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}",
"Idempotency-Key": f"order_{order.id}",
},
json={
"amount": order.price,
"currency": order.currency,
"description": "Pro Membership · monthly",
"reference": f"order_{order.id}",
"customer_email": current_user.email,
"metadata": {"user_id": str(current_user.id)},
"success_url": (
f"https://yourstore.com/orders/{order.id}"
f"/thanks?payment={{PAYMENT_ID}}"
),
"cancel_url": "https://yourstore.com/cart",
},
timeout=15,
)
if not r.ok:
return "Checkout is unavailable. Try again in a moment.", 502
session = r.json()
orders.update(order.id, payment_id=session["id"])
return redirect(session["url"], code=303)<?php
// After saving the order
$ch = curl_init('https://pay.railbed.io/v1/checkout_sessions');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order_' . $order['id'],
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => $order['price'],
'currency' => $order['currency'],
'description' => 'Pro Membership · monthly',
'reference' => 'order_' . $order['id'],
'customer_email' => $user['email'],
'metadata' => ['user_id' => (string) $user['id']],
'success_url' => 'https://yourstore.com/orders/' . $order['id']
. '/thanks?payment={PAYMENT_ID}',
'cancel_url' => 'https://yourstore.com/cart',
]),
]);
$session = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 300) {
http_response_code(502);
exit('Checkout is unavailable.');
}
save_payment_id($order['id'], $session['id']);
header('Location: ' . $session['url'], true, 303);Return URLs
| Field | When the buyer sees it |
|---|---|
success_url | Once 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_url | A 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 code | Server only | Server, plus a few lines in the page buyers pay from |
| Buyers | Leave your page while they pay, and come back to your success_url | Stay on your page. The card provider still opens in its own tab |
| Where it works | Every browser, in-app browsers and mobile apps | Websites 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 browsers | The provider opens in the checkout's tab | The 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:
<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 sessionurlfrom the host that servesembed.js(https://pay.railbed.io/p/pay_…) or the session's id (pay_…), and rejects anything else. The promise resolves with{ status, session }, wherestatusispaid,held,failed,expiredorclosed; it's a hint for your page, not proof of payment. The embedded checkout guide has the npm package'sopenCheckout. - After payment. Once the payment is confirmed, your whole page goes to your
success_url, as it would from Railbed's page. Without asuccess_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.ioinscript-srcandframe-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. Whatcustomerandorderalready 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).