Enable payments on your app via web checkout

In order to allow customers to pay for their shopping, you can connect your Poq app to your web payment screens. Your customer still experiences the checkout screens on their app, but payment is actually taken via your website.

Use this document to add the required code to your web payment pages to make checkout work on your app.

How it works

Web checkout on your app is enabled by the Poq web checkout JS. This is a Javascript library that, when added to your web-based checkout, opens up communication between your web page and the Poq app on your customer’s device.

Once integrated, your web checkout pages can listen for events from your app and send messages to your Poq app. It can be triggered whenever a customer taps ‘checkout’ on your app, and subsequent events in the checkout process:

The bridge allows data about your customer’s order to flow seamlessly and securely between the payment screens of your website and your app.

You use the Javascript bridge by adding a small snippet of Javascript into each web page that communicates with the app in the checkout process.

Requirements

  • A javascript snippet needs to be added to your web checkout pages.
  • Your checkout pages should support mobile screen sizes.
  • The web checkout pages should not display a header with your brand logo or navigation to other parts of your website. This is handled on your behalf, with a navigation bar that supports closing the web view and returning to the native screens at any point the user decides.
  • You should include a button to return to the native screens in your app, once they have checked out.

Integrate the Poq Web Checkout Javascript in your website

Add the following script before the </body> tag on your website’s checkout pages:

<script>
  (function(p,o,q,w,e,b){var g=p.PoqWebCheckout={q:[]};[b,"send","on","destroy"].forEach(function(a){g[a]=function(){g.q.push([a,arguments])},g[b]=function(a){a.debug&&h("",""),g.q.push([b,[a]])}});var h=function(a,d){var c=o.createElement(q);q=o.getElementsByTagName(q)[0],c.src=["https://assets.poq.io/web-checkout",a,"min.js"].filter(function(a){return!!a}).join("."),c.async=1,c.crossOrigin="anonymous",d&&(c.integrity=d),q.parentNode.insertBefore(c,q)};p[w]={postMessage:function(a,f){"bridgesettings"===a&&(f=JSON.parse(f),g.q.push([b,[f]]),h(f.version,f.integrity))}},p.webkit?p.webkit.messageHandlers[w].postMessage(e):p.android&&p.android.postMessage(e)}(window,document,"script","poqWebCheckout","{\"name\":\"ping\"}","options"))
</script>
Warning

The snippet must be load only once per page and placed before any calls to PoqWebCheckout.

When the checkout has been completed and the order has been placed, send the order to your Poq app. Make sure that this call is made only after all other possible updates to the order have taken place:

Note

total is required, other fields are optional. See Order schema in Technical docs. The fields total, subTotal, delivery and discount should be a number and orderId should be a string.

PoqWebCheckout.send('paymentcompleted', {
  order: {
    total: 13.0,
    orderId: '0776620100',
    subTotal: 10.0,
    delivery: 5.0,
    discount: 2.0,
    currency: 'GBP'
  }
});

Identify requests from your Poq app

To ensure your web checkout page opens and displays correctly, you should identify requests from your Poq app and run logic to remove the header and other navigation elements from your web checkout pages.

A product identifier is added to the User Agent header in the following format:

{App Name}-{Environment}/{App Version}

So the full User Agent header for the app PoqDemoApp-UAT/2.3 would look like:

Mozilla/5.0 (iPhone; CPU iPhone OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) PoqDemoApp-UAT/2.3

In Javascript, you can detect if the page has been opened by your Poq app with the following test:

window.addEventListener('DOMContentLoaded', () => {
  if (navigator.userAgent.indexOf('PoqDemoApp') > -1) {
    // Hide header
  }
});

Create a continue shopping button

Add a button allowing your customer to return to the native screens in your app, once they have checked out.

When the user wants to continue shopping, close the WebView by sending the closewebview event to your app.

PoqWebCheckout.send('closewebview');

Use Debugging mode

If you want to test that you have implemented the process correctly whilst developing, set debug to true in options to check if you have integrated the Javascript correctly. In debug mode, events and information will be logged to the console, so make sure to remove the option in production!

Poq will provide you with a build of your iOS App that you can debug in Safari before you start implementing these changes. Once you have the build and you are making the necessary changes to your website, you can test them by enabling debug mode and checking the console in the Safari developer tool. Please make sure that your device is connected to your computer. For more information you can familiarise yourself with the Safari developer tools.

PoqWebCheckout.options({ debug: true });