JavaScript

JavaScript integration

Overview

To integrate with Roqqett using Javascript, you'll need to include a JavaScript library served from Roqqett. The library is responsible for taking your customers to the correct place on desktop, mobile web, and app. The outcome of the payment and cart will be communicated via webhooks to the endpoint that you defined when creating the checkout in the Roqqett portal. The customer is then taken to the return URL similarly designated in the checkout.

Javascript calls and flow during payment

On page load, a Roqqett instance must be created that takes a callback as an argument. The callback will be given a transferId as an argument, which must be given back to Roqqett through the API.

Copy

Copied

 let roqqett;
   window.onload = function () {
    roqqett = new Roqqett(callback);
  };

  async function callback(transferId) {
        ...
  }

The customer is transferred to Roqqett by calling the roqqett.checkout() function on the Roqqett object.

This in turn calls a "callback" that you define and provide when instantiating the Roqqett object. This triggers your backend service to initiate the cart via /carts.

The outcome of the cart is sent via the payment webhooks. The customer is then taken back to your domain using the return URL specified in the checkout instance.

info

You can have multiple live checkouts at any one time, each with their own return URL. You can configure a checkout's return URL in the Checkouts area of the Roqqett portal.

Integration steps

Add our button on your webstore's payment page to allow your customers to pay with Roqqett.

info

Download our brand-ready pack of buttons for a wide selection of buttons to use.

When your customer clicks our button, our library will provide you with a transferId. You can use this transferId to create a cart. After you create a cart, our library allows the user to pay you with our app or in their browser.

While the payment is in process, our library will manage the payment journey and customer experience.

Once paid, our server will communicate this and redirect your customer to a page of your choosing.

Security warning

Keep sensitive information, such as product price and availability on your server. This will prevent customers from manipulating this information.

Integrating the Roqqett Javascript library

To integrate the Roqqett checkout library with your existing frontend codebase, include the following script tag inside the <head> of your top-level HTML file:

Copy

Copied

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

Including the Roqqett button

You should include a Roqqett button on your webstore's payment page. This is an example button:

Button packs

Learn more about our button pack.

Initialising the library

The Roqqett checkout library should be initialised when the page with the Roqqett button loads. To do this, you should initialise a new Roqqett object.

Copy

Copied

let roqqett;

window.onload = function() {
    roqqett = new Roqqett();
  }

Getting and consuming a transfer ID

To transfer your customer to the Roqqett payment flow, you must create a cart. A cart requires a transferId to synchronise details with our system.

To get a transferId, call the asynchronous .carts() function on the Roqqett object. Note: the onclick handler of the Roqqett button should handle this.

This function will return an object containing both:

your transferId for this transaction
a value indicating whether the transferId is safe to use

Finally, forward your transferId to your backend endpoint which creates a cart. Our library will handle the rest.

Transfer still 'fresh'?

You should always check if the transferId is fresh before consuming it, otherwise creating the cart may fail.

Copy

Copied

async function checkout() {
   const { transferId, isFresh } = await roqqett.checkout();
   if (isFresh) {
    // Forward the transferId to the endpoint on your server
    // responsible for creating a cart
     callMerchantBackend(transferId);
     }
  }

Creating a cart

Your backend should make a request to /carts via HTTP POST. This endpoint will create a cart, which our library consumes to allow your customer to pay with Roqqett.

Your headers must include the X-API-KEY header, with the value set to the API secret you created in the Roqqett portal.

Once the cart has been created, our library will initiate the customer payment journey.

During payment

Roqqett handles the entire payment journey, so from a store-side perspective there is little to do apart from waiting to receive confirmation of payment success or abandonment.

Learn more about the payment flow.

After payment

Payment success

Once payment is confirmed, our backend will send you the Cart Completed webhook.

We include the following body values:

cartId : the ID of the created cart
merchantCartId : the ID of the cart in your records or domain
paymentId : the unique ID of the payment record in our system
orderId : the unique ID of the resultant order record in our system

At the same time, our library will redirect your customer to your checkout's return URL after they have finished payment.

info

You can have multiple live checkouts at any one time, each with their own return URL. You can configure a checkout's return URL on the Checkouts area of the Roqqett portal.

Placing orders

You should only record the order once you have received the Cart Completed webhook.

You can query the payment record at https://api.roqqett.com/checkout/payments/{paymentID} via HTTP GET. Again, you must include a valid X-API-KEY header with your request.

Payment cancellation

If the cart is cancelled, our backend will send you the Cart Cancelled webhook.

We include the following query parameters:

cartId : the ID of the cart
merchantCartId : the ID of the cart in your records or domain

Cancellations occur when the user has cancelled out of the process and returned to your checkout, or your backend has specifically cancelled the cart via a call to /carts/{cartId}/cancel endpoint.

In either case, our library will handle the user journey and return them to your page. The end user can then retry payment with Roqqett or another payment method.

Payment abandonment

If the customer simply abandons the payment, our backend will send you the Cart Abandoned webhook after a fixed amount of time.

We include the following query parameters:

cartId : the ID of the cart
merchantCartId : the ID of the cart in your records or domain

info

The expiry time that leads to the abandonment event is set to a default of 20 minutes. However, you can customise this time by providing a different value as the expiryTimeMinutes parameter when calling the /carts endpoint.