Checkout Sessions

A checkout session is an open charge. Hosted: redirect to pay.noderails.com. Headless: noderails.headlessCheckout on the same session.

💡

Hosted payment page

Checkout sessions power the NodeRails hosted payment UI. Your customer never leaves a NodeRails-hosted page, reducing PCI-equivalent complexity for crypto payments.

Create a checkout session

POST/checkout-sessions

Creates a new checkout session. Returns a session object with line items.

Request body

Parameter	Type	Required	Description
`appId`	`string`	Yes	Your app UUID
`successUrl`	`string`	Yes	URL to redirect on successful payment
`cancelUrl`	`string`	Yes	URL to redirect on cancellation
`items`	`CheckoutItem[]`	Yes	Line items (min 1)
`customerAccountId`	`string`	No	Existing customer UUID
`mode`	`"PAYMENT" \| "SUBSCRIPTION"`	No	Checkout mode (default: PAYMENT)
`expiresInMinutes`	`number`	No	Auto-expire in 1-1440 minutes
`metadata`	`object`	No	Arbitrary key-value metadata

CheckoutItem

Field	Type	Required	Description
`name`	`string`	Yes	Item name (1-255 chars)
`amount`	`string`	No	Price in fiat (decimal string)
`currency`	`string`	No	Currency code (max 10 chars)
`quantity`	`number`	No	Item quantity (positive integer)
`description`	`string`	No	Item description (max 500)
`productPlanId`	`string`	No	Link to a product plan
`productPlanPriceId`	`string`	No	Specific price option
`isPriceOption`	`boolean`	No	Whether to use price option

SDK exampletypescript

const session = await noderails.checkoutSessions.create({
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  items: [
    {
      name: 'Pro Plan',
      amount: '49.99',
      currency: 'USD',
      quantity: 1,
    },
  ],
  metadata: { orderId: 'order_123' },
});

// Redirect your customer to the hosted payment page:
// https://pay.noderails.com/checkout/{session.id}
console.log(session.id);     // UUID
console.log(session.status); // "OPEN"

cURLbash

curl -X POST https://api.noderails.com/checkout-sessions \
  -H "x-api-key: nr_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your-app-id",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "items": [{
      "name": "Pro Plan",
      "amount": "49.99",
      "currency": "USD",
      "quantity": 1
    }]
  }'

List checkout sessions

GET/checkout-sessions

Query parameters

Parameter	Type	Description
`appId`	`string`	Filter by app UUID
`status`	`"OPEN" \| "COMPLETE" \| "EXPIRED"`	Filter by status
`page`	`number`	Page number (default: 1)
`pageSize`	`number`	Items per page (1-100)

SDK exampletypescript

const result = await noderails.checkoutSessions.list({
  status: 'OPEN',
  page: 1,
  pageSize: 25,
});

console.log(result.data);       // CheckoutSession[]
console.log(result.pagination); // { total, page, pageSize, totalPages }

Retrieve a checkout session

GET/checkout-sessions/:id

SDK exampletypescript

const session = await noderails.checkoutSessions.retrieve('cs_abc123');
console.log(session.status); // "OPEN" | "COMPLETE" | "EXPIRED"

Expire a checkout session

POST/checkout-sessions/:id/expire

Manually expires an open checkout session, preventing any further payments.

SDK exampletypescript

const expired = await noderails.checkoutSessions.expire('cs_abc123');
console.log(expired.status); // "EXPIRED"

Headless payment options

GET/checkout-sessions/:id/payment-options

Secret key. Session must be OPEN. Returns accepted chains and tokens with a spot quote per token. Exact signed amount is on prepare. See Headless Checkout.

SDK exampletypescript

const options = await noderails.headlessCheckout.paymentOptions(session.id);

Headless prepare

POST/checkout-sessions/:id/prepare

Parameter	Type	Required	Description
`tokenKey`	`string`	Yes	Accepted token key
`chainId`	`number`	Yes	Accepted chain id
`walletAddress`	`string`	Yes	Customer wallet

SDK exampletypescript

const prepared = await noderails.headlessCheckout.prepare(session.id, {
  tokenKey: 'USDC-8453',
  chainId: 8453,
  walletAddress: '0x...',
});

Headless confirm

POST/checkout-sessions/:id/confirm

Secret key. Calls the same authorize path as hosted checkout. ERC-20 returns CAPTURING. Native, Solana, and Sui one-time pays return AWAITING_USER_TX plus captureData.

Parameter	Type	Required	Description
`walletAddress`	`string`	Yes	Customer wallet
`chainId`	`number`	Yes	Chain used on prepare
`tokenKey`	`string`	Yes	Token used on prepare
`customerEmail`	`string`	Yes	Buyer email
`cryptoAmount`	`string`	Yes	Charge amount from prepare (raw units)
`exchangeRate`	`string`	Yes	Rate from prepare
`quoteId`	`string`	No	Required when conversion is on
`permitSignature`	`object`	No	amount, deadline, v, r, s after permit
`approvalTxHash`	`string`	No	Approve tx hash
`customerName`	`string`	No	Required when billing details are required
`billingAddress`	`string`	No	Required when billing details are required
`billingCity`	`string`	No	Required when billing details are required
`billingState`	`string`	No	Required when billing details are required
`billingCountry`	`string`	No	Required when billing details are required
`billingPostalCode`	`string`	No	Required when billing details are required

SDK exampletypescript

const result = await noderails.headlessCheckout.confirm(session.id, {
  walletAddress: '0x...',
  chainId: 8453,
  tokenKey: 'USDC-8453',
  customerEmail: 'buyer@example.com',
  cryptoAmount: prepared.cryptoAmount,
  exchangeRate: prepared.exchangeRate,
  quoteId: prepared.quoteId ?? undefined,
  permitSignature,
});

Headless submit user tx

POST/checkout-sessions/:id/submit-user-tx

Secret key. Report the capture hash after confirm returns AWAITING_USER_TX.

Parameter	Type	Required	Description
`intentId`	`string`	Yes	Payment intent from confirm
`txHash`	`string`	No*	Capture hash (EVM, Solana, or Sui)
`suiSponsored`	`object`	No*	Sponsored Sui payload. *Send txHash or suiSponsored

SDK exampletypescript

await noderails.headlessCheckout.submitUserTx(session.id, {
  intentId: result.intentId,
  txHash: '0x...',
});

Create from payment link

POST/checkout-sessions/from-link

Creates a checkout session from a payment link slug. This is a public endpoint, no authentication required.

Parameter	Type	Required	Description
`slug`	`string`	Yes	Payment link slug (1-100 chars)

Create from invoice

POST/checkout-sessions/from-invoice

Creates a checkout session from an invoice ID. This is a public endpoint, no authentication required.

Parameter	Type	Required	Description
`invoiceId`	`string`	Yes	Invoice UUID

Response object

All responses are wrapped in { "success": true, "data": ... }. List endpoints add pagination with total, page, pageSize, and totalPages.

CheckoutSession object (create / expire)json

{
  "success": true,
  "data": {
    "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
    "appId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customerAccountId": null,
    "paymentIntentId": null,
    "mode": "PAYMENT",
    "status": "OPEN",
    "sourceType": "CHECKOUT",
    "sourceId": null,
    "amount": "49.99",
    "currency": "USD",
    "subtotal": "49.99",
    "taxAmount": "0",
    "taxDescription": null,
    "allowedChains": "ALL",
    "allowedTokens": "ALL",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "selectedPriceId": null,
    "requireBillingDetails": false,
    "metadata": { "orderId": "order_123" },
    "expiresAt": "2025-01-16T10:30:00.000Z",
    "completedAt": null,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z",
    "items": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "checkoutSessionId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
        "productPlanId": null,
        "productPlanPriceId": null,
        "name": "Pro Plan",
        "description": null,
        "amount": "49.99",
        "currency": "USD",
        "quantity": 1,
        "isPriceOption": false,
        "createdAt": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

CheckoutSession fields

idstringUnique checkout session UUID

appIdstringApp this session belongs to

customerAccountIdstring | nullLinked customer UUID, if any

paymentIntentIdstring | nullAssociated payment intent UUID once payment begins

modestringPAYMENT or SUBSCRIPTION

statusstringOPEN, COMPLETE, or EXPIRED

sourceTypestringOrigin type: CHECKOUT, PAYMENT_LINK, INVOICE, or SUBSCRIPTION

sourceIdstring | nullID of the originating resource (payment link, invoice, etc.)

amountstringTotal payment amount as a decimal string

currencystringFiat currency code (e.g. USD)

subtotalstringAmount before tax

taxAmountstringCalculated tax amount

taxDescriptionstring | nullTax label shown to customer (e.g. 'VAT 20%')

allowedChains'ALL' | number[]Permitted chain IDs (EVM + Solana e.g. 103)

allowedTokens'ALL' | string[]Permitted token identifiers

successUrlstringRedirect URL after successful payment

cancelUrlstringRedirect URL on cancellation

selectedPriceIdstring | nullSelected product plan price UUID

requireBillingDetailsbooleanWhether billing details are required at checkout

metadataobjectArbitrary key-value pairs

expiresAtstringISO 8601 expiration timestamp

completedAtstring | nullISO 8601 timestamp when session completed

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last-update timestamp

itemsCheckoutSessionItem[]Line items in this session

CheckoutSessionItem fields

idstringItem UUID

checkoutSessionIdstringParent checkout session UUID

productPlanIdstring | nullLinked product plan UUID

productPlanPriceIdstring | nullLinked price UUID

namestringItem display name

descriptionstring | nullItem description

amountstringPrice per unit as decimal string

currencystringCurrency code

quantitynumberItem quantity

isPriceOptionbooleanWhether this item uses a price option

createdAtstringISO 8601 creation timestamp

💡

Retrieve response

The retrieve endpoint returns additional nested objects: app (full app record), paymentIntent (full payment intent), and each item includes productPlan and productPlanPrice when linked.