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

FieldTypeDescription
idstringThe session's id, pay_…. The same id identifies its payment
objectstring"checkout_session"
urlstringThe hosted checkout page for this session. Send the buyer here, or open it over your page with Railbed.open (pop-up)
statusstringopen, pending, paid, held, failed or expired. See statuses
livemodebooleanfalse for Test mode, true for Live mode
amountstringThe price, as set at creation: "49.00"
currencystringUSD, EUR, GBP, CAD, AUD, INR or SEK
descriptionstringWhat the buyer is paying for, shown on the checkout
referencestring or nullYour own id for the order
customer_emailstring or nullThe buyer's email, lowercased
createdintegerWhen it was created, in Unix seconds
expires_atintegerWhen it stops accepting new payments: 24 hours after creation
started_atinteger or nullWhen the buyer (or your server) started it. Set once
metadataobject or nullYour normalized key-value pairs, returned on the session, payment and webhook
order_idstring or nullThe order this session is a payment attempt for, ord_…. Every session has one (null only on records from before orders existed)
collectobject or nullWhat the hosted page asks the buyer for besides their email, or null for nothing more. See The collect field
canceled_atinteger or nullWhen you canceled it, in Unix seconds. null until then
checkout_idstring or nullThe checkout the session was made from, chk_…. null for a session you described yourself. See From a saved checkout
plan_labelstring or nullThe pricing-table plan, as buyers see it: "Pro · Yearly", or "Pro" on a table without a switch. null otherwise
warningsarrayOn 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.

FieldTypeDescription
amountstring RequiredLeave 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
currencystring RequiredLeave it out when you send checkout. USD, EUR, GBP, CAD, AUD, INR or SEK, in any letter case
descriptionstring RequiredLeave it out when you send checkout. What the buyer is paying for, up to 120 Unicode code points after text normalization
customer_emailstring or nullThe buyer's email. Optional here, but needed before the session can start
referencestring or nullYour 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
metadataobject or nullUp 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_urlstring or nullWhere the checkout sends the buyer once the payment is confirmed. {PAYMENT_ID} and {REFERENCE} are filled in. Up to 1,000 characters
cancel_urlstring or nullWhere the checkout's "Cancel and return to …" and "Back to …" links lead (they name your business). Up to 1,000 characters
customerobject or nullWho is buying: name, phone and your customer id. See Orders and customers
orderobject or nullWhat they're buying: items, discount, shipping, tax, addresses and your order id. See Orders and customers
collectobject or nullWhat 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
checkoutstring or nullMake the session from one of your checkouts instead of describing it: its id (chk_…) or slug. See From a saved checkout
planstring or nullWith checkout, for a pricing table: the id of the plan the buyer chose
optioninteger or nullWith 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"
  }'
Response
{
  "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
}
201 Created

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.

FieldTypeDescription
checkoutstring RequiredThe checkout's id (chk_…) or slug, in the same mode as your key. List checkouts returns both
planstring or nullThe id of the plan the buyer chose (plans[].id on the checkout). Required for a pricing table, refused for a page or widget
optioninteger or null0 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:

  • amount and currency: 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.

Node.js: a session for a signed-in user
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"
Response
{
  "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"
}
201 Created
StatusCodeWhen
400field_not_allowedamount, currency, description, collect or order was sent with checkout. field names it
400invalid_checkoutNo checkout with that id or slug in this account and mode
400invalid_planplan 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
403integration_disabledCheckouts are turned off for the account
409checkout_offThe checkout is turned off. Turn it on in the dashboard first
409checkout_deletedThe 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 answers 400 invalid_amount with 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 and warnings says the minimums couldn't be checked; if the only providers that take it are briefly unavailable, it is accepted and warnings names 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 in warnings. A smaller amount answers 400 invalid_amount as it would without crypto.
  • warnings is on the 201 response (and an idempotent replay) only when there is something to say. A replay with the same Idempotency-Key always answers its session, with today's warnings, even if the amount would be refused as a new session. A session made from a saved checkout carries warnings on its 201 only: its replay answers the session as it was made, even after the checkout has changed or been deleted. Each entry has code, message and minimum (the floor as { amount, currency }, or null). limited_coverage means 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.
JSON
{
  "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, description and reference
  • the buyer's email, from customer_email or customer.email
  • success_url and cancel_url
  • metadata: key order doesn't matter, but spaces inside values do
  • every field of order and customer, only when the request sent either
  • collect, only when the request sent it
  • for a session from a saved checkout: checkout, plan and option as 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"
  }'
Response
{
  "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
}
201 Created

Retrieve the order with order_id to see what was saved.

The customer field

FieldTypeDescription
emailstring or nullThe buyer's email, with the same rules as customer_email. Send either one; when you send both, they must be the same address
namestring or nullThe buyer's name, up to 120 characters. Without it, the name on the shipping (or billing) address is used
phonestring or nullUp to 40 characters, in any format
date_of_birthstring or nullA past date as YYYY-MM-DD. Kept on the customer
accepts_marketingboolean or nulltrue 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
idstring or nullThe 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

FieldTypeDescription
idstring or nullYour 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
numberstring or nullThe order number your buyers see, up to 32 characters, such as 1042 (a leading # is dropped). Used only with id
urlstring or nullThe order's page in your admin, up to 1,000 characters. Used only with id, and only when it's an https:// address
storeobject or nullWhich of your stores the order is from. Needs id: store without it is 400 invalid_order. See below
itemsarray or nullWhat's being bought, 1–100 items. Leave it out for a single line. See below
discountstring or nullTaken 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_codestring or nullThe code the buyer used, up to 64 characters
shippingstring or nullShipping charged. Default "0.00"
shipping_methodstring or nullUp to 120 characters, such as Standard
taxstring or nullTax charged. Default "0.00"
shipping_addressobject or nullWhere to ship the order. See below
billing_addressobject or nullThe buyer's billing address
fulfillmentstring or nullnone, 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:

FieldTypeDescription
namestring RequiredUp to 200 characters
quantityinteger RequiredA whole number from 1 to 100,000
amountstring RequiredThe line's total for all its units, such as "64.00". Zero is allowed
unit_amountstring or nullOne unit's price, for display. It isn't checked against amount
skustring or nullUp to 64 characters
variantstring or nullWhich 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.

FieldTypeDescription
idstring RequiredA stable id for the store, up to 64 characters. Keep it the same: it's how later sessions and list filters find the order
platformstringwoocommerce, shopify or other (the default)
namestring or nullThe store's name, up to 120 characters
urlstring or nullThe 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:

FieldDescription
nameUp to 120 characters
line1, line2Up to 200 characters each
cityUp to 120 characters
regionA state, province or county, up to 120 characters
postal_codeUp to 32 characters
countryA 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.

FieldTypeDescription
namestringoff, optional or required
phonestringAs above
date_of_birthstringAs above. Self-declared: what the buyer types, not an ID check
minimum_ageinteger or null13 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_addressstringAs above. A delivery address makes the order unfulfilled unless order.fulfillment says otherwise
billing_addressstringAs above
marketing_opt_inbooleanShows an unticked "Email me news and offers" box. A ticked box sets the customer's accepts_marketing
custom_fieldsarrayUp 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.

A session that asks for a phone number and a player ID
{
  "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:

PartAmount
Magnesium glycinate × 264.00
Daily greens54.00
Shaker bottle12.00
Discount, WELCOME10−13.00
Shipping+8.95
Tax+9.36
amount135.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.id join 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 number and 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, or held with money you could accept as paid or that part-paid it, a new session gets 409 order_paid and 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's payment_ids; refund one from your wallet.
  • Use a new Idempotency-Key for 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 with order_paid. The key covers order and customer too, so the same key with a different order is 409 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"

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.

FieldTypeDescription
customer_emailstringThe buyer's email. Optional when the session already has one; a new one replaces it
countrystringThe 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" }'
Response (two providers shown)
{
  "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"
    }
  ]
}
200 OK

The response is the session with two more fields:

FieldTypeDescription
countrystring or nullThe country you sent, uppercased
providersarrayThe 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.

StatusCodeWhen
400invalid_emailThe session has no email and none was sent
400invalid_countrycountry isn't two letters
404not_foundNot a session of yours in this mode
409no_providersNo card provider can take this payment. reason says why, with the providers it is about: see Why no provider is offered. Nothing was started
409already_paid, held, failedThe payment has finished
409unavailableThe 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
409commerce_pausedThe account has paused taking payments. Nothing was started
409start_changedThe account's payment settings changed while the session was starting. Try again
409invoice_changedA 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
410expired, canceledThe session can no longer be paid
410invoice_voidA payment toward an invoice that was voided
429rate_limitedMore than about 12 starts a minute
502network_unavailableThe card network didn't answer. Retry in a minute
503payments_pausedLive 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.

Coinbase is turned off, and it's the one provider that could take this buyer
{
  "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"]
  }
}
409 Conflict
reasonWhat it meansWhat to do
providers_offCard providers you turned off could have taken this buyer. providers holds their idsTurn one back on under Integrations → Card providers
below_minimumThe amount is under every card provider's minimum. minimum is the smallest card payment your buyers can make, as { amount, currency }, when it's knownCharge at least that much, or turn on a provider with a lower minimum
countryNo card provider serves the buyer's country. providers is emptyOffer the buyer another way to pay
unavailableThe providers that could take it are down, paused or not working for now (providers)Try again in a few minutes
closingThe 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"
Response
{
  "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
}
200 OK

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.

StatusCodeWhen
404not_foundNot a session of yours in this mode
409not_cancelableThe 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
403merchant_read_onlyThe account is suspended or archived. An account that has paused taking payments can still cancel

Updated · This page as Markdown