Checkout sessions
A checkout session is one payment for one order. Create it on your server, send the buyer to its page or start it for your own checkout, and read its payment to fulfil.
On this page
The checkout session object
| Field | Type | Description |
|---|---|---|
id | string | The session's id, pay_…. The same id identifies its payment |
object | string | "checkout_session" |
url | string | The hosted checkout page for this session. Send the buyer here, or open it over your page with Railbed.open (pop-up) |
status | string | open, pending, paid, held, failed or expired. See statuses |
livemode | boolean | false for Test mode, true for Live mode |
amount | string | The price, as set at creation: "49.00" |
currency | string | USD, EUR, GBP, CAD, AUD, INR or SEK |
description | string | What the buyer is paying for, shown on the checkout |
reference | string or null | Your own id for the order |
customer_email | string or null | The buyer's email, lowercased |
created | integer | When it was created, in Unix seconds |
expires_at | integer | When it stops accepting new payments: 24 hours after creation |
started_at | integer or null | When the buyer (or your server) started it. Set once |
metadata | object or null | Your normalized key-value pairs, returned on the session, payment and webhook |
order_id | string or null | The order this session is a payment attempt for, ord_…. Every session has one (null only on records from before orders existed) |
collect | object or null | What the hosted page asks the buyer for besides their email, or null for nothing more. See The collect field |
canceled_at | integer or null | When you canceled it, in Unix seconds. null until then |
checkout_id | string or null | The checkout the session was made from, chk_…. null for a session you described yourself. See From a saved checkout |
plan_label | string or null | The pricing-table plan, as buyers see it: "Pro · Yearly", or "Pro" on a table without a switch. null otherwise |
warnings | array | On the create response only, and only when there is something to say: what the card providers' minimums mean for this amount. See Provider minimums |
Create a checkout session
POST /v1/checkout_sessions
Creates a session for one order. Nothing is charged and no provider is contacted until the buyer starts paying. Send an Idempotency-Key so a retry returns the same session.
| Field | Type | Description |
|---|---|---|
amount | string Required | Leave it out when you send checkout. The price as a decimal string with at most two decimals, from "1.00" to "100000.00". "49" and "49.0" become "49.00". Numbers, exponents and negative values are refused, and so is an amount under the smallest card payment (about "2.00" USD): see Provider minimums |
currency | string Required | Leave it out when you send checkout. USD, EUR, GBP, CAD, AUD, INR or SEK, in any letter case |
description | string Required | Leave it out when you send checkout. What the buyer is paying for, up to 120 Unicode code points after text normalization |
customer_email | string or null | The buyer's email. Optional here, but needed before the session can start |
reference | string or null | Your order id, up to 120 Unicode code points after text normalization. Returned on the payment and every webhook. Not unique: Railbed doesn't stop two sessions sharing one |
metadata | object or null | Up to 20 normalized keys (1–40 Unicode code points, not starting with __) with string values up to 500 code points. See normalization rules. For your own ids, never secrets or card details |
success_url | string or null | Where the checkout sends the buyer once the payment is confirmed. {PAYMENT_ID} and {REFERENCE} are filled in. Up to 1,000 characters |
cancel_url | string or null | Where the checkout's "Cancel and return to …" and "Back to …" links lead (they name your business). Up to 1,000 characters |
customer | object or null | Who is buying: name, phone and your customer id. See Orders and customers |
order | object or null | What they're buying: items, discount, shipping, tax, addresses and your order id. See Orders and customers |
collect | object or null | What the hosted page asks the buyer for besides their email. Leave it out and the page asks nothing more, as before. See The collect field |
checkout | string or null | Make the session from one of your checkouts instead of describing it: its id (chk_…) or slug. See From a saved checkout |
plan | string or null | With checkout, for a pricing table: the id of the plan the buyer chose |
option | integer or null | With checkout, for a pricing table with a switch: 0 for its first option, 1 for its second |
Return URLs must be full http:// or https:// addresses with no username or password, and not on a Railbed host (pay.railbed.io, app.railbed.io). In Live mode they must be public https:// addresses: localhost, *.localhost, loopback and private IP addresses, single-word hosts and local names (.local, .internal, .lan, .home.arpa, .test) are refused. Test mode accepts http:// and localhost. They are stored in the standard URL parser’s normalized form: the hostname is lowercased, default ports are omitted, and . or .. path segments are resolved. For example, https://EXAMPLE.com:443/orders/../thanks becomes https://example.com/thanks. Encoded template tokens are still filled when the buyer returns. In Live mode your account needs a payout wallet first, or the request gets 409 no_payout_wallet. An account that has paused taking payments gets 409 commerce_paused, and a suspended or archived one 403 merchant_read_only (its reads still work).
curl https://pay.railbed.io/v1/checkout_sessions \
-H "Authorization: Bearer $RAILBED_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1042" \
-d '{
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"metadata": { "user_id": "player_1042" },
"success_url":
"https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}",
"cancel_url": "https://yourstore.com/cart"
}'const res = 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_1042',
},
body: JSON.stringify({
amount: '49.00',
currency: 'USD',
description: 'Pro Membership',
reference: 'order_1042',
customer_email: 'buyer@example.com',
metadata: { user_id: 'player_1042' },
success_url:
'https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}',
cancel_url: 'https://yourstore.com/cart',
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const session = await res.json();r = requests.post(
"https://pay.railbed.io/v1/checkout_sessions",
headers={
"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}",
"Idempotency-Key": "order_1042",
},
json={
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"metadata": {"user_id": "player_1042"},
"success_url": (
"https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}"
),
"cancel_url": "https://yourstore.com/cart",
},
timeout=15,
)
r.raise_for_status()
session = r.json()<?php
$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_1042',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => '49.00',
'currency' => 'USD',
'description' => 'Pro Membership',
'reference' => 'order_1042',
'customer_email' => 'buyer@example.com',
'metadata' => ['user_id' => 'player_1042'],
'success_url' =>
'https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}',
'cancel_url' => 'https://yourstore.com/cart',
]),
]);
$session = json_decode(curl_exec($ch), true);{
"id": "pay_7AAiYH0Ykt11ED4hmfiN",
"object": "checkout_session",
"url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
"status": "open",
"livemode": false,
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"created": 1790380525,
"expires_at": 1790466925,
"started_at": null,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": null
}A retry with the same Idempotency-Key and validated, normalized body answers 200 OK with the same session. Only this endpoint and Create an invoice honor the header.
From a saved checkout
Send checkout instead of a price to make the session from a page, widget or pricing table you made in the dashboard. This is how an embedded checkout tells you which of your users paid: the buyer picks a plan and presses Continue on your site, your server makes the session for its signed-in user with your own reference and metadata, and the buyer pays it in the same frame. Know which of your users paid has a route handler.
| Field | Type | Description |
|---|---|---|
checkout | string Required | The checkout's id (chk_…) or slug, in the same mode as your key. List checkouts returns both |
plan | string or null | The id of the plan the buyer chose (plans[].id on the checkout). Required for a pricing table, refused for a page or widget |
option | integer or null | 0 or 1: which side of the pricing table's switch (options, such as ["Monthly", "Yearly"]) the buyer chose. Required when the table has a switch, refused otherwise |
customer_email, customer, reference, metadata, success_url, cancel_url and the Idempotency-Key work as on any session. amount, currency, description, collect and order come from the checkout, so sending any of them answers 400 field_not_allowed.
The session copies these from the checkout when it's made, and keeps them if the checkout changes later:
amountandcurrency: the checkout's price, or for a pricing table the chosen plan's price on the chosen side of the switch.description: the checkout's name. The order's line item is the checkout's name with the plan beside it.plan_label: the plan as the buyer saw it, such as"Pro · Yearly".success_url: the checkout's, unless you send your own.
These follow the checkout until the buyer pays: the details its page asks for (the session's collect reads null, and the checkout's settings apply), whether buyers may pay in crypto, its look, and how buyers reach a card provider. A session you start yourself for your own checkout still gets the full list of providers.
When you send customer_email, the payment uses that email, whatever the buyer types on the checkout. Leave it out and the buyer's own email is used.
A checkout that is turned off takes no new sessions. A session made before it was turned off or deleted can still be paid until it expires, so cancel one you no longer want with Cancel a checkout session.
const res = 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': attempt.idempotencyKey, // saved with the attempt
},
body: JSON.stringify({
checkout: 'chk_Np4wQ8sT2mXv7KcZr5Ld',
plan: 'plan_7Qm2Xc9Lk4TzR8vNw3Hp', // from GET /v1/checkouts/:id
option: 1, // Yearly
reference: 'user_1042',
customer_email: 'player@example.com',
metadata: { user_id: 'player_1042' },
}),
});
const session = await res.json(); // amount "490.00", plan_label "Pro · Yearly"{
"id": "pay_Hq2Nc6Vx9LmT4bRz8KpW",
"object": "checkout_session",
"url": "https://pay.railbed.io/p/pay_Hq2Nc6Vx9LmT4bRz8KpW",
"status": "open",
"livemode": false,
"amount": "490.00",
"currency": "USD",
"description": "Membership",
"reference": "user_1042",
"customer_email": "player@example.com",
"created": 1790380525,
"expires_at": 1790466925,
"started_at": null,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_Wc5Lr9Tz2QmX7vKn3BsH",
"collect": null,
"canceled_at": null,
"checkout_id": "chk_Np4wQ8sT2mXv7KcZr5Ld",
"plan_label": "Pro · Yearly"
}| Status | Code | When |
|---|---|---|
| 400 | field_not_allowed | amount, currency, description, collect or order was sent with checkout. field names it |
| 400 | invalid_checkout | No checkout with that id or slug in this account and mode |
| 400 | invalid_plan | plan is missing for a pricing table or isn't one of its plans, option is missing for a table with a switch or isn't 0 or 1, or plan or option was sent for a page or widget. field says which |
| 403 | integration_disabled | Checkouts are turned off for the account |
| 409 | checkout_off | The checkout is turned off. Turn it on in the dashboard first |
| 409 | checkout_deleted | The checkout was deleted |
Provider minimums
Each card provider has its own minimum, and Railbed checks amount against them when you create a session, a payment link or a checkout, in the key's mode:
- The floor is the lowest minimum among the card providers you offer (a provider you turned off doesn't count), in your currency (converted at the current rate; about
"2.00"USD today). An amount under it answers400 invalid_amountwith the floor in the message ("Card providers take payments from 2.00 USD. Enter at least 2.00."), and nothing is created. If the provider list or a rate can't be read at that moment, the amount is accepted andwarningssays the minimums couldn't be checked; if the only providers that take it are briefly unavailable, it is accepted andwarningsnames them. - Crypto. An account that takes crypto payments may create an amount no card provider takes, as long as it's big enough to pay in crypto (about
"0.85"USD today); the response says so inwarnings. A smaller amount answers400 invalid_amountas it would without crypto. warningsis on the201response (and an idempotent replay) only when there is something to say. A replay with the sameIdempotency-Keyalways answers its session, with today'swarnings, even if the amount would be refused as a new session. A session made from a saved checkout carrieswarningson its201only: its replay answers the session as it was made, even after the checkout has changed or been deleted. Each entry hascode,messageandminimum(the floor as{ amount, currency }, ornull).limited_coveragemeans fewer than half the card providers take the amount, or buyers in some region (the US, the EU, elsewhere) have at most one: "At 3.00 USD, Stripe, Coinbase and Cash App can take the payment. Buyers outside the US have one provider (Coinbase). From 11.00 USD most providers take it." It is information about today's list, never a promise that a given buyer will be accepted: the provider decides at hand-off.
{
"warnings": [
{
"code": "limited_coverage",
"message": "At 3.00 USD, Stripe, Coinbase and Cash App can take the payment. Buyers outside the US have one provider (Coinbase). From 11.00 USD most providers take it.",
"minimum": { "amount": "2.00", "currency": "USD" }
}
]
}The minimums are the providers' and they change. In Live mode, Integrations → Card providers in the dashboard shows each one's current minimum, and List payment methods answers the same from your code; Test mode checks against a fixed list. Apple Pay and Google Pay show today's line, marked “about”: they pay on Ethereum, take only orders where forwarding from there costs at most 3%, and the line moves with the network's cost (details).
Idempotency
Save the exact request body with its key before the first call, and send that same body on every retry. The key's fingerprint covers:
amount,currency,descriptionandreference- the buyer's email, from
customer_emailorcustomer.email success_urlandcancel_urlmetadata: key order doesn't matter, but spaces inside values do- every field of
orderandcustomer, only when the request sent either collect, only when the request sent it- for a session from a saved checkout:
checkout,planandoptionas you sent them, instead of the amount, currency and description
A session from a checkout is fingerprinted on your request, not on the price it got, so a retry answers the same session even after the checkout's price changed or it was turned off. checkout sent as the id and as the slug are two different requests.
Values are compared after validation and normalization, so "49" and "49.00" match. Any other difference in these fields is 409 idempotency_conflict, including a retry rebuilt from current data: a buyer who changed their email, a renamed item, a return URL on a new domain. Don't retry a conflict with the same key. 409 idempotency_in_progress means a request with that key hasn't finished: wait Retry-After seconds and send the same request again. Idempotency has every case.
Orders and customers
Every session belongs to an order. Send order and customer with the session, and the order has your items, totals, addresses and store order id, and the customer has the buyer's name and phone. They appear in the dashboard's Orders and Customers and in every webhook. Without them, the order has one line, your description, for the whole amount.
The buyer's checkout page still shows your description and the amount. The order's details are for your records, not for the buyer to confirm.
curl https://pay.railbed.io/v1/checkout_sessions \
-H "Authorization: Bearer $RAILBED_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1042-attempt-1" \
-d '{
"amount": "135.31",
"currency": "USD",
"description": "Order #1042",
"reference": "order_1042",
"customer_email": "maya@example.com",
"customer": {
"name": "Maya Okafor",
"phone": "+1 503 555 0142",
"id": "88"
},
"order": {
"id": "1042",
"number": "1042",
"url": "https://yourstore.com/admin/orders/1042",
"store": {
"id": "yourstore",
"name": "yourstore.com",
"url": "https://yourstore.com"
},
"items": [
{
"name": "Magnesium glycinate",
"variant": "120 capsules",
"sku": "HN-MG-120",
"quantity": 2,
"unit_amount": "32.00",
"amount": "64.00"
},
{
"name": "Daily greens",
"sku": "HN-DG-30",
"quantity": 1,
"amount": "54.00"
},
{ "name": "Shaker bottle", "quantity": 1, "amount": "12.00" }
],
"discount": "13.00",
"discount_code": "WELCOME10",
"shipping": "8.95",
"shipping_method": "Standard",
"tax": "9.36",
"shipping_address": {
"name": "Maya Okafor",
"line1": "418 Linden Avenue",
"line2": "Apt 3B",
"city": "Portland",
"region": "OR",
"postal_code": "97214",
"country": "US"
}
},
"success_url": "https://yourstore.com/orders/1042/thanks"
}'const res = 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_1042-attempt-1',
},
body: JSON.stringify({
amount: '135.31',
currency: 'USD',
description: 'Order #1042',
reference: 'order_1042',
customer_email: 'maya@example.com',
customer: { name: 'Maya Okafor', phone: '+1 503 555 0142', id: '88' },
order: {
id: '1042',
number: '1042',
url: 'https://yourstore.com/admin/orders/1042',
store: {
id: 'yourstore',
name: 'yourstore.com',
url: 'https://yourstore.com',
},
items: [
{
name: 'Magnesium glycinate',
variant: '120 capsules',
sku: 'HN-MG-120',
quantity: 2,
unit_amount: '32.00',
amount: '64.00',
},
{ name: 'Daily greens', sku: 'HN-DG-30', quantity: 1, amount: '54.00' },
{ name: 'Shaker bottle', quantity: 1, amount: '12.00' },
],
discount: '13.00',
discount_code: 'WELCOME10',
shipping: '8.95',
shipping_method: 'Standard',
tax: '9.36',
shipping_address: {
name: 'Maya Okafor',
line1: '418 Linden Avenue',
line2: 'Apt 3B',
city: 'Portland',
region: 'OR',
postal_code: '97214',
country: 'US',
},
},
success_url: 'https://yourstore.com/orders/1042/thanks',
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const session = await res.json();r = requests.post(
"https://pay.railbed.io/v1/checkout_sessions",
headers={
"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}",
"Idempotency-Key": "order_1042-attempt-1",
},
json={
"amount": "135.31",
"currency": "USD",
"description": "Order #1042",
"reference": "order_1042",
"customer_email": "maya@example.com",
"customer": {
"name": "Maya Okafor",
"phone": "+1 503 555 0142",
"id": "88",
},
"order": {
"id": "1042",
"number": "1042",
"url": "https://yourstore.com/admin/orders/1042",
"store": {
"id": "yourstore",
"name": "yourstore.com",
"url": "https://yourstore.com",
},
"items": [
{
"name": "Magnesium glycinate",
"variant": "120 capsules",
"sku": "HN-MG-120",
"quantity": 2,
"unit_amount": "32.00",
"amount": "64.00",
},
{
"name": "Daily greens",
"sku": "HN-DG-30",
"quantity": 1,
"amount": "54.00",
},
{"name": "Shaker bottle", "quantity": 1, "amount": "12.00"},
],
"discount": "13.00",
"discount_code": "WELCOME10",
"shipping": "8.95",
"shipping_method": "Standard",
"tax": "9.36",
"shipping_address": {
"name": "Maya Okafor",
"line1": "418 Linden Avenue",
"line2": "Apt 3B",
"city": "Portland",
"region": "OR",
"postal_code": "97214",
"country": "US",
},
},
"success_url": "https://yourstore.com/orders/1042/thanks",
},
timeout=15,
)
r.raise_for_status()
session = r.json()<?php
$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_1042-attempt-1',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => '135.31',
'currency' => 'USD',
'description' => 'Order #1042',
'reference' => 'order_1042',
'customer_email' => 'maya@example.com',
'customer' => [
'name' => 'Maya Okafor',
'phone' => '+1 503 555 0142',
'id' => '88',
],
'order' => [
'id' => '1042',
'number' => '1042',
'url' => 'https://yourstore.com/admin/orders/1042',
'store' => [
'id' => 'yourstore',
'name' => 'yourstore.com',
'url' => 'https://yourstore.com',
],
'items' => [
[
'name' => 'Magnesium glycinate',
'variant' => '120 capsules',
'sku' => 'HN-MG-120',
'quantity' => 2,
'unit_amount' => '32.00',
'amount' => '64.00',
],
[
'name' => 'Daily greens',
'sku' => 'HN-DG-30',
'quantity' => 1,
'amount' => '54.00',
],
['name' => 'Shaker bottle', 'quantity' => 1, 'amount' => '12.00'],
],
'discount' => '13.00',
'discount_code' => 'WELCOME10',
'shipping' => '8.95',
'shipping_method' => 'Standard',
'tax' => '9.36',
'shipping_address' => [
'name' => 'Maya Okafor',
'line1' => '418 Linden Avenue',
'line2' => 'Apt 3B',
'city' => 'Portland',
'region' => 'OR',
'postal_code' => '97214',
'country' => 'US',
],
],
'success_url' => 'https://yourstore.com/orders/1042/thanks',
]),
]);
$session = json_decode(curl_exec($ch), true);{
"id": "pay_Rt5Wm2KxQ8zLb3NvYc7P",
"object": "checkout_session",
"url": "https://pay.railbed.io/p/pay_Rt5Wm2KxQ8zLb3NvYc7P",
"status": "open",
"livemode": true,
"amount": "135.31",
"currency": "USD",
"description": "Order #1042",
"reference": "order_1042",
"customer_email": "maya@example.com",
"created": 1790380525,
"expires_at": 1790466925,
"started_at": null,
"metadata": null,
"order_id": "ord_Vd3kR8mQ1xTn6LpZs0Wa",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": null
}Retrieve the order with order_id to see what was saved.
The customer field
| Field | Type | Description |
|---|---|---|
email | string or null | The buyer's email, with the same rules as customer_email. Send either one; when you send both, they must be the same address |
name | string or null | The buyer's name, up to 120 characters. Without it, the name on the shipping (or billing) address is used |
phone | string or null | Up to 40 characters, in any format |
date_of_birth | string or null | A past date as YYYY-MM-DD. Kept on the customer |
accepts_marketing | boolean or null | true when they agreed to marketing email in your store: they join your list (Customers → Subscribed). false or absent changes nothing, so a later unticked box never unsubscribes anyone |
id | string or null | The buyer's customer id in your store, up to 64 characters. It appears in the dashboard, on the order's store.customer_id and in the customer's store_accounts |
Name and phone reach the customer with the buyer's email: when the session is created with it, or once the buyer gives it and starts paying. See how customers are made.
The order field
| Field | Type | Description |
|---|---|---|
id | string or null | Your order id, up to 64 characters. A later session with the same id joins this order instead of making another. See Store orders and retries |
number | string or null | The order number your buyers see, up to 32 characters, such as 1042 (a leading # is dropped). Used only with id |
url | string or null | The order's page in your admin, up to 1,000 characters. Used only with id, and only when it's an https:// address |
store | object or null | Which of your stores the order is from. Needs id: store without it is 400 invalid_order. See below |
items | array or null | What's being bought, 1–100 items. Leave it out for a single line. See below |
discount | string or null | Taken off the items' total. Default "0.00". It can be more than the items when store credit covers shipping or tax too, as long as the order still adds up to amount |
discount_code | string or null | The code the buyer used, up to 64 characters |
shipping | string or null | Shipping charged. Default "0.00" |
shipping_method | string or null | Up to 120 characters, such as Standard |
tax | string or null | Tax charged. Default "0.00" |
shipping_address | object or null | Where to ship the order. See below |
billing_address | object or null | The buyer's billing address |
fulfillment | string or null | none, unfulfilled or fulfilled. Default unfulfilled when there's a shipping address, otherwise none. See fulfilment |
Money in order is written like amount: a decimal string with at most two decimal places, never a number. Zero is allowed. Text fields are trimmed, and a blank one counts as left out.
Each item in items:
| Field | Type | Description |
|---|---|---|
name | string Required | Up to 200 characters |
quantity | integer Required | A whole number from 1 to 100,000 |
amount | string Required | The line's total for all its units, such as "64.00". Zero is allowed |
unit_amount | string or null | One unit's price, for display. It isn't checked against amount |
sku | string or null | Up to 64 characters |
variant | string or null | Which version, up to 120 characters, such as 120 capsules |
store tells your stores apart, so two of them can use the same order ids. With one store, leave it out.
| Field | Type | Description |
|---|---|---|
id | string Required | A stable id for the store, up to 64 characters. Keep it the same: it's how later sessions and list filters find the order |
platform | string | woocommerce, shopify or other (the default) |
name | string or null | The store's name, up to 120 characters |
url | string or null | The store's address, up to 1,000 characters. Kept only when it's http:// or https:// |
shipping_address and billing_address take the same fields, each optional:
| Field | Description |
|---|---|
name | Up to 120 characters |
line1, line2 | Up to 200 characters each |
city | Up to 120 characters |
region | A state, province or county, up to 120 characters |
postal_code | Up to 32 characters |
country | A two-letter code such as US, in any letter case. Saved in capitals |
An address with nothing in it counts as none. Any field that breaks these rules is 400 invalid_order, with field naming it, such as order.items[2].quantity. A customer that isn't an object, or a customer.email that differs from customer_email, is 400 invalid_customer.
The collect field
By default the hosted page asks the buyer for their email and nothing more: your server already knows who's buying. collect makes the page ask for more, for a checkout you send buyers to from a site that collects nothing itself. Each detail is off (the default), optional or required.
| Field | Type | Description |
|---|---|---|
name | string | off, optional or required |
phone | string | As above |
date_of_birth | string | As above. Self-declared: what the buyer types, not an ID check |
minimum_age | integer or null | 13 to 99, only with date_of_birth required: a younger buyer is told they can't buy this and the session doesn't start. Nothing is charged |
shipping_address | string | As above. A delivery address makes the order unfulfilled unless order.fulfillment says otherwise |
billing_address | string | As above |
marketing_opt_in | boolean | Shows an unticked "Email me news and offers" box. A ticked box sets the customer's accepts_marketing |
custom_fields | array | Up to 5 questions of your own, each { "key", "label", "required" }: key is 1–40 of a–z, 0–9 and _, starting with a letter and unique in the list; label is what the buyer reads, up to 50 characters; required defaults to false. Leave key out and it's made from the label (Player ID → player_id), as question_1, question_2 for a label with no Latin letters or digits, with _2 added when another question has it |
What customer and order already hold is filled in for the buyer, who can correct it, and a required detail that's already known isn't asked again. What the buyer gives lands on the order (shipping_address, billing_address, custom_fields) and the customer (name, phone, date_of_birth, accepts_marketing) in the same write that starts the payment, so payment.started and every later webhook carry it. A bad collect is 400 invalid_collect, with field naming the part, such as collect.custom_fields[1].key. Starting the session from your server with POST /v1/checkout_sessions/:id/start never asks: collect what you need in your own UI and send it in customer and order.
{
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"customer_email": "buyer@example.com",
"collect": {
"phone": "required",
"custom_fields": [{ "key": "player_id", "label": "Player ID", "required": true }]
}
}Totals
With items, the parts must add up to amount exactly, to the cent: the items' amounts, less discount, plus shipping and tax. For the order above:
| Part | Amount |
|---|---|
| Magnesium glycinate × 2 | 64.00 |
| Daily greens | 54.00 |
| Shaker bottle | 12.00 |
Discount, WELCOME10 | −13.00 |
| Shipping | +8.95 |
| Tax | +9.36 |
amount | 135.31 |
A session whose parts don't add up is 400 invalid_order_totals, and nothing is created; the error's message shows the sum. Line amounts come before the order's discount: when your store discounts single lines, send either the discounted line totals or the whole discount in discount, not both.
Without items, the order has one line named after your description, for whatever makes the parts add up: amount + discount − shipping − tax. If that comes to less than zero, the session is 400 invalid_order_totals.
Store orders and retries
A session with order.id pays for an order in your store. Railbed keeps one order for each order.id (within its store.id, in each mode):
- The first session creates the order. Later sessions with the same
order.idjoin it as more attempts at paying, for example after the buyer's card was declined or their session expired. - The latest session describes the order. Its items, totals and addresses replace the order's, and so does its customer when it has an email. The order's
numberand fulfilment stay, and its timeline in the dashboard notes when the total or items changed. - A paid order refuses a new session. When the order is
paid, orheldwith money you could accept as paid or that part-paid it, a new session gets409 order_paidand nothing is created. Check the order before asking the buyer to pay again. An order held only for money you can't accept (it went somewhere other than your wallet) takes new sessions, so the buyer can pay. - Earlier sessions stay open. Joining doesn't close them, and one that's still open can still be paid. Send the buyer only to the newest session's
url. A buyer who pays twice leaves two paid payments in the order'spayment_ids; refund one from your wallet. - Use a new
Idempotency-Keyfor each attempt. Repeating a request with the same key and body returns its original session, even after the order is paid: a replay is never refused withorder_paid. The key coversorderandcustomertoo, so the same key with a different order is409 idempotency_conflict.
Without order.id, every session creates a new order.
Retrieve a checkout session
GET /v1/checkout_sessions/:id
Returns a session of yours in the key's mode. Another account's session, or one in the other mode, is 404 not_found. Reading a session past its expires_at marks it expired.
curl https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN \
-H "Authorization: Bearer $RAILBED_SECRET_KEY"const session = await fetch(`https://pay.railbed.io/v1/checkout_sessions/${id}`, {
headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());session = requests.get(
f"https://pay.railbed.io/v1/checkout_sessions/{id}",
headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
timeout=15,
).json()<?php
$ch = curl_init(
'https://pay.railbed.io/v1/checkout_sessions/' . rawurlencode($id)
);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
],
]);
$session = json_decode(curl_exec($ch), true);The response is the checkout session object. To fulfil, read the payment instead: it adds the payment and settlement details.
Start a checkout session
POST /v1/checkout_sessions/:id/start
For your own checkout: starts the session as the buyer would on the hosted page, and returns the card providers that can take it, each with a handoff_url to open in the buyer's browser. Starting assigns the payment's deposit address and locks the fee and the order's value in USD.
| Field | Type | Description |
|---|---|---|
customer_email | string | The buyer's email. Optional when the session already has one; a new one replaces it |
country | string | The buyer's two-letter country code (US, DE), any letter case. Optional. Use the buyer's country, never your server's |
Send {} when the saved email is enough.
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 '{ "country": "US" }'const url = `https://pay.railbed.io/v1/checkout_sessions/${id}/start`;
const started = await fetch(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ country: 'US' }),
}).then((r) => r.json());started = requests.post(
f"https://pay.railbed.io/v1/checkout_sessions/{id}/start",
headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
json={"country": "US"},
timeout=15,
).json()<?php
$ch = curl_init(
'https://pay.railbed.io/v1/checkout_sessions/' . rawurlencode($id) . '/start'
);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['country' => 'US']),
]);
$started = json_decode(curl_exec($ch), true);{
"id": "pay_7AAiYH0Ykt11ED4hmfiN",
"object": "checkout_session",
"url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
"status": "open",
"livemode": false,
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"created": 1790380525,
"expires_at": 1790466925,
"started_at": 1790380611,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": null,
"country": "US",
"providers": [
{
"id": "stripe",
"name": "Stripe",
"note": "Card, Apple Pay or Google Pay",
"recommended": true,
"handoff_url": "https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=stripe"
},
{
"id": "coindisco",
"name": "Coindisco",
"note": "Card, through Coindisco",
"recommended": false,
"handoff_url": "https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=coindisco"
}
]
}The response is the session with two more fields:
| Field | Type | Description |
|---|---|---|
country | string or null | The country you sent, uppercased |
providers | array | The providers that can take this payment, best match first. Each has id, name, note (a short line on how the buyer pays), recommended (true for at most one: a provider the buyer already tried for this order comes last and is never recommended, so when they tried every provider, none is) and handoff_url |
Starting again is safe: started_at and the deposit address stay the same. A session made from a checkout that you start here gets every provider that can take it too, whatever the checkout says about providers: its hosted page and embedded checkout follow the checkout instead. Providers depend on the amount, currency and country, so fetch them when the buyer reaches your checkout, and open a handoff_url only from the buyer's click, in a new tab.
| Status | Code | When |
|---|---|---|
| 400 | invalid_email | The session has no email and none was sent |
| 400 | invalid_country | country isn't two letters |
| 404 | not_found | Not a session of yours in this mode |
| 409 | no_providers | No card provider can take this payment. reason says why, with the providers it is about: see Why no provider is offered. Nothing was started |
| 409 | already_paid, held, failed | The payment has finished |
| 409 | unavailable | The account can't take Live payments now: its payout wallet is missing or can't take payments, or the card network refused the account's setup. Nothing was started or charged; retrying gives the same answer |
| 409 | commerce_paused | The account has paused taking payments. Nothing was started |
| 409 | start_changed | The account's payment settings changed while the session was starting. Try again |
| 409 | invoice_changed | A payment toward an invoice that now has less left to pay than this payment asks for. The customer pays what's left from the invoice's page |
| 410 | expired, canceled | The session can no longer be paid |
| 410 | invoice_void | A payment toward an invoice that was voided |
| 429 | rate_limited | More than about 12 starts a minute |
| 502 | network_unavailable | The card network didn't answer. Retry in a minute |
| 503 | payments_paused | Live only: new payments are paused for a few minutes while a problem is fixed. Nothing was started; retry shortly |
Why no provider is offered
A no_providers error on this endpoint carries two more fields beside code and message, so your server can tell the cases apart without reading the message. The message is written for the buyer; show it or log it, and branch on reason.
{
"error": {
"code": "no_providers",
"message": "Mondial Games doesn’t offer a card provider that can take this payment. Contact Mondial Games for another way to pay.",
"reason": "providers_off",
"providers": ["coinbase"]
}
}reason | What it means | What to do |
|---|---|---|
providers_off | Card providers you turned off could have taken this buyer. providers holds their ids | Turn one back on under Integrations → Card providers |
below_minimum | The amount is under every card provider's minimum. minimum is the smallest card payment your buyers can make, as { amount, currency }, when it's known | Charge at least that much, or turn on a provider with a lower minimum |
country | No card provider serves the buyer's country. providers is empty | Offer the buyer another way to pay |
unavailable | The providers that could take it are down, paused or not working for now (providers) | Try again in a few minutes |
closing | The payment closes too soon for the one provider left (providers) | Create a new session |
providers is always an array, empty when the reason names no provider. New reasons can be added within v1: treat one you don't know as unavailable. To find out before a buyer is there, ask GET /v1/payment_methods with the amount and the buyer's country: when it offers nothing, its no_providers holds the same fields.
Cancel a checkout session
POST /v1/checkout_sessions/:id/cancel
Closes a session nobody has started paying, so its page and its handoff_url links can't be used any more. Use it when you replace a buyer's checkout with a new session, or the order is called off. No body is needed.
curl -X POST \
https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN/cancel \
-H "Authorization: Bearer $RAILBED_SECRET_KEY"const canceled = await fetch(`https://pay.railbed.io/v1/checkout_sessions/${id}/cancel`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());canceled = requests.post(
f"https://pay.railbed.io/v1/checkout_sessions/{id}/cancel",
headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
timeout=15,
).json(){
"id": "pay_7AAiYH0Ykt11ED4hmfiN",
"object": "checkout_session",
"url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
"status": "expired",
"livemode": false,
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"created": 1790380525,
"expires_at": 1790466925,
"started_at": null,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
"collect": null,
"canceled_at": 1790380711,
"checkout_id": null,
"plan_label": null
}The session's status becomes expired and canceled_at is set. Its order reads canceled, and endpoints that subscribe to it receive payment.canceled. Canceling again returns the same session, so a retry is safe.
You can cancel a session you created through the API, or a payment link, until the buyer goes to a card provider (a handoff_url, or a provider chosen on the hosted page) or is shown a crypto address. Being started doesn't stop a cancel. After that hand-off the buyer may already be paying, so the session stays open.
| Status | Code | When |
|---|---|---|
| 404 | not_found | Not a session of yours in this mode |
| 409 | not_cancelable | The buyer has gone to a card provider or been shown a crypto address; the session is paid, held, failed or expired; or it's a buyer's own attempt on a checkout page or a Shopify checkout. The message says which |
| 403 | merchant_read_only | The account is suspended or archived. An account that has paused taking payments can still cancel |