RapidCents

RapidPay (`v1/checkout-pay`)

One-time payments with a compact JSON body. The response includes a checkout URL for the payment UI. In the browser, load rapid.js from the same API host and pass that URL as data-checkout-url (see below). The POST …/v1/checkout-pay call must run on your server (OAuth, not in the browser). No success_url / cancel_url in the request body. No subscriptions. The payment-testing-app demo uses the same pattern.

When to use

Quick “pay now” flows (invoice, modal checkout).
You split amount_subtotal, tax, discount explicitly.

Need return URLs or subscriptions? Use checkout/create (embedded or hosted).

Staging/production hosts: Overview → APIs.

Required API

POST {API origin}/api/{business_id}/v1/checkout-pay

Same OAuth and Origin rules as checkout/create. Token refresh

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

Same as checkout/create: Bearer token, JSON, Origin.

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}/v1/checkout-pay

business_id string (UUID)

Business id for this API host/environment.

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

Body — customer & amounts (wire JSON)

Fields for POST …/v1/checkout-pay. Validation and rounding rules are enforced by the RapidCents API—use decimal amounts with consistent precision (typically two places).

customer_email string

Payer email.

Valid email · e.g. "payer@example.com"

amount_total number

Charge amount in major units.

≥ 0; 2 decimals · e.g. 11.50

amount_subtotal number

Before tax/discount if you split amounts.

≥ 0; 2 decimals · e.g. 10.00

amount_tax number

Tax component.

≥ 0; 2 decimals · e.g. 1.50

amount_discount number

Discount off the order.

≥ 0; 2 decimals · e.g. 0

surcharge boolean

Surcharge flag per your gateway rules.

true, false · e.g. false

Body — description & metadata

description string

Receipt or dashboard label.

Non-empty string recommended · e.g. "Invoice #1001"

metadata object

Your ids for reconciliation; avoid unnecessary PII.

JSON · e.g. {"order_id": "42", "source": "pos"}

Metadata — suggested keys

Use metadata for stable identifiers for reconciliation. Examples:

order_id Your internal order or invoice id.

cart_id Shopping cart or basket reference.

customer_reference CRM or membership id (non-sensitive).

No success_url or cancel_url

RapidPay does not accept success_url / cancel_url in the request body. In the browser, use rapid.js with data-checkout-url (see the RapidPay doc), then handle completion with iframe postMessage and your own navigation; confirm settlement server-side per RapidCents guidance.

Example request

cURL (staging)

curl -sS -X POST "https://uatstage00-api.rapidcents.com/api/YOUR_BUSINESS_ID/v1/checkout-pay" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Origin: https://your-https-app.example.com" \
  -d '{
    "customer_email": "customer@example.com",
    "amount_subtotal": 10.00,
    "amount_total": 11.50,
    "amount_tax": 1.50,
    "amount_discount": 0,
    "surcharge": false,
    "description": "Order 123",
    "metadata": { "order_id": "42" }
  }'

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.

RapidPay in the browser: `rapid.js`

1. On your server, call POST …/v1/checkout-pay (OAuth, JSON, Origin as for other checkout APIs). 2. From the JSON response, read the session’s checkout URL (often checkout_url or iframe_url — see the response example above). 3. On the page you show the payer, include rapid.js from the same API host you called — {API origin}/js/rapid.js — and set the required data-checkout-url to that checkout URL. The script creates the hosted checkout iframe. You can listen for checkout events via postMessage or the rapidcents-checkout custom event if you need height or completion handling.

URLs (match your environment — Overview → APIs):

Staging: https://uatstage00-api.rapidcents.com/js/rapid.js
Production: https://api.rapidcents.com/js/rapid.js

data-checkout-url is required. data-height is optional (default in rapid.js is min(720px, 90vh) when omitted).

Stubborn Attachments

$20.00

RapidPay · rapid.js (required)

<?php
declare(strict_types=1);
// rapid_pay.php — plain PHP: call v1/checkout-pay, then print a page with rapid.js.
// Configure: API base, business id, OAuth token, HTTPS origin (required by the API), and the payer email.

$apiBase    = rtrim(getenv('RAPIDCENTS_API_BASE') ?: 'https://api.rapidcents.com', '/');
$businessId = getenv('RAPIDCENTS_BUSINESS_ID') ?: 'YOUR_BUSINESS_ID';
$token      = getenv('RAPIDCENTS_ACCESS_TOKEN') ?: 'YOUR_OAUTH_ACCESS_TOKEN';
$origin     = getenv('RAPIDCENTS_HTTPS_ORIGIN') ?: 'https://your-site.example';

$body = [
    'customer_email'  => 'payer@example.com',
    'amount_subtotal' => 20.0,
    'amount_total'    => 20.0,
    'amount_tax'      => 0.0,
    'amount_discount' => 0.0,
    'surcharge'       => false,
    'description'     => 'Order',
];

$endpoint = $apiBase . '/api/' . $businessId . '/v1/checkout-pay';
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'Accept: application/json',
        'Origin: ' . $origin,
    ],
    CURLOPT_POSTFIELDS     => json_encode($body),
]);
$raw  = curl_exec($ch);
$code = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($raw === false || $code < 200 || $code >= 300) {
    http_response_code(500);
    echo 'v1/checkout-pay failed (HTTP ' . $code . ')';
    exit;
}

$data      = json_decode($raw, true) ?: [];
$session   = $data['checkout_session'] ?? [];
$payUrl    = $data['iframe_url'] ?? $data['checkout_url'] ?? $session['iframe_url'] ?? $session['checkout_url'] ?? '';
$scriptSrc = $apiBase . '/js/rapid.js';

if ($payUrl === '') {
    http_response_code(500);
    echo 'No checkout URL in API response.';
    exit;
}
?><!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Rapid checkout</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <div class="w-full">
    <script
      src="<?= htmlspecialchars($scriptSrc, ENT_QUOTES, 'UTF-8') ?>"
      data-checkout-url="<?= htmlspecialchars($payUrl, ENT_QUOTES, 'UTF-8') ?>"
      data-height="min(720px, 90vh)"
    ></script>
  </div>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Rapid checkout</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <div class="w-full">
    <script
      src="https://api.rapidcents.com/js/rapid.js"
      data-checkout-url="PASTE_CHECKOUT_URL_FROM_YOUR_SERVER_RESPONSE"
      data-height="min(720px, 90vh)"
    ></script>
  </div>
</body>
</html>

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.

RapidPay (v1/checkout-pay)