Rapid.js

What crosses the wire

• Where it sits

  In the browser, in front of your server call. It is initialised with a publishable key, mounts as hosted fields inside your markup, and hands your page a token when the customer submits. Your server then creates the payment with that token and its secret key.

• What you send

  The publishable key, your theme configuration, and the container elements to mount into. No card data passes through your code at any point, which is the property the whole design exists to preserve.

• What comes back

  A token, plus lifecycle callbacks your page can listen to: validation state as the customer types, success, failure, and a 3-D Secure challenge that renders inline rather than sending the customer away. The reference names the events and the mount options.

When to use it

• Keeping checkout in your own design

  When a redirect to a hosted page would break the flow, the branding or the conversion path you have already tuned.

• Reducing PCI scope without rebuilding

  Hosted fields keep the card out of your environment, which is the single change that moves most e-commerce integrations to the narrow self-assessment.

• Adding wallets to an existing checkout

  Apple Pay and Google Pay buttons sit alongside the card fields, so the wallet path and the card path produce the same token for your server to charge.

How to implement Rapid.js

What fails, and how you find out

• A content security policy that blocks the fields

  Hosted fields load from RapidCents, so a restrictive policy silently renders an empty box. It is the most common first-day failure and produces no useful JavaScript error.

• Trying to read the card value

  The fields are isolated by design and your page cannot inspect what was typed. Validation state is reported through events; anything that needs the number itself is asking for the one thing hosted fields exist to prevent.

• Treating the token as a payment

  A token is permission to charge, not a charge. Until your server creates the payment, nothing has been authorized and no money has moved, however successful the browser looked.

• Skipping the authentication callback

  If 3-D Secure presents a challenge and your page does not handle the callback, the customer completes it and your checkout never learns the result. The payment response is what confirms the outcome.

Sandbox versus production

• The publishable key selects the environment

  A sandbox publishable key produces sandbox tokens, which only a sandbox secret key can charge. A build shipped with the wrong key fails at the server call, not in the browser, which is where people look first.

• Authentication both ways, on demand

  Documented test cards force a frictionless 3-D Secure pass and a challenge, so the inline challenge callback can be exercised deliberately rather than waited for.

• Styling behaves identically

  Theme values, breakpoints and mobile keyboard behaviour are the same in both environments, so the visual review done in sandbox is the one that holds on production.