RapidCents V1 API

Checkout overview

Your backend creates a checkout session with RapidCents. The response includes checkout_url (where the shopper pays) and a session token. Never call session APIs from the browser with your API key.

Checkout modes

Subscription checkout — same v1/checkout/create API with mode: subscription (embedded or hosted). See the guide for plan fields and line_items.

APIs you need

• Embedded / Hosted / Subscriptions — POST {API origin}/api/v1/checkout/create (JSON).
• RapidPay — POST {API origin}/api/v1/checkout-pay (JSON).
• Session details — GET {API origin}/api/v1/checkout/{session_token}/details. Use the session token from your create or pay response. After the shopper pays, this returns updated checkout_session state and, when available, a transaction object with the approved charge. Optional: ?expand=refunds to include refund rows for that charge. The payment id for void and refund is transaction.transactionID.
• Void — POST {API origin}/api/v1/voids. Body: {"payment": "<payment id>"}. Use while the approved charge is still in an open batch.
• Refund — POST {API origin}/api/v1/refunds. Body: payment and optional amount in cents. Omit amount to refund the full remaining balance. Retrieve one refund with GET {API origin}/api/v1/refunds/{refund_id}.

Staging vs production base URLs:

Authentication

The V1 API uses API key authentication. Your secret API key (rc_sk_...) is created in the RapidCents dashboard and used as a Bearer token on all server-side requests.

• Create an API key in the RapidCents dashboard; set the intended_domain to your app's HTTPS origin.
• Keep your rc_sk_ key on the server only. Never expose it in client-side code.
• Use Authorization: Bearer rc_sk_... on all API requests.

Create an API key

In the RapidCents dashboard open Developers → API keys (/dashboard/developers/api-keys) and add a key.

• Intended domain — your app's public HTTPS origin, for example https://shop.example.com. Every checkout request must send that same value in the Origin header.
• Secret — the dashboard shows rc_sk_... once. Copy it then. It is not shown again.
• This demo — Admin → Gateways → edit the environment → paste it into Secret API key.

Create a webhook secret

The webhook signing secret is separate from the API key. RapidCents uses it to sign each delivery. Your server uses the same value to verify the Signature header.

• In the dashboard open Developers → Webhooks (/dashboard/developers/webhooks) and add an endpoint.
• URL — your public HTTPS receiver. For this demo, use the URL shown on the gateway form (/webhooks/payment).
• Events — select the events you want, including checkout, payment, and subscription events.
• Signing secret — the dashboard shows rc_whsec_... once, when the endpoint is created and again if you rotate it. Copy it then.
• This demo — paste that value into the gateway environment Webhook secret field. When it is set, this app rejects deliveries whose HMAC-SHA256 signature does not match the raw body.

Payload shape, signature check, and event list: Webhooks.

Checkout request headers

curl -sS -X POST "https://uatstage00-api.rapidcents.com/api/v1/checkout/create" \
  -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 '{
    "ui_mode": "embedded",
    "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 }
    ]
  }'

{
    "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
}

curl -sS -G "https://uatstage00-api.rapidcents.com/api/v1/checkout/SESSION_TOKEN_FROM_CHECKOUT_SESSION/details" \
  --data-urlencode "expand=refunds" \
  -H "Authorization: Bearer rc_sk_YOUR_SECRET_KEY" \
  -H "Accept: application/json" \
  -H "Origin: https://your-https-app.example.com"

{
    "ok": true,
    "message": "Checkout session created successfully",
    "status": "COMPLETED",
    "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": "COMPLETED",
        "payment_status": "PAID",
        "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": 1001,
        "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": {
            "order_id": "42"
        },
        "ui_mode": "embedded",
        "created_at": "2026-04-21T12:00:00.000000Z",
        "line_items": [
            {
                "name": "Premium plan (monthly)",
                "quantity": 1,
                "unit_amount": 49.99,
                "total": 49.99
            }
        ]
    },
    "transaction": {
        "code": "AA",
        "message": "Approved Transaction (Auths / Reversals)",
        "receiptID": 50001,
        "transactionID": 90001,
        "details": {
            "merchant_name": "Example Merchant",
            "merchant_address": "123 Main St",
            "merchant_number": "+1-555-0100",
            "card": "VISA 4242",
            "date": "Mon, Apr 21, 2026 1:15 PM",
            "association": "Visa",
            "amount": 49.99,
            "customer": {
                "id": 1001,
                "name": "Alex Rivera",
                "email": "buyer@example.com"
            },
            "issuer_reference": "AUTH123456",
            "source": "checkout_session"
        }
    }
}

curl -sS -X POST "https://uatstage00-api.rapidcents.com/api/v1/voids" \
  -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 '{
    "payment": "90001"
  }'

{
  "id": 90001,
  "object": "payment",
  "amount": 4999,
  "amount_received": 4999,
  "amount_refunded": 0,
  "currency": "cad",
  "status": "voided",
  "paid": false,
  "is_voided": true,
  "void_reference": "VOID123456",
  "created": 1713700000
}

curl -sS -X POST "https://uatstage00-api.rapidcents.com/api/v1/refunds" \
  -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 '{
    "payment": "90001",
    "amount": 500
  }'

{
  "id": 91002,
  "object": "refund",
  "payment": 90001,
  "amount": 500,
  "currency": "cad",
  "status": "succeeded",
  "created": 1713700100
}

curl -sS "https://uatstage00-api.rapidcents.com/api/v1/refunds/91002" \
  -H "Authorization: Bearer rc_sk_YOUR_SECRET_KEY" \
  -H "Accept: application/json" \
  -H "Origin: https://your-https-app.example.com"

Browser / frontend

• Keep your API key (rc_sk_) on your server only; your frontend should talk to your backend and let the backend call RapidCents.
• Embedded (v1/checkout/create) — Required checkout.js at {API origin}/js/checkout.js (RapidCentsCheckout). Staging / production: https://uatstage00-api.rapidcents.com/js/checkout.js · https://api.rapidcents.com/js/checkout.js. Guide + sample: Embedded → checkout.js, embedded sample HTML.
• Hosted — Redirect to checkout_url after create succeeds.
• RapidPay — After server v1/checkout-pay, use required rapid.js with data-checkout-url to inject the checkout_url in an iframe ({API origin}/js/rapid.js).
• If you use postMessage, verify event.origin matches the checkout URL origin (and for embedded, that event.source is the checkout iframe).

Success & cancel URLs

Creating a session returns payment UI (checkout_url) and a token. Redirects and postMessage improve UX only—confirm capture on your server using the mechanism RapidCents documents for your integration before fulfilling orders.

By checkout mode

• Embedded — Use required checkout.js (RapidCentsCheckout.create with ui_mode: embedded) so the library mounts the iframe and handles postMessage (rc:checkout_height, rc:checkout_result), or create the session on your server and set the iframe src to checkout_url yourself. Always validate e.source and e.origin if you listen for messages. See Embedded → checkout.js.
• Hosted — After 200, send the browser to checkout_url with 302 or 303 (prefer 303 after a POST “start checkout” so the form is not resubmitted). The shopper returns to your success_url or cancel_url when checkout finishes.
• RapidPay — v1/checkout-pay does not accept success_url / cancel_url in the body. Mount checkout_url in the browser with rapid.js (data-checkout-url), then handle postMessage (or the rapidcents-checkout event) as needed; confirm payment server-side before fulfillment.
• Subscriptions — Same success_url / cancel_url behaviour as one-time checkout/create when the API requires those fields.

success_url

• Absolute https:// URL; add your own id in the query if needed.
• Not proof of payment—users can open or replay the URL. Keep “thank you” logic idempotent.

cancel_url

• Absolute https:// URL where RapidCents may send the shopper if they abandon checkout (when the API requires it).

Security

• Never send your secret API key (rc_sk_...) to the browser or mobile app—keep it server-side only.
• Store your API key encrypted at rest; never commit it to version control.
• Origin must be HTTPS and match the intended_domain configured on your API key.
• Call RapidCents only over TLS; do not disable certificate checks in production.
• Log session token and your own order ids for support.

Common errors

Common HTTP status codes

• 401 Unauthorized — Missing or invalid API key. Check that you're using a valid rc_sk_... key in the Authorization: Bearer header.
• 403 Forbidden — API key is valid but not allowed for this business or operation.
• 422 Unprocessable Entity — Validation failed (missing fields, wrong types, amounts out of range, invalid currency, or Origin doesn't match intended_domain). Read the response body for field errors.
• 400 Bad Request — Malformed JSON or an invalid combination of fields (for example, ui_mode / mode).

Common integration mistakes

• Origin mismatch — Origin header does not match the intended_domain configured on your API key.
• Wrong environment — Staging credentials or base URL used against production, or the reverse.
• Invalid return URLs — success_url / cancel_url not absolute HTTPS where the API requires them.
• Amounts — Use decimal amounts to the precision the API expects; avoid floating-point drift in application code.