Javascript integration

To integrate with Roqqett using Javascript, you will need to include a javascript library served from Roqqett. The library is responsible for taking the user to the correct place on both desktop, mobile web and app. The outcome of the payment and cart will be communicated via webhooks to the endpoint that you also defined when creating the checkout in Roqqett portal (info / link). The consumer is then returned to the return URL similarly designated in the checkout.

Javascript calls and flow during payment

• On page load, a Roqqett instance must be created which 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.

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

  async function callback(transferId) {
    ...
  }
</script>

• The consumer is transferred to Roqqett by calling roqqett.checkout() function on the roqqett object.
• This in turn calls a 'callback' - that you define and provide when instantiating the roqqett object - that triggers the your backend service to initiate the cart via /carts

• The outcome of the cart is sent via the payment webhooks.
• Consumers are then returned back to the merchant's domain using the return URL - specified in checkout instance.
  
  
  NB: a merchant, at any one time, can have multiple live checkouts, each with their own return URL. You can configure a checkout's return URL on the checkouts page in the Roqqett portal (info / link).

Include our button on your webstore's payment page to allow your customers to pay with Roqqett.
NB: 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 manipulating this information.

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

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

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

📘

Style rules

You must adhere to the following style rules when including the button on your page:

1. The background-color must be #3E3AFF.
2. The white Roqqett logo must be displayed in the centre of the button.
3. The border-radius must be 3px.
4. There must be 8px of vertical padding and 12px of horizontal padding.

<button style="background-color: #3E3AFF; width: 100%; border-radius: 3px; border: 0; height: 48px; cursor: pointer; padding: 8px 12px">
  <svg
    width="111"
    height="24"
    viewBox="0 0 111 24"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
  >
    <path
      fill-rule="evenodd"
      clip-rule="evenodd"
      d="M24 16.0519L12 0L0 16.0519L6 24L8.96064 20.0781L11.9213 24L14.9603 19.9743L17.9992 24L23.9992 16.0519H24ZM11.9213 8.1039L17.9213 16.0519H5.92128L11.9213 8.1039ZM42.8212 4.79913C43.9098 4.79913 44.8691 5.00358 45.6991 5.41247C46.5291 5.82136 47.1755 6.40062 47.6381 7.15024C48.1007 7.88625 48.3321 8.75173 48.3321 9.74669C48.3321 10.6054 48.1416 11.3822 47.7606 12.0774C47.3796 12.7725 46.8625 13.3381 46.2094 13.7742L48.8015 19.1102H44.6786L42.5763 14.6942H40.5556V19.1102H36.8V4.79913H42.8212ZM40.5556 11.6276H42.515C43.1273 11.6276 43.6104 11.464 43.9642 11.1369C44.318 10.7962 44.4949 10.3328 44.4949 9.74669C44.4949 9.16061 44.318 8.70402 43.9642 8.37691C43.6104 8.03617 43.1273 7.8658 42.515 7.8658H40.5556V11.6276ZM54.5302 19.2329C53.3736 19.2329 52.3599 19.0148 51.489 18.5787C50.6318 18.1289 49.965 17.4951 49.4888 16.6774C49.0261 15.8596 48.7948 14.9123 48.7948 13.8356C48.7948 12.7588 49.0261 11.8116 49.4888 10.9938C49.965 10.176 50.6318 9.54906 51.489 9.11291C52.3599 8.66313 53.3736 8.43825 54.5302 8.43825C55.6868 8.43825 56.6937 8.66313 57.551 9.11291C58.4218 9.54906 59.0886 10.176 59.5512 10.9938C60.0275 11.8116 60.2656 12.7588 60.2656 13.8356C60.2656 14.9123 60.0275 15.8596 59.5512 16.6774C59.0886 17.4951 58.4218 18.1289 57.551 18.5787C56.6937 19.0148 55.6868 19.2329 54.5302 19.2329ZM54.5302 16.4116C55.197 16.4116 55.7208 16.1799 56.1018 15.7165C56.4828 15.2394 56.6733 14.6125 56.6733 13.8356C56.6733 13.0587 56.4828 12.4385 56.1018 11.9751C55.7208 11.4981 55.197 11.2596 54.5302 11.2596C53.8635 11.2596 53.3396 11.4981 52.9586 11.9751C52.5776 12.4385 52.3871 13.0587 52.3871 13.8356C52.3871 14.6125 52.5776 15.2394 52.9586 15.7165C53.3396 16.1799 53.8635 16.4116 54.5302 16.4116ZM72.111 23.1991V8.56091H69.0085L68.7228 9.8898C67.9608 8.9221 66.9266 8.43825 65.6204 8.43825C64.6951 8.43825 63.8719 8.66313 63.1507 9.11291C62.4295 9.56269 61.8648 10.2033 61.4566 11.0347C61.0484 11.8525 60.8443 12.7929 60.8443 13.856C60.8443 14.9328 61.0484 15.88 61.4566 16.6978C61.8648 17.5156 62.4295 18.1425 63.1507 18.5787C63.8855 19.0148 64.7087 19.2329 65.6204 19.2329C66.845 19.2329 67.8315 18.7899 68.5799 17.904V23.1991H72.111ZM68.0696 15.7165C67.7023 16.1935 67.192 16.432 66.5388 16.432C65.8993 16.432 65.389 16.1935 65.008 15.7165C64.627 15.2258 64.4365 14.592 64.4365 13.8151C64.4365 13.0382 64.6202 12.4181 64.9876 11.9547C65.3686 11.4777 65.8857 11.2391 66.5388 11.2391C67.192 11.2391 67.7023 11.4777 68.0696 11.9547C68.437 12.4181 68.6207 13.0382 68.6207 13.8151C68.6207 14.592 68.437 15.2258 68.0696 15.7165ZM84.3797 8.56091V23.1991H80.8486V17.904C80.1002 18.7899 79.1137 19.2329 77.8891 19.2329C76.9774 19.2329 76.1542 19.0148 75.4194 18.5787C74.6982 18.1425 74.1335 17.5156 73.7253 16.6978C73.3171 15.88 73.113 14.9328 73.113 13.856C73.113 12.7929 73.3171 11.8525 73.7253 11.0347C74.1335 10.2033 74.6982 9.56269 75.4194 9.11291C76.1406 8.66313 76.9638 8.43825 77.8891 8.43825C79.1954 8.43825 80.2295 8.9221 80.9915 9.8898L81.2773 8.56091H84.3797ZM78.8076 16.432C79.4607 16.432 79.971 16.1935 80.3384 15.7165C80.7057 15.2258 80.8895 14.592 80.8895 13.8151C80.8895 13.0382 80.7057 12.4181 80.3384 11.9547C79.971 11.4777 79.4607 11.2391 78.8076 11.2391C78.1544 11.2391 77.6374 11.4777 77.2563 11.9547C76.889 12.4181 76.7053 13.0382 76.7053 13.8151C76.7053 14.592 76.8958 15.2258 77.2768 15.7165C77.6578 16.1935 78.168 16.432 78.8076 16.432ZM86.0553 10.9938C85.6062 11.8116 85.3817 12.7725 85.3817 13.8765C85.3817 14.9668 85.613 15.9141 86.0757 16.7182C86.5519 17.5224 87.2391 18.1425 88.1371 18.5787C89.0352 19.0148 90.1034 19.2329 91.3416 19.2329C92.2941 19.2329 93.131 19.0694 93.8521 18.7422C94.5869 18.4015 95.1652 17.9517 95.587 17.3929C96.0225 16.8205 96.2878 16.1935 96.383 15.512H92.9132C92.7091 16.2889 92.1036 16.6774 91.0967 16.6774C89.9129 16.6774 89.2325 16.0231 89.0556 14.7147V14.6738H96.4035C96.4715 14.3467 96.5055 13.9651 96.5055 13.5289C96.5055 12.5203 96.2674 11.6344 95.7911 10.8711C95.3149 10.0942 94.6481 9.49454 93.7909 9.07202C92.9473 8.6495 91.9675 8.43825 90.8518 8.43825C89.7632 8.43825 88.8039 8.66313 87.9739 9.11291C87.1574 9.54906 86.5179 10.176 86.0553 10.9938ZM92.3417 11.3618C92.6955 11.6208 92.92 12.0024 93.0153 12.5067H89.0964C89.1781 12.0024 89.3822 11.6208 89.7088 11.3618C90.0489 11.0892 90.4912 10.9529 91.0355 10.9529C91.5661 10.9529 92.0016 11.0892 92.3417 11.3618ZM98.1541 11.4845H96.5009V8.56091H98.1541V5.59647H101.685V8.56091H103.951V11.4845H101.685V15.2258C101.685 15.5665 101.76 15.8119 101.91 15.9618C102.059 16.1117 102.304 16.1867 102.644 16.1867H103.951V19.1102H101.318C100.311 19.1102 99.5285 18.8445 98.9706 18.3129C98.4263 17.7677 98.1541 16.9772 98.1541 15.9414V11.4845ZM108.134 5.59647H104.603V15.9414C104.603 16.9772 104.876 17.7677 105.42 18.3129C105.978 18.8445 106.76 19.1102 107.767 19.1102H110.4V16.1867H109.094C108.754 16.1867 108.509 16.1117 108.359 15.9618C108.209 15.8119 108.134 15.5665 108.134 15.2258V11.4845H110.4V8.56091H108.134V5.59647Z"
      fill="white"
    />
  </svg>
</button>

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.

let roqqett;

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

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:

1. Your transferID for this transaction.
2. A value indicating whether the transferId is safe to use.

Finally, forward your transferID to your backend endpoint which creates a cart. Our library handles the rest! (yes it's really that simple)

🚧

Transfer still 'fresh'?

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

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);
  }
}

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 (info / link) earlier.

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

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

For more information on this payment journey, see here.

Once payment is confirmed our backend will send you the Cart Complete webhook. We include the following body values:

1. cartId - The ID of the cart created.
2. merchantCartId - The ID of the cart in the merchant's records or domain.
3. paymentId - The unique ID of the payment record in our system.
4. 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.
NB: A merchant, at any one time, can have multiple live checkouts, each with their own return URL. You can configure a checkout's return URL on the checkouts page in the Roqqett portal (info / link).

📘

Placing orders

You should only record the order once you have received the Cart Complete 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.

If the cart is cancelled, our backend will send you the Cart Cancelled webhook. We include the following query parameters:

1. cartId - The ID of the cart created.
2. merchantCartId - The ID of the cart in the merchant's 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 merchant page that will be unlocked. The end user can then retry payment with Roqqett or another payment method.

If the customer simply abandons the payment, our backend, after a fixed amount of time, will send you the Cart Abandoned webhook. We include the following query parameters:

1. cartId - The ID of the cart created.
2. merchantCartId - The ID of the cart in the merchant's records or domain.

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.