3 min read

Set up Apple Pay for web checkout transfer

When a customer wants to use Apple Pay in your Poq app, the transaction needs to be authorised using Apple Pay’s native security process - your customer uses either their finger print or the security code for their device to authorise the payment.

For security reasons, Apple does not provide Apple Pay methods to web views in iOS, which means this process cannot be completed on the web checkout in your Poq app.

To resolve this, you can use JavaScript to communicate the authorisation process between the web checkout page and the Poq app on the customer’s device.

The customer’s journey, and the background process looks like this:

  1. The customer goes to the checkout in your app to pay for their shopping - which launches the web checkout page.

    • This triggers an Apple Pay button to be embedded in your web checkout page.
  2. The customer taps the Apple Pay button.

    • Your web checkout page calls your Poq app, requesting that the Apple Pay authorisation process is started on your customer’s device.
  3. The customer authorises the Apple Pay transaction in the usual way.

    • Your Poq app sends the relevant part of an Apple Pay token to your web checkout.
    • Your web checkout page can then pass this data to your Payment Service Provider, completing the payment.
  4. The customer’s journey through the web checkout is completed as normal.

Apple Pay is meant to be used purely as a payment method. As a result, additional fields such as Shipping and Delivery details don't appear at the time of payment when Apple Pay's popup is displayed. Therefore, Apple Pay will not handle any shipping methods or delivery addresses. The website should handle them before the Apple Pay Sheet is presented. In this way, Apple Pay Sheet will only present the total price at the end.

There is no need to use Apple Pay Sessions or any of the current logic that you have in your website for Apple Pay. The **Poq web checkout JS** will take care of checking if the user device is capable of Apple Pay payments and whether or not to show the Apple Pay button.

What you need to do

To enable Apple Pay on a web checkout page:

  1. Add the Poq web checkout JS snippet to your web checkout page. This enables communication between your web checkout and the Poq app on your customer’s device. This also adds a listener in your web checkout for when the Apple Pay payment has been authorised.
  2. Create a container element where the Apple Pay button will be embedded when Apple Pay is available.
  3. Ensure that your web checkout page updates the order total, so that when the customer selects their payment methods, the total to pay is correct.
  4. Listen for the applepayauthorized event to allow you to complete the payment process.
  5. Complete the transaction.

Add the Poq web checkout JS snippet to your web checkout page

The Poq web checkout JS code allows the communication of checkout events between your web checkout page and your Poq app.

If you have not yet integrated Poq web checkout JS into your website’s checkout pages, add the following script before the </body> tag:

(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"))

Add the Apple Pay button to your web checkout page

When tapped by your customer, the Apple Pay button on your web checkout page triggers a call to your Poq app to begin the authorisation process.

To add the Apple Pay button:

  1. Use this code to insert the Apple Pay button container where you want it on your web checkout page:

<div class="poq-apple-pay-container">
<!-- A Poq Apple Pay button will be automatically inserted here. -->

  1. Add CSS rules to style the Apple Pay button so it appears correctly to your customers. Check Apple’s Developer Documentation for more on displaying Apple Buttons.

Enable debug mode to see the injected Apple Pay button within the container.

Ensure that your web checkout page updates the order

To make sure that the user gets charged the right amount when the Apple Pay process is started, your web checkout must update the order as the customer makes changes. For example, if the customer removes an item or changes their delivery method.

To update the order, within your Javascript, include the following:

total is required, other fields are optional. See Order schema in Technical docs.

PoqWebCheckout.send('order', {
total : 13.00,
orderId : '0776620100',
subTotal : 10.00,
delivery : 5.00,
discount : 2.00,
currency: 'GBP'

Listen for the applepayauthorized event

Once the user has authorised the payment on the Apple Pay modal, the bridge will receive the applepayauthorized event which returns paymentData. You can listen for this event and complete the order with your payment service provider when your callback function is called.

PoqWebCheckout.on('applepayauthorized', paymentData => {
// Outputs:
// {
// version: "EC_v1" or "RSA_v1", // Version information about the payment token
// data: "xxxxx", // Encrypted payment data
// signature: "xxxxx", // Signature of the payment and header data
// header: {} // Additional information to decrypt and verify the payment
// }
// TODO: Complete your checkout with the paymentData property.

You will not receive any delivery or shipping information in the paymentData object. You will only receive payment data, an example paymentData object can be viewed at paymentData.json.

To complete the transaction with your payment service provider, pass the paymentData variable to their SDK.

Complete the transaction

Once the user has completed their transaction, tell your Poq app that the user has successfully placed an order. The payload must contain the final order object. Also, if your checkout supports non-apple pay transactions(e.g. credit card payment) too, you also have to do this.

You should include as many of the appropriate fields as possible at this stage of the checkout flow.

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

Debug Apple Pay buttons

If you want to test that you have implemented the process correctly,

In debug mode, it is possible to force Apple Pay buttons to display on Safari Web (They will appear in other browsers but Apple Pay CSS properties will not be available).

PoqWebCheckout.options({ debug: true, applePayEnabled: true });

Sending applePayEnabled: true replicates the option that iOS sends to the bridge to notify it that Apple Pay is enabled. Alongside debug: true, it will mock the process of talking to your Poq app and you will see a success message in the console after clicking a linked Apple Pay button.

[PoqWebCheckout] Payment process completed successfully!