RapidCents

Hosted checkout

Same checkout/create as embedded, with ui_mode: hosted. After session creation, redirect the browser to checkout_url. The shopper pays on RapidCents, then is sent to your success_url or cancel_url.

When to use

You prefer redirect-out / redirect-back over an iframe.
Minimal client JavaScript.

Embedded · Overview · Subscriptions

Staging/production hosts: Overview → APIs.

Required API

POST {API origin}/api/{business_id}/checkout/create

OAuth

All checkout API requests require:

Authorization: Bearer <access_token> — from OAuth (see Overview → OAuth).
Origin — HTTPS origin of your app (for example https://shop.example.com). It must match the origin registered for your API client in RapidCents.
Content-Type: application/json and Accept: application/json unless the API specifies otherwise.

Never expose tokens in the browser

Create checkout sessions on your server only. Do not send the access token to client-side JavaScript.

HTTP headers

Required on every checkout/create call from your backend.

Authorization string

Access token from POST …/oauth/token. Server only.

Bearer <token> · e.g. Bearer eyJhbG…

Origin string

Your app’s public HTTPS origin; must match the OAuth client registration.

HTTPS URL · e.g. https://shop.example.com

Content-Type string

JSON request body.

application/json

Accept string

JSON response.

application/json

Required & common parameters

Same JSON as embedded; set ui_mode to hosted.

Path parameters

In the URL path (not the JSON body). Pattern: POST {API origin}/api/{business_id}/checkout/create

business_id string (UUID)

Business id for this API host/environment.

UUID string · e.g. "550e8400-e29b-41d4-a716-446655440000"

Payment session (`mode: payment`)

One-time charge: ui_mode, amounts, return URLs, optional customer fields. Same shape for embedded and hosted.

ui_mode string

Iframe on your site vs full-page redirect. This guide: embedded.

embedded, hosted · e.g. "embedded"

mode string

Use payment for one-time checkout. For subscription, see the Subscription checkout guide.

payment, subscription · e.g. "payment"

amount_total number

Total in major units; align with line_items when present.

≥ 0; typically 2 decimals · e.g. 49.99

currency string

ISO 4217; must be enabled for your merchant account.

e.g. CAD, USD

amount_subtotal number

Pre-tax/discount subtotal when itemizing (often sum of line totals).

≥ 0; 2 decimals · e.g. 45.00

line_items array

Optional cart lines; omit for a single lump sum.

Array (see line items section) · e.g. [{ "name": "…", … }]

success_url string (URL)

HTTPS URL after success; add your own id in the query if needed. Confirm payment server-side before fulfillment.

Absolute https:// · e.g. "https://app.example.com/checkout/success?session=42"

cancel_url string (URL)

HTTPS return if the shopper abandons checkout.

Absolute https:// · e.g. "https://app.example.com/checkout/cancel"

customer_email string

Pre-fills email in checkout when set.

Email · e.g. "buyer@example.com"

customer_name string

Pre-fills name when set.

Display name · e.g. "Alex Rivera"

Line item objects (`line_items[]`)

Multiple lines for carts or itemized receipts; one object is enough for a single SKU. Omit or send one row when you do not need a breakdown.

name string

Line label on the receipt.

Non-empty string · e.g. "API subscription (monthly)"

quantity number

Units on this line.

Typically ≥ 1 · e.g. 2

unit_amount number

Unit price in major units (usually 2 decimals).

≥ 0; 2 decimals · e.g. 12.50

total number

Line total (qty × unit after line adjustments); should roll up to order totals.

≥ 0; 2 decimals · e.g. 25.00

Example request

cURL (staging)

curl -sS -X POST "https://uatstage00-api.rapidcents.com/api/YOUR_BUSINESS_ID/checkout/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Origin: https://your-https-app.example.com" \
  -d '{
    "ui_mode": "hosted",
    "mode": "payment",
    "amount_total": 49.99,
    "amount_subtotal": 49.99,
    "currency": "CAD",
    "success_url": "https://your-https-app.example.com/thank-you?order=1",
    "cancel_url": "https://your-https-app.example.com/cart",
    "customer_email": "buyer@example.com",
    "line_items": [
      { "name": "Item", "quantity": 1, "unit_amount": 49.99, "total": 49.99 }
    ]
  }'

Example response

Use checkout_url as Location for 302 / 303:

checkout_session

{
    "ok": true,
    "message": "Checkout session created successfully",
    "status": "PENDING",
    "checkout_session": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "token": "a1b2c3d4e5f6789012345678901234567890abcdef0123456789abcdef012345",
        "checkout_url": "https://checkout.rapidcents.com/session/a1b2c3d4\u2026/embedded",
        "allowed_origins": [
            "https://shop.example.com"
        ],
        "expires_at": "2026-04-21T18:00:00.000000Z",
        "session_status": "PENDING",
        "payment_status": "UNPAID",
        "amount_total": 49.99,
        "amount_subtotal": 49.99,
        "amount_tax": 0,
        "amount_discount": 0,
        "surcharge": false,
        "amount_surcharge": 0,
        "surcharge_rate": null,
        "currency": "CAD",
        "mode": "payment",
        "description": null,
        "customer_id": null,
        "customer_email": "buyer@example.com",
        "customer_name": "Alex Rivera",
        "client_reference_id": null,
        "success_url": "https://shop.example.com/thank-you?order=1",
        "cancel_url": "https://shop.example.com/cart",
        "return_url": null,
        "metadata": [],
        "ui_mode": "embedded",
        "created_at": "2026-04-21T12:00:00.000000Z",
        "billing_address_collection": null,
        "shipping_address_collection": null,
        "billing_address": null,
        "shipping_address": null,
        "consent": null,
        "consent_collection": null,
        "phone_number_collection": null,
        "line_items": [
            {
                "name": "Premium plan (monthly)",
                "quantity": 1,
                "unit_amount": 49.99,
                "total": 49.99
            }
        ],
        "discounts": null,
        "apply_discount": null,
        "total_details": null,
        "invoice_creation": null,
        "tax_id_collection": null
    },
    "transaction": null
}

checkout_session.token — store as your external session or order correlation id.
checkout_session.checkout_url — load in an iframe, new tab, or follow as a redirect depending on the mode.

Browser usage, success_url / cancel_url, security, and common errors are documented once in Checkout overview → Browser / frontend, Success & cancel URLs, Security, and Common errors.