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:

FieldTypeDescription
paid_atinteger or nullWhen it became paid, in Unix seconds
providerstring or nullThe provider the buyer chose, such as stripe or paypal. Null when the buyer paid in crypto
methodstringHow the money that settled (or is held) arrived: card, or crypto when the buyer sent stablecoins from their own wallet (crypto payments)
hold_reasonstring or nullWhy it's held, in plain words. Null otherwise
hold_acceptablebooleanFor a held payment: whether you can accept it as paid in the dashboard
canceled_atinteger or nullWhen 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
settlementobjectWhat arrived and where it went. See below
collectobject or nullWhat the hosted page asked the buyer for besides their email, as on the session; null for nothing more
invoice_idstring or nullThe 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
tipstringThe 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:

FieldTypeDescription
networkstring or nullCrypto payments: the network the money arrived on, such as base or polygon. Null for card, whose coin names the network
coinstring or nullWhat 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_coinstring or nullHow much arrived at the payment's deposit address, before fees
merchant_received_usdstring or nullThe 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_receivedstring or nullHow 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_instring or nullThe transaction that delivered the money: for card, on Polygon, or on Ethereum when coin starts with erc20_; on network for crypto
txid_outstring or nullThe transaction that forwarded it to your wallet
payout_walletstring or nullThe 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"
Response
{
  "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"
}
200 OK

A held payment includes why it didn't pass a check, and whether you can accept it:

A held payment
{
  "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"
}
200 OK

A payment sent from the buyer's own crypto wallet names the network and has no card provider:

A crypto payment
{
  "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"
}
200 OK

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.

ParameterTypeDescription
limitinteger1–100. Default 20
starting_afterstringA payment id from the previous page's next_cursor
statusstringopen, pending, paid, held, failed or expired. Overdue open or pending payments count as expired
referencestringExact match on the stored reference. It's normalized as on create (text normalization), so up to 120 Unicode code points
invoice_idstringOnly payments toward this invoice, in_…
created_gteintegerCreated on or after this Unix timestamp in seconds
created_lteintegerCreated 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"
Response
{
  "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"
}
200 OK

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).

FieldTypeDescription
outcomestring Requiredpaid (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" }'

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.

StatusCodeWhen
400invalid_outcomeoutcome is missing or not one of the four supported values
403live_paymentThe payment is a Live payment
409not_startedStart the session first, with Start a checkout session

Updated · This page as Markdown