Skip to content

RapidCents V1 API

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 …/api/v1/checkout-pay call must run on your server with your API key. 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 v1/checkout/create (embedded or hosted).

Staging/production hosts: Overview → APIs.

Required API

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

Auth: Authorization: Bearer rc_sk_... — see Overview → Authentication.

All V1 checkout API requests require:

  • Authorization: Bearer rc_sk_... - your secret API key from the RapidCents dashboard.
  • Origin - HTTPS origin of your app (for example https://shop.example.com). It must match the intended_domain configured on your API key.
  • Content-Type: application/json and Accept: application/json.

Never expose your API key in the browser

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

HTTP headers

Same as v1/checkout/create: API key, JSON, Origin.

Authorization string
Required

Your secret API key. Server only.

Bearer rc_sk_...

Origin string
Required

Your app's public HTTPS origin; must match the API key's intended_domain.

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

Content-Type string
Required

JSON request body.

application/json

Accept string
Required

JSON response.

application/json

Parameters

Body - customer & amounts (wire JSON)

Fields for POST …/api/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
Required

Payer email.

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

amount_total number
Required

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/v1/checkout-pay" \
  -H "Authorization: Bearer rc_sk_YOUR_SECRET_KEY" \
  -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 …/api/v1/checkout-pay with your API key (Authorization: Bearer rc_sk_...), JSON body, and Origin header. 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, secret API key (rc_sk_...), HTTPS origin (must match intended_domain), and the payer email.

$apiBase = rtrim(getenv('RAPIDCENTS_API_BASE') ?: 'https://api.rapidcents.com', '/');
$apiKey  = getenv('RAPIDCENTS_API_KEY') ?: 'rc_sk_YOUR_SECRET_API_KEY';
$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/v1/checkout-pay';
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey, // rc_sk_... secret API key
        'Content-Type: application/json',
        'Accept: application/json',
        'Origin: ' . $origin, // Must match API key's intended_domain
    ],
    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.