Payments
A payment is what a checkout session became. Read it to fulfil orders, list payments to reconcile, and simulate outcomes in Test mode.
On this page
The payment object
A payment has every field of its checkout session, with object set to "payment". Its checkout_id and plan_label name the checkout and plan for every payment made through a checkout: a buyer's own on its page, and a session your server made from it. Plus:
| Field | Type | Description |
|---|---|---|
paid_at | integer or null | When it became paid, in Unix seconds |
provider | string or null | The provider the buyer chose, such as stripe or paypal. Null when the buyer paid in crypto |
method | string | How the money that settled (or is held) arrived: card, or crypto when the buyer sent stablecoins from their own wallet (crypto payments) |
hold_reason | string or null | Why it's held, in plain words. Null otherwise |
hold_acceptable | boolean | For a held payment: whether you can accept it as paid in the dashboard |
canceled_at | integer or null | When it was canceled: a session or payment link you canceled, or an unstarted payment closed when its invoice was voided or changed. A canceled payment's status is expired |
settlement | object | What arrived and where it went. See below |
collect | object or null | What the hosted page asked the buyer for besides their email, as on the session; null for nothing more |
invoice_id | string or null | The invoice it pays toward, in_…, or null. Every payment link is an invoice too, and each part payment of an invoice is its own payment |
tip | string | The part of amount the buyer added as a tip on an invoice, "0.00" without one. Tips never count toward the invoice |
The settlement object:
| Field | Type | Description |
|---|---|---|
network | string or null | Crypto payments: the network the money arrived on, such as base or polygon. Null for card, whose coin names the network |
coin | string or null | What was delivered, usually polygon_usdc (polygon_usdt is also possible). Card payments whose provider is applepay or googlepay (card payments on other networks) arrive on Ethereum, as erc20_usdc (or erc20_usdt), rampnow ones as ETH there (eth), venmo ones as PayPal USD there (erc20_pyusd), and cashapp ones on BNB Chain, as bep20_usdt (or bep20_usdc). Crypto payments name their network, such as base_usdc |
value_coin | string or null | How much arrived at the payment's deposit address, before fees |
merchant_received_usd | string or null | The same amount in US dollars (six decimal places), whatever the coin: a dollar coin such as USDC or USDT counts one dollar each, any other at the price it was valued at when the payment was checked. Null until merchant_received is reported. This is the figure the dashboard adds up as Received |
merchant_received | string or null | How much was forwarded to your wallet, in the coin (six decimal places, or eight for Bitcoin, Litecoin, Bitcoin Cash, Zcash and Monero), once it's reported. Can be null for a while after paid and fill in later. A held payment has it when its payout reached your wallet, and keeps it if you accept it as paid; it stays null when the payout didn't reach you |
txid_in | string or null | The transaction that delivered the money: for card, on Polygon, or on Ethereum when coin starts with erc20_; on network for crypto |
txid_out | string or null | The transaction that forwarded it to your wallet |
payout_wallet | string or null | The wallet it went to, fixed when the buyer started. The examples on this page show a placeholder (0x3333…); yours shows your own wallet |
amount and currency are always the price you set; value_coin and merchant_received are what actually moved, and merchant_received_usd is what you earned in dollars. Use a Polygon block explorer for card payments (an Ethereum one when coin starts with erc20_), or the explorer for settlement.network for crypto payments, to inspect the transactions.
Retrieve a payment
GET /v1/payments/:id
Returns the current state of a payment of yours in the key's mode. This is the authority for fulfilment: when it says paid, the money arrived and passed Railbed's settlement checks. What to deliver is on its order, from order_id.
curl https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN \
-H "Authorization: Bearer $RAILBED_SECRET_KEY"const payment = await fetch(`https://pay.railbed.io/v1/payments/${id}`, {
headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());payment = requests.get(
f"https://pay.railbed.io/v1/payments/{id}",
headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
timeout=15,
).json()<?php
$ch = curl_init('https://pay.railbed.io/v1/payments/' . rawurlencode($id));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
],
]);
$payment = json_decode(curl_exec($ch), true);{
"id": "pay_7AAiYH0Ykt11ED4hmfiN",
"object": "payment",
"url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
"status": "paid",
"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,
"paid_at": 1790381342,
"provider": "stripe",
"hold_reason": null,
"hold_acceptable": false,
"method": "card",
"settlement": {
"network": null,
"coin": "polygon_usdc",
"value_coin": "47.53",
"merchant_received": "44.915850",
"merchant_received_usd": "44.915850",
"txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
"txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
"payout_wallet": "0x3333333333333333333333333333333333333333"
},
"invoice_id": null,
"tip": "0.00"
}A held payment includes why it didn't pass a check, and whether you can accept it:
{
"id": "pay_Kx81mQv2PzR0dT7eWcYa",
"object": "payment",
"url": "https://pay.railbed.io/p/pay_Kx81mQv2PzR0dT7eWcYa",
"status": "held",
"livemode": false,
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"created": 1790380465,
"expires_at": 1790466865,
"started_at": 1790380611,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_Rx2Np5VqT9sW4mLb7ZaC",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": null,
"paid_at": null,
"provider": "stripe",
"hold_reason": "The provider sent 24.50 USDC, below 85% of the order’s 49.00 USD value.",
"hold_acceptable": true,
"method": "card",
"settlement": {
"network": null,
"coin": "polygon_usdc",
"value_coin": "24.50",
"merchant_received": "23.152500",
"merchant_received_usd": "23.152500",
"txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
"txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
"payout_wallet": "0x3333333333333333333333333333333333333333"
},
"invoice_id": null,
"tip": "0.00"
}A payment sent from the buyer's own crypto wallet names the network and has no card provider:
{
"id": "pay_Sd70mP9ArQ6cW2zXn8eV",
"object": "payment",
"url": "https://pay.railbed.io/p/pay_Sd70mP9ArQ6cW2zXn8eV",
"status": "paid",
"livemode": false,
"amount": "100.00",
"currency": "USD",
"description": "Annual Membership",
"reference": "order_1043",
"customer_email": "buyer@example.com",
"created": 1790380525,
"expires_at": 1790466925,
"started_at": 1790380611,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_C9vMx2QpR5tN8wKa3sLb",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": null,
"paid_at": 1790381342,
"provider": null,
"hold_reason": null,
"hold_acceptable": false,
"method": "crypto",
"settlement": {
"network": "base",
"coin": "base_usdc",
"value_coin": "100.00",
"merchant_received": "98.000000",
"merchant_received_usd": "98.000000",
"txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
"txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
"payout_wallet": "0x3333333333333333333333333333333333333333"
},
"invoice_id": null,
"tip": "0.00"
}Reading a payment past its expires_at marks an unpaid one expired.
List payments
GET /v1/payments
Returns your payments in the key's mode, newest first. Use it to reconcile, not to find new payments quickly: it lists by creation time, so recheck unfinished payments you saved by id.
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1–100. Default 20 |
starting_after | string | A payment id from the previous page's next_cursor |
status | string | open, pending, paid, held, failed or expired. Overdue open or pending payments count as expired |
reference | string | Exact match on the stored reference. It's normalized as on create (text normalization), so up to 120 Unicode code points |
invoice_id | string | Only payments toward this invoice, in_… |
created_gte | integer | Created on or after this Unix timestamp in seconds |
created_lte | integer | Created on or before this Unix timestamp in seconds, including the whole ending second |
Keep the same filters when following next_cursor. Invalid statuses, invalid dates, or a start later than the end return 400. Dates filter creation time; recheck saved unresolved payment ids separately to catch later settlement.
curl "https://pay.railbed.io/v1/payments?limit=50&status=paid&reference=order_1042" \
-H "Authorization: Bearer $RAILBED_SECRET_KEY"// Every payment, page by page
let cursor = null;
do {
const url = new URL('https://pay.railbed.io/v1/payments');
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('starting_after', cursor);
const page = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },
}).then((r) => r.json());
for (const payment of page.data) reconcile(payment);
cursor = page.next_cursor;
} while (cursor);cursor = None
while True:
params = {"limit": 100, **({"starting_after": cursor} if cursor else {})}
page = requests.get(
"https://pay.railbed.io/v1/payments",
headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
params=params,
timeout=15,
).json()
for payment in page["data"]:
reconcile(payment)
cursor = page["next_cursor"]
if not cursor:
break<?php
$cursor = null;
do {
$query = http_build_query(array_filter([
'limit' => 100,
'starting_after' => $cursor,
]));
$ch = curl_init('https://pay.railbed.io/v1/payments?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),
],
]);
$page = json_decode(curl_exec($ch), true);
foreach ($page['data'] as $payment) reconcile($payment);
$cursor = $page['next_cursor'];
} while ($cursor);{
"data": [
{
"id": "pay_7AAiYH0Ykt11ED4hmfiN",
"object": "payment",
"url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
"status": "paid",
"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,
"paid_at": 1790381342,
"provider": "stripe",
"hold_reason": null,
"hold_acceptable": false,
"method": "card",
"settlement": {
"network": null,
"coin": "polygon_usdc",
"value_coin": "47.53",
"merchant_received": "44.915850",
"merchant_received_usd": "44.915850",
"txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
"txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
"payout_wallet": "0x3333333333333333333333333333333333333333"
},
"invoice_id": null,
"tip": "0.00"
},
{
"id": "pay_Kx81mQv2PzR0dT7eWcYa",
"object": "payment",
"url": "https://pay.railbed.io/p/pay_Kx81mQv2PzR0dT7eWcYa",
"status": "held",
"livemode": false,
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": "buyer@example.com",
"created": 1790380465,
"expires_at": 1790466865,
"started_at": 1790380611,
"metadata": {
"user_id": "player_1042"
},
"order_id": "ord_Rx2Np5VqT9sW4mLb7ZaC",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": null,
"paid_at": null,
"provider": "stripe",
"hold_reason": "The provider sent 24.50 USDC, below 85% of the order’s 49.00 USD value.",
"hold_acceptable": true,
"method": "card",
"settlement": {
"network": null,
"coin": "polygon_usdc",
"value_coin": "24.50",
"merchant_received": "23.152500",
"merchant_received_usd": "23.152500",
"txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
"txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
"payout_wallet": "0x3333333333333333333333333333333333333333"
},
"invoice_id": null,
"tip": "0.00"
}
],
"has_more": true,
"next_cursor": "pay_Kx81mQv2PzR0dT7eWcYa"
}Each item is a full payment object, including method and settlement.network. An invalid limit is 400 invalid_limit; a cursor that isn't one of your payments in this mode is 400 invalid_cursor.
Simulate a payment
POST /v1/payments/:id/simulate
Test mode only. Simulates an outcome for a started test payment. Simulated money goes through the same settlement checks and webhooks as a live payment. A card decline keeps the payment open for retry. Your key works on any of your Test payments; on the hosted pages, only your team's browsers can simulate (Testing).
| Field | Type | Description |
|---|---|---|
outcome | string Required | paid (about 97% of the value arrives), underpaid (half arrives, so it's held), declined (stays open for another provider, no failed webhook), or failed (terminal Test failure with a payment.failed webhook) |
curl -X POST \
https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN/simulate \
-H "Authorization: Bearer $RAILBED_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "outcome": "paid" }'const payment = await fetch(`https://pay.railbed.io/v1/payments/${id}/simulate`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ outcome: 'paid' }),
}).then((r) => r.json());payment = requests.post(
f"https://pay.railbed.io/v1/payments/{id}/simulate",
headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
json={"outcome": "paid"},
timeout=15,
).json()<?php
$ch = curl_init(
'https://pay.railbed.io/v1/payments/' . rawurlencode($id) . '/simulate'
);
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(['outcome' => 'paid']),
]);
$payment = json_decode(curl_exec($ch), true);The response is the payment after the outcome. Simulated money arrives as polygon_usdc, or as erc20_usdc when the provider is applepay or googlepay. A declined outcome leaves it open for another provider on the same session. Simulating a finished payment returns it unchanged.
| Status | Code | When |
|---|---|---|
| 400 | invalid_outcome | outcome is missing or not one of the four supported values |
| 403 | live_payment | The payment is a Live payment |
| 409 | not_started | Start the session first, with Start a checkout session |