RapidPay

Summary

RapidPay is the RapidCents compact payment API for processing card-not-present transactions. RapidPay provides a lightweight, RapidCents-hosted payment modal that loads inside an iframe on your page. The customer enters their card details directly on the RapidCents secure form — your server and your frontend never handle or see card data.

RapidPay vs Checkout Sessions

RapidCents offers three ways to accept payments. All three keep card data off your servers:

Processing Flow

Here is how a RapidPay payment flows — card data never touches your servers:

What Happens During a Payment

1. Your server creates a session — You POST the amount, currency, and customer email to the RapidCents API with your Bearer token. RapidCents returns a checkout_url.
2. The RapidPay modal loads in an iframe — Your frontend opens the checkout_url in an iframe using the RapidPay JavaScript library (rapid.js). The customer sees a compact payment modal hosted entirely by RapidCents.
3. Customer enters card details on RapidCents — The card number, expiry, CVV, and billing address are entered directly on the RapidCents-hosted form. Your page never has access to this data.
4. RapidCents processes the payment — The card is tokenized, 3D Secure is applied (if enabled), and the payment is submitted to the card networks for authorization.
5. Your page receives the result — RapidCents sends a postMessage to your parent page with the payment result (success/failure, transaction ID, receipt ID). You handle this in your JavaScript callbacks.

Authentication

All RapidPay endpoints require OAuth 2.0 Bearer token authentication. Every request must include a valid access token in the Authorization header.

Required Headers

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

Base URL Pattern

All RapidPay endpoints follow the pattern /api/{business_id}/... where {business_id} is your RapidCents Business UUID.

Credentials Provided During Onboarding

During merchant onboarding, RapidCents provides the following credentials. Store them securely on your server — never expose them in client-side code.

OAuth Token Flow

RapidCents uses OAuth 2.0 for authentication. The token endpoint supports both Password Grant (initial login) and Refresh Token grant.

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
}

Token Refresh Strategy

We recommend implementing automatic token refresh in your backend:

1. Store token expiry — When you receive a token response, calculate the absolute expiry time (now + expires_in) and persist it alongside the tokens.
2. Check before each API call — Before making any RapidPay API call, compare the current time against your stored expiry. If the token expires within the next 5 minutes, refresh it first.
3. Handle 401 gracefully — If you receive a 401 Unauthorized response, attempt a token refresh and retry the request once. If the refresh also fails, alert your operations team.
4. Secure storage — Store credentials in encrypted environment variables or a secrets manager. Never commit tokens to source control.

IP Whitelisting

RapidCents enforces IP-based access control on all RapidPay endpoints. Only requests originating from your whitelisted server IPs are permitted to create checkout sessions and process saved card sales.

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.

Step 1 — Create a RapidPay Session

From your server, call the RapidPay API to create a checkout session. This returns a checkout_url which you'll load in an iframe on your page. You only need to send the amount, currency, and customer email — no card data is needed from your server.

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

{
  "amount_total": 150.00,
  "currency": "CAD",
  "customer_email": "[email protected]"
}

Request Fields

{
  "ok": true,
  "checkout_session": {
    "id": "session-uuid",
    "token": "a1b2c3d4e5f6...",
    "checkout_url": "https://dashboard.rapidcents.com/customer/checkout-rapid/a1b2c3d4e5f6...",
    "ui_mode": "rapid",
    "amount_total": 150.00,
    "currency": "CAD"
  }
}

Step 2 — Load the Payment Modal

On your frontend, include the RapidPay JavaScript library and use it to open the payment modal in an iframe. The customer enters their card details directly on the RapidCents-hosted form — your page never has access to card data.

Include the Script

<!-- RapidPay JavaScript Library -->
<script src="https://api.rapidcents.com/js/rapid.js"></script>

Initialize and Open Modal

// Initialize RapidPay with your business credentials
RapidCentsCheckout.init({
  businessId: 'your-business-id',
  authToken: 'your-access-token',

  // Callbacks
  onSuccess: function(data) {
    console.log('Payment successful!', data.session_id, data.transaction_id);
    // Verify on your server, then fulfill the order
  },
  onCancel: function(data) {
    console.log('Payment cancelled', data.session_id);
  },
  onError: function(error) {
    console.error('Payment error:', error.message);
  }
});

// When the customer clicks "Pay Now"
document.getElementById('pay-button').addEventListener('click', function() {
  RapidCentsCheckout.create({
    ui_mode: 'rapid',
    amount_total: 150.00,
    currency: 'CAD',
    customer_email: '[email protected]'
  });
});

How the Modal Works

1. Session creation — The library calls POST /api/{business_id}/rapid-checkout/create with the amount and customer email. RapidCents validates the OAuth client origin and returns a checkout_url.
2. Iframe loads — The library opens the checkout_url in a secure iframe. The customer sees a compact payment form with the amount, card fields, and a “Pay” button.
3. Customer enters card — The card number, expiry, CVV, and billing address are entered on the RapidCents form. If 3D Secure is enabled, the bank authentication challenge appears inside the same iframe.
4. Result via postMessage — After payment processing, RapidCents sends a postMessage to your page with the result. Your onSuccess, onCancel, or onError callback fires accordingly.

Origin Validation

Step 3 — Handle Payment Result

When the payment completes (or is cancelled/fails), RapidCents sends a postMessage from the iframe to your parent page. The RapidPay library automatically parses this and fires your registered callbacks.

Success Callback

{
  "session_id": "a1b2c3d4e5f6...",
  "transaction_id": "txn-uuid-5678",
  "receipt_id": "receipt-uuid-9012",
  "amount": 150.00,
  "currency": "CAD"
}

Error / Failure Callback

{
  "message": "Payment declined",
  "error_code": "ND",
  "session_id": "a1b2c3d4e5f6..."
}

If the customer exceeds the maximum payment attempts (3), RapidCents returns error_code: "max_attempts_reached" and automatically closes the session.

What to Do After Payment

1. Verify on your server — Always verify the payment status from your backend using the session token (see next section). Never trust client-side data alone.
2. Store the references — Save transaction_id and receipt_id in your database for reconciliation, refunds, and support.
3. Update order status — Mark the order as paid and trigger fulfillment.
4. Notify the customer — Send a confirmation email or in-app notification.

Verify Payment (Server-Side)

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

After the onSuccess callback fires, always verify the payment on your server before fulfilling the order. This prevents fraud from manipulated client-side data.

GET /api/{business_id}/checkout/{session_token}/details
Authorization: Bearer {access_token}

{
  "ok": true,
  "checkout_session": {
    "session_status": "COMPLETED",
    "payment_status": "PAID",
    "amount_total": 150.00,
    "currency": "CAD",
    "customer_email": "[email protected]"
  },
  "transaction": {
    "id": "txn-uuid-5678",
    "receipt_id": "receipt-uuid-9012",
    "response_code": "AA",
    "card": "411111******1111",
    "association": "Visa"
  }
}

Saved Card Sale (Card on File)

POST /api/{business_id}/customer/{customer_id}/sale

Process a payment using a previously tokenized card. When a customer pays through the RapidPay modal, their card is automatically tokenized by RapidCents. You receive a cardId which you can use for future charges without the customer re-entering their card details.

Request Fields

POST /api/{business_id}/customer/{customer_id}/sale
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "amount": 29.99,
  "cardId": "card-uuid-abcd-1234",
  "ip_address": "203.0.113.42"
}

{
  "ok": true,
  "status": "Approved",
  "code": "AA",
  "message": "Approved Transaction (Auths / Reversals)",
  "receiptID": "receipt-uuid-9012",
  "recordID": "txn-uuid-5678"
}

Automatic Card Tokenization

When a customer completes a payment through the RapidPay modal, their card is automatically tokenized by RapidCents. You receive a cardId in the transaction details which you can use for future saved card operations.

All Endpoints

RapidPay Checkout

Saved Card Endpoints

Authentication Endpoints

Environment Configuration

Response Codes

The code field in the response indicates the transaction outcome:

Error Handling

Security Best Practices

• Card data never touches your servers — All card entry happens on the RapidCents-hosted payment modal. Your servers only handle session creation (amount + email) and receive payment results (transaction IDs).
• Use HTTPS exclusively — All API communication must use TLS/HTTPS. The RapidPay modal is served over HTTPS.
• Rotate tokens proactively — Refresh access tokens before the 24-hour expiry. Store both new access_token and refresh_token from each refresh response.
• Store only references — Persist transaction_id, receipt_id, and session_id — never card details. Use cardId for saved card operations.
• Verify payments server-side — Always verify payment status from your backend using GET /checkout/{token}/details before fulfilling orders. Never trust client-side callbacks alone.
• Validate OAuth origins — Ensure your OAuth client redirect URL matches the domain where the RapidPay modal is loaded. Origin mismatches will block session creation.
• Whitelist your server IPs — Ensure all server IPs making API calls are whitelisted with RapidCents. Update the whitelist before infrastructure changes.

Integration Checklist

Authentication & Setup

• OAuth token refresh is implemented and tokens are stored securely
• Token expiry is tracked and refreshed proactively (before 24-hour expiry)
• Both access_token and refresh_token are persisted on each refresh
• Server IP(s) have been submitted to RapidCents and confirmed whitelisted
• Staging and production credentials are stored separately
• OAuth client redirect URL matches the domain where RapidPay modal loads

Frontend Integration

• RapidPay JavaScript library (rapid.js) is loaded on your page
• RapidCentsCheckout.init() is called with correct businessId and authToken
• onSuccess, onCancel, and onError callbacks are implemented
• Session creation (create()) is triggered by a user action (button click)
• Payment modal loads correctly in the iframe

Payment Verification

• Server-side payment verification is implemented (GET /checkout/{token}/details)
• session_status: "COMPLETED" and payment_status: "PAID" are checked before fulfilling orders
• transaction_id and receipt_id are stored for reconciliation and refunds
• Error scenarios (cancelled, failed, expired sessions) are handled gracefully

Saved Card Operations (Optional)

• Saved card sale works using cardId from previous transactions
• All decline codes (ND, NC, NR, N7) are handled gracefully