How ripper checkout works

Read this once and the rest of the docs will be shorter.

The pieces #

The loader is one script tag, r.js, served from https://js.ripper.dev. It reads your publishable key from its own tag, fetches a small manifest, and inserts the runtime. window.ripper works from the first line of your page: calls made before the runtime has loaded are queued and replayed in order, so you never have to wait for it.

The runtime is the checkout itself — the card fields, the panels, the payment. The loader brings it in; you never reference it directly.

The npm package is ripperpay. loadRipper() gives you the same runtime through an import instead of a script tag, for pages that build their JavaScript.

The React component is RipperCheckout, from ripperpay/react. It is the runtime with props.

The Stripe compatibility layer is for pages already written against Stripe.js. It accepts what those pages already send, so an existing integration can move with fewer changes. It is reached by its own loader path, and the native SDK is what to write against for anything new.

What happens when a shopper pays #

You call collect() with an amount. The checkout needs a session, and gets one in whichever way you set up: created in the browser from your publishable key, or created on your server and handed over. It renders the card fields, runs 3-D Secure where the card asks for it, confirms the payment, and shows the shopper the outcome.

collect() resolves rather than rejecting for any payment outcome, including a decline: a refusal is a result, not an exception. The one exception is the runtime failing to load at all.

The words for an outcome #

A payment that was taken has status captured. Prose in these docs may say "paid"; the wire word is captured.

A payment that was held rather than taken has status held and a capture state of authorised, and collect() reports it to your page as authorised. The money is reserved and not yet taken. Shopper-facing copy says "reserved"; the merchant verbs are capture and void.

A payment still being confirmed is pending. One that was refused is declined, and one that failed on our side is failed.

Where the outcome is decided #

On your server, not in the browser. The browser tells your page what happened so it can show the shopper something useful, but the decision your business acts on — fulfil, ship, email — should come from reading the session or the payment from your server, or from the webhook that tells you without being asked.

That is not distrust of the shopper. It is that a browser can be closed, refreshed or driven by someone else, and your server cannot.

Three ways in #

Most integrations use more than one, and they are not alternatives so much as layers.

• The checkout on your page — the loader, the runtime, React or Next.js. Start at the Quickstart.
• The API from your server — create sessions, read payments, receive webhooks. Start at the API reference.
• The hosted payment page — no code at all, a link you send. See The hosted page.

If you are using an AI coding assistant, point it at /llms.txt and it will find the rest.