Embedded checkout

With the embedded checkout, the Roqqett JavaScript library opens a checkout session in a pop-up window over your page, and tells your page when the payment is complete. The payer never leaves your site. On a desktop computer, the pop-up offers a QR code or a link by text message, so the payer can finish on their phone. The embedded checkout uses the same checkout session as the hosted checkout. Only the way you send the payer to its checkoutUrl is different.

Before you begin

Complete Set up Roqqett. You need the ID of an active SHOPPING checkout.

How it works

Load the library

Your payment page loads the library and creates a Roqqett instance.

The payer clicks your Roqqett button

You call checkout() with a promise of the session’s checkoutUrl. The library opens the pop-up at once, with a holding page.

Your server creates a checkout session

Your server creates the session and returns its checkoutUrl. The pop-up then shows the payment.

The payer pays

The payer approves the payment at their bank, in the pop-up or on their phone.

Roqqett tells you the outcome

The library calls your callbacks in the browser. Your server confirms the session’s status before you fulfil the order.

Step 1: Load the library

Add the script to your payment page, and create the Roqqett instance once the page has loaded.

<script src="https://pay.roqqett.com/api/channel/fulfilment/js"></script>
<script>
  let roqqett;

  window.addEventListener("load", () => {
    roqqett = Roqqett();
  });
</script>

Roqqett() takes no arguments. You pass your callbacks to checkout().

Step 2: Add a Roqqett button

Add a button to your payment page for the payer to choose Roqqett, for example:

<button id="pay-with-roqqett" type="button">Pay by bank with Roqqett</button>

Match the size and corner radius of your other payment buttons. Roqqett button artwork is in the Roqqett button pack.

Step 3: Start the checkout

Call checkout() from your button’s click handler, before any await. Browsers block pop-ups that don’t open straight from a click, so pass checkoutUrl as a promise: the library opens the pop-up at once, and loads the session when the promise resolves.

document.getElementById("pay-with-roqqett").addEventListener("click", () => {
  // Your server creates the checkout session and returns its checkoutUrl.
  const checkoutUrl = fetch("/api/roqqett/checkout-sessions", { method: "POST" })
    .then((response) => response.json())
    .then((session) => session.checkoutUrl);

  roqqett
    .checkout(
      {
        onCompleted: async (event) => {
          // Return true to send the payer to event.returnUrl.
          return true;
        },
        onPending: (event) => {
          // The bank is still settling the payment.
        },
        onCancelled: (event) => {
          // The payer cancelled. Unless event.final, they may retry in the pop-up.
        },
        onFailure: (event) => {
          // A payment failed, the session ended, or the checkout couldn't start.
        },
      },
      { checkoutUrl }
    )
    .catch((error) => {
      // The checkout couldn't start. error.reason says why.
    });
});

If you already have the checkoutUrl when the payer clicks, you can pass it as a string instead. checkout(callbacks, { checkoutUrl, isApp }) takes:

Option	Description
`checkoutUrl`	The session’s `checkoutUrl`, or a promise of it. It must be a Roqqett checkout session link, `https://pay.roqqett.com/ch/pay/s/{checkoutSessionId}`.
`isApp`	Optional. Set to `true` when your page runs inside your own mobile app’s web view. See Mobile apps.

The returned promise resolves with { checkoutSessionId } once the pop-up is connected to the session. It rejects when the checkout can’t start, with an Error whose reason is one of the failure reasons. If the payer clicks again while the pop-up is open, the library brings the pop-up to the front. For the same checkoutUrl, checkout() returns the same promise. For a different one, it refuses with CHECKOUT_IN_PROGRESS.

Callbacks

Each callback is optional, and gets an event with:

checkoutSessionId: the session.
status: completed, pending, cancelled, failed or expired.
final: true when the session has ended and the pop-up has closed.
returnUrl: the session’s returnUrl.
reason: only when the checkout couldn’t start or was ended by the library.

Callback	When it’s called
`onCompleted(event)`	The payment is complete. If you return a truthy value, the library sends the payer to `returnUrl`. Return a falsy value to handle navigation yourself. Without `onCompleted`, the library always sends the payer to `returnUrl`.
`onPending(event)`	The payer approved the payment and the bank is still settling it. Without `onPending`, the library sends the payer to `returnUrl` when they close the pop-up.
`onCancelled(event)`	The payer cancelled at their bank, and can try again in the pop-up. When `final` is `true`, the session itself was cancelled and has ended.
`onFailure(event)`	A bank payment failed, the session expired or was abandoned (`status` is `expired`), or the checkout couldn’t start (`reason` is set). The payer can retry a failed payment until `final` is `true`.

The library only sends the payer to an https return URL. Roqqett doesn’t add query parameters to it, so put your own order reference in each session’s returnUrl. A callback doesn’t prove the payer paid. Before you fulfil the order, confirm the session’s status on your server.

Failure reasons

`reason`	Meaning
`POPUP_BLOCKED`	The browser blocked the pop-up. Call `checkout()` straight from the click, before any `await`.
`POPUP_CLOSED`	The payer closed the pop-up before your `checkoutUrl` promise resolved.
`INVALID_CHECKOUT_URL`	`checkoutUrl` isn’t a Roqqett checkout session link.
`CHECKOUT_URL_FAILED`	Your `checkoutUrl` promise rejected.
`CHECKOUT_IN_PROGRESS`	Another checkout is open in the pop-up.
`SUPERSEDED`	A newer `checkout()` call replaced this one.
`BRIDGE_SETUP_FAILED`	The library couldn’t connect to Roqqett. Ask the payer to try again.

Step 4: Create the checkout session

Your server creates the checkout session exactly as for the hosted checkout, and returns its checkoutUrl to your page. See Create a checkout session. Create a new session for each attempt to pay, with its own idempotencyKey. To stop a session from being paid, for example when the payer chooses another payment method, cancel it.

Mobile apps

If your page runs inside your own mobile app’s web view, pass isApp: true:

roqqett.checkout(callbacks, { checkoutUrl, isApp: true });

The library then opens the checkout in a new window, which an app shell normally hands to the phone’s browser, and doesn’t dim your page. Your callbacks are still called in the app when the payment ends.

Test your integration

V2 checkout sessions have no test mode, and there is no Roqqett sandbox yet. Take a few small real payments, confirm that they reach your settlement account, then refund them. Check the pop-up, the QR code to a phone, and your page’s handling of each callback.

Get started

Accounts & onboarding

Budgets

Payments

Cards

Transactions

Reports

People

Webhooks

Roqqett

Before you begin

How it works

Step 1: Load the library

Step 2: Add a Roqqett button

Step 3: Start the checkout

Callbacks

Failure reasons

Step 4: Create the checkout session

Mobile apps

Test your integration

​Before you begin

​How it works

​Step 1: Load the library

​Step 2: Add a Roqqett button

​Step 3: Start the checkout

​Callbacks

​Failure reasons

​Step 4: Create the checkout session

​Mobile apps

​Test your integration

Before you begin

How it works

Step 1: Load the library

Step 2: Add a Roqqett button

Step 3: Start the checkout

Callbacks

Failure reasons

Step 4: Create the checkout session

Mobile apps

Test your integration