RapidCents

Subscription checkout

POST …/checkout/create with mode: subscription plus subscription fields. Embedded and hosted use the same JSON; only ui_mode changes. RapidPay does not support subscriptions.

When to use

Recurring plans billed through RapidCents checkout.
Choose ui_mode: embedded (iframe) or hosted (redirect) the same way as one-time checkout.

Embedded · Hosted · Overview

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

Parameters

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"

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

Subscription session (`mode: subscription`)

Plan object, amounts, return URLs, line_items, optional customer fields. Only ui_mode differs between embedded and hosted. RapidPay does not support subscriptions.

ui_mode string

Iframe on your domain (embedded) vs full-page redirect to RapidCents (hosted). Only this field differs between the two UX patterns; all other subscription fields are the same.

embedded, hosted

mode string

Subscription checkout.

subscription · e.g. "subscription"

amount_total number

Price per billing period (major units).

≥ 0; 2 decimals · e.g. 29.99

amount_subtotal number

Pre-tax subtotal (often equals amount_total if tax is not split).

2 decimals · e.g. 29.99

currency string

ISO 4217 plan currency.

e.g. "CAD"

success_url string (URL)

HTTPS return after signup (same idea as payment).

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

cancel_url string (URL)

HTTPS return on cancel.

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

customer_email string

Subscriber email if known (may be null).

Email or null · e.g. "sub@example.com"

customer_name string

Subscriber name if known.

String or null · e.g. "Jamie"

subscription object

Plan terms (interval, dates, display name).

Object; see nested rows

subscription.interval string

Billing cadence label (confirm allowed values with RapidCents).

e.g. Weekly, Monthly, Annual

subscription.start_date string (date)

When billing should start.

ISO date · e.g. "2026-04-17"

subscription.is_installment boolean

Installment plan vs standard recurring.

true, false · e.g. false

subscription.name string

Plan name shown to the customer.

Non-empty string · e.g. "Pro"

line_items array

At least one line matching the subscription price.

Same shape as payment line items · e.g. [{ "name": "Pro", "quantity": 1, … }]

API contract

Confirm subscription field requirements with your RapidCents integration or account manager; APIs may vary by product tier.

Example request

Only ui_mode differs between embedded and hosted.

Embedded (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": "embedded",
    "mode": "subscription",
    "amount_total": 29.99,
    "amount_subtotal": 29.99,
    "currency": "CAD",
    "success_url": "https://your-https-app.example.com/subscription/success?session=1",
    "cancel_url": "https://your-https-app.example.com/plans",
    "customer_email": "subscriber@example.com",
    "subscription": {
      "interval": "Monthly",
      "start_date": "2026-04-17",
      "is_installment": false,
      "name": "Pro plan"
    },
    "line_items": [
      { "name": "Pro plan", "quantity": 1, "unit_amount": 29.99, "total": 29.99 }
    ]
  }'

Example response

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.