Checkout Sessions

Summary

Checkout Sessions let merchants create secure, pre-configured payment sessions that customers complete through a RapidCents-hosted payment page (hosted mode) or an embedded iframe on the merchant’s website (embedded mode). In both modes, the customer enters their card details directly on the RapidCents-hosted form — your server and your frontend never handle or see card data.

Checkout Session Lifecycle

1. Create — Merchant creates a checkout session via the API with amount, customer, URLs, and configuration. A unique session_token and checkout_url are returned.
2. Present — For hosted mode, the customer is redirected to the checkout URL. For embedded mode, the checkout form loads in an iframe on the merchant’s page.
3. Pay — Customer enters payment details directly on the RapidCents-hosted form (card, saved card, or Google Pay) and submits. 3D Secure step-up is triggered if enabled. The merchant’s server never receives card data.
4. Complete — On approval, the session status changes to COMPLETED and payment status to PAID. The customer is redirected to the success_url with the session_token appended.
5. Verify — Merchant retrieves the session details via the API to confirm payment status and get transaction details.

Session Statuses

Session Status

Payment Status

UI Modes

Processing Flow

Hosted Mode

Embedded Mode

Authentication

All merchant-facing Checkout Session endpoints require OAuth 2.0 Bearer token authentication. Customer-facing (public) endpoints use the session token in the URL as an implicit access token.

Required Headers

Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

Obtaining an Access Token

RapidCents uses OAuth 2.0 with the Password Grant and Refresh Token flows. You will receive the following credentials during merchant onboarding:

IP Whitelisting

RapidCents enforces IP-based access control on all payment processing endpoints. Only requests originating from your whitelisted server IPs are permitted to create checkout sessions and process payments.

How to Whitelist

1. Identify your server IPs — Determine the static/elastic IP address(es) of the server(s) that will make API calls to RapidCents. If you use a load balancer or NAT gateway, provide the outbound IP.
2. Submit to RapidCents — Provide your IP address(es) to the RapidCents integration team during onboarding or via your account manager.
3. Confirmation — RapidCents will whitelist your IPs and confirm. You can then begin making API calls.
4. Update when IPs change — If your server infrastructure changes and your outbound IP changes, contact RapidCents to update the whitelist before migrating.

OAuth Token Flow

Refresh Access Token

POST /api/oauth/token

Access tokens expire after 24 hours. Use the refresh token to obtain a new access token without re-authenticating.

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "{your_refresh_token}",
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}",
  "redirect_uri": "",
  "scope": ""
}

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
  "refresh_token": "def50200a3c2f7...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Create Checkout Session

POST /api/{business_id}/checkout/create

Request Body

POST /api/{business_id}/checkout/create
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "amount_total": 150.00,
  "amount_subtotal": 130.00,
  "amount_tax": 20.00,
  "currency": "CAD",
  "customer_email": "[email protected]",
  "customer_name": "John Doe",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "ui_mode": "hosted",
  "description": "Order #1234",
  "line_items": [
    { "name": "Widget Pro", "quantity": 2, "unit_amount": 50.00, "total": 100.00 },
    { "name": "Premium Support", "quantity": 1, "unit_amount": 30.00, "total": 30.00 }
  ],
  "billing_address_collection": "required",
  "metadata": { "order_id": "1234" }
}

{
  "ok": true,
  "message": "Checkout session created successfully",
  "status": "PENDING",
  "checkout_session": {
    "id": "session-uuid",
    "token": "a1b2c3d4e5f6...64chars",
    "checkout_url": "https://dashboard.rapidcents.com/customer/checkout/a1b2c3...",
    "session_status": "PENDING",
    "payment_status": "UNPAID",
    "amount_total": 150.00,
    "currency": "CAD",
    "expires_at": "2026-06-09T12:00:00.000000Z",
    "ui_mode": "hosted",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel"
  },
  "transaction": null
}

Line Items

Subscription Mode

{
  "amount_total": 49.99,
  "customer_email": "[email protected]",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "mode": "subscription",
  "line_items": [
    { "name": "Pro Plan", "quantity": 1, "unit_amount": 49.99, "total": 49.99 }
  ],
  "subscription": {
    "interval": "Monthly",
    "start_date": "2026-07-01",
    "name": "Pro Plan Monthly"
  }
}

Subscription Intervals

Get Checkout Session Details

GET /api/{business_id}/checkout/{session_token}/details

Retrieve full session details including transaction information after payment. Use this endpoint on your success_url page to verify the payment.

{
  "ok": true,
  "status": "COMPLETED",
  "checkout_session": {
    "session_status": "COMPLETED",
    "payment_status": "PAID",
    "amount_total": 150.00
  },
  "transaction": {
    "code": "AA",
    "message": "Approved Transaction (Auths / Reversals)",
    "receiptID": "receipt-uuid",
    "transactionID": "transaction-uuid",
    "details": {
      "association": "Visa",
      "amount": 150.00,
      "issuer_reference": "ref-123456",
      "source": "checkout_session"
    }
  }
}

List Checkout Sessions

GET /api/{business_id}/checkout-sessions

Returns a paginated list of checkout sessions with optional filters.

Get Session Data (Internal)

GET /api/checkout/{session_token}/data

Used by the RapidCents checkout form to load session details, business info, saved cards, and 3DS configuration. No authentication required (session token in URL acts as implicit access).

Create Customer for Session (Internal)

POST /api/checkout/{session_token}/customer

Process Payment (Internal)

POST /api/checkout/{session_token}/pay

Called by the RapidCents checkout form when the customer submits payment. Card data is sent directly from the RapidCents-hosted form to this endpoint — it never passes through the merchant’s server or frontend.

Payment Methods

New Card

{
  "payment_method_type": "new_card",
  "amount": 150.00,
  "customerId": "customer-uuid",
  "cardData": {
    "cardNumber": "4111111111111111",
    "month": "12",
    "year": 2028,
    "nameOnCard": "John Doe",
    "cvv": "123",
    "saveCard": false,
    "address": { "postalCode": "M5V 2T6", "line1": "123 Main St" }
  }
}

Saved Card

{
  "payment_method_type": "saved_card",
  "amount": 150.00,
  "customerId": "customer-uuid",
  "cardId": "stored-card-uuid"
}

Google Pay

{
  "payment_method_type": "google_pay",
  "amount": 150.00,
  "customerId": "customer-uuid",
  "googlePayToken": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\",...}"
}

{
  "ok": true,
  "message": "Payment successful",
  "result": { "code": "AA", "recordID": "txn-uuid", "receiptID": "receipt-uuid" },
  "success_url": "https://yoursite.com/success?session_token=a1b2c3d4..."
}

{
  "ok": false,
  "message": "Payment failed. Please check your payment details and try again.",
  "attempt_count": 1,
  "max_attempts": 3,
  "cancel_url": "https://yoursite.com/cancel?session_token=a1b2c3d4..."
}

RapidCents Checkout.js Library

For embedded and hosted checkout integrations, RapidCents provides a client-side JavaScript library that handles session creation, iframe management, and payment result callbacks.

Installation

<script src="https://api.rapidcents.com/js/rapidcents-checkout.js"></script>

Initialization

RapidCentsCheckout.init({
  businessId: 'your-business-uuid',
  authToken: 'your-oauth-access-token',
  apiBaseUrl: 'https://api.rapidcents.com/api',
  defaultUiMode: 'embedded',
  containerId: 'rc-checkout',

  // Session verification (recommended)
  verifySessionUrl: '/api/rapidcents/checkout-session',
  autoVerify: true,

  // Callbacks
  onSuccess: function(data) {
    console.log('Payment successful!', data.session_id);
  },
  onCancel: function(data) {
    console.log('Payment cancelled', data.session_id);
  },
  onError: function(error) {
    console.error('Payment error:', error.message);
  }
});

Embedded Mode Example

<!-- HTML -->
<div id="rc-checkout"></div>
<button onclick="startCheckout()">Pay Now</button>

<script src="https://api.rapidcents.com/js/rapidcents-checkout.js"></script>
<script>
  RapidCentsCheckout.init({
    businessId: 'your-business-uuid',
    authToken: 'your-oauth-access-token',
    containerId: 'rc-checkout',
    defaultUiMode: 'embedded',
    onSuccess: function(data) {
      window.location.href = '/order-confirmed?session=' + data.session_id;
    },
    onError: function(error) {
      alert('Payment failed: ' + error.message);
    }
  });

  function startCheckout() {
    RapidCentsCheckout.create({
      amount_total: 99.99,
      customer_email: '[email protected]',
      success_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cancel'
    });
  }
</script>

Library Methods

PostMessage Events (Embedded Mode)

Step-by-Step: Hosted Mode

1. Create a Checkout Session (Server-Side) — From your server, call POST /api/{business_id}/checkout/create with the payment details, success_url, and cancel_url. No card data is needed at this step.
2. Redirect the Customer — Use the checkout_url from the response to redirect: window.location.href = response.checkout_session.checkout_url. The customer is taken to a RapidCents-hosted checkout page where they enter their card details directly.
3. Customer Pays on RapidCents — The customer enters their card number, expiry, CVV, and billing info on the RapidCents-hosted page. Your server and your frontend never handle or see this data. 3D Secure is applied automatically if enabled.
4. Handle the Return — On your success_url page, the session_token is appended as a query parameter. Extract it from the URL.
5. Verify Payment (Server-Side) — Call GET /api/{business_id}/checkout/{session_token}/details to confirm session_status is COMPLETED and payment_status is PAID.

Step-by-Step: Embedded Mode

1. Add the container and script — Add <div id="rc-checkout"></div> and include the Checkout.js script on your page.
2. Initialize and create checkout — Call RapidCentsCheckout.init() with your businessId, authToken, and callbacks. Then call RapidCentsCheckout.create() when the user clicks “Pay Now”.
3. Customer Pays in Iframe — A secure iframe from RapidCents loads inside your page. The customer enters their card details directly on the RapidCents form within the iframe. Your page’s JavaScript and DOM cannot access the card data inside the sandboxed iframe.
4. Handle callbacks — The onSuccess callback receives the session data (session ID, transaction ID, receipt ID). Verify the payment on your server before fulfilling the order.

All Endpoints

Merchant API (Authenticated)

Customer API (Public)

Session Expiry & Limits

Error Handling

After Payment

When the customer completes a payment, the outcome depends on the checkout mode:

Hosted Mode

The customer is automatically redirected to the URL you specified when creating the session:

On your success_url page, extract the session_id from the query string and verify the payment on your server before fulfilling the order.

Embedded Mode

The RapidCents iframe sends a postMessage to your parent page. Your registered callbacks fire automatically: