API Reference
API Reference

ApplePay Client Integration

Apple Pay PXP integration script - Merchants

This README demonstrates the simple integration of Apple Pay API using the PXP ANYpay gateway.

Note: This document is subject to significant change in the coming days.

Table of Contents

Getting Started

Here are the instructions for integration of Apple Pay payments API.
As a merchant, to customize the code for your specific use case, you will need to update the following:

  1. Add a div element to your HTML file with the ID "apple-pay-container". This will serve as the placeholder for the Apple Pay button on your website.
  2. In your HTML file, call the "runApplePay" function with the appropriate parameters to initiate the Apple Pay payment process
  3. It's essential to ensure that your website is served over HTTPS, as Apple Pay requires a secure connection for the payment process to work. Ensure that your site is using a valid SSL/TLS certificate and HTTPS protocol.
  4. Check the Apple Pay documentation to verify that your device is compatible with Apple Pay requirements. Ensure that the device is running iOS 10 or later, macOS Sierra or later, or watchOS 3 or later.
  5. For the best user experience, ensure that your website is open in Safari browser, as Apple Pay is only available on Safari on macOS and iOS.

1. Import the PXP JS script

This section contains the information for you, the merchant, regarding where you can obtain the PXP script for the Apple Pay button integration.

To import the script, you should navigate to the publicly-available CDN(Content Delivery Network) at the following URL: https://example-pxp-instructions-for-merchants.com.

You should import this script in the head of your checkout page.

Please note, to avoid the browser caching, and to ensure the latest version of the .js file is used, we recommend adding 'v' url parameter as shown below.

For example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Merchant's Checkout Page</title>
    <script src="./apple-pay.js?v=" + Date.now()"></script>
  </head>
  ...
</html>

2. Create the div to render the Apple Pay button

Add an HTML element to your checkout page, with the id HTML attribute set to pxp-apple-pay-container. For example:

<div id="pxp-apple-pay-container"></div>

This will serve as the placeholder for the Apple Pay button on your website.

3. Call the runApplePay function

In this section, you will learn how to use the PXP apple-pay.js script. Essentially, the PXP apple-pay.js script requires you
to to invoke the runApplePay() function, and pass to it a number of
arguments:

  • mid
  • sid
  • clientSystemTransactionId
  • base64token
  • domainName
  • currencyCode
  • amount

Here is an example on how to invoke the runApplePay() function with some parameters:

<script>
  runApplePay(
    "123456789", // mid
    "987654321", // sid
    "111222333", // clientSystemTransactionId
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", // base64token
    "example.com", // domainName
    "amount": "1.99",
    "GBP" // currencyCode
  );
</script>

For a live demo of how this is done, please navigate to the https://pxp-live-demo-???.com.

3.1 Parameters to pass to the runApplePay call

1. mid

Merchant ID issued by PXP. It is a string used to identify the merchant in the PXP system. This is a required parameter.

2. sid

Store ID issued by PXP. It is a string similar to merchant but it is a subdivision on the merchant side, in case that the merchant has multiple labels. This is a required parameter.

3. clientSystemTransactionId

This is the merchant transaction id and created by merchant. It can be used for query and other operations. This is a required parameter.

4. base64token

Token issued by PXP. This is a required parameter.

5. domainName

The domain name for the payment. This is a required parameter.

6. currencyCode

The currency code for the payment. This is a required parameter.

7. amount

The amount for the payment. This is a required parameter.

4. Successful payment processing

What happens after the runApplePay() call is successfully processed?

Upon successful call to runApplePay() function, the script returns the data received from the PXP payment processing backend servers, and gives the chance to the merchant to further work with the data received.

5. Failed payment processing

What happens when the call to the runApplePay() function returns an error?

Upon a failed call to the runApplePay() function - that is, upon the script returning an error in processing the payment - the error data will be sent to the merchant from the PXP payment processing backend servers. This should allow the merchant to further work with the errors received.