Apple Pay - Web - Developer

Apple Pay gives a secure and easy way to pay within apps and websites. Thanks to this documentation you will be able to start accepting Apple Pay payments on your website.

Integration Process

The integration process has 3 steps:

HIPAY ENABLEMENT

Apple Pay is on a supervised rollout phase, and you will need to request your Account Manager to enable it.

APPLE PAY CERTIFICATE

To accept Apple Pay on your website you need to have a certificate. As partner of Apple, we have a Payment Service Provider Certificate, that will simplify your integration. The table below shows you when you can use our certificate.

Integration	HiPay Certificate	Your own Certificate
Web Only	✅	✅
App Only		✅
App & Web		✅

If you want to use HiPay’s certificate please, check the domain validation step, if you want to use yours, please follow this documentation.

TECHNICAL INTEGRATION

The last phase is the technical integration. To test your integration please follow these steps.

Prerequisites

- - iOS 11 and later or macOS 10.13 and later
  - HTTPS (if you want to test in development mode, use https://ngrok.com/)
  - An activated card in your Wallet

Domain Validation

When you have chosen to use HiPay Certificate, the only thing that you will need to do is to:

1 – HOST THE FILE

Download this file and host it at /.well-known/apple-developer-merchantid-domain-association on your site.

For example, if you’re validating https://test.com, make that file available at https://test.com/.well-known/apple-developer-merchantid-domain-association.

2 – WHITELIST IPs

Allow these Apple IP Addresses.

3 – COMMUNICATE

Communicate to your Technical Account Manager once this is done.

If you use your own certificate and you want to integrate Apple Pay Web, you will need to do the domain validation following this documentation.

HiPay JS SDK

To get started, include the HiPay JavaScript SDK on your HTML page.

The following link exposes a global variable, HiPay, as a function to initialize the SDK with your public credentials and your configuration.

HTML

<script type="text/javascript" src="https://libs.hipay.com/js/sdkjs.js"></script>

Then, create an instance of the HiPay JavaScript SDK. You must replace HIPAY-PUBLIC-USERNAME and HIPAY-PUBLIC-PASSWORD with the public credentials of your main HiPay Account.

JavaScript

var hipay = HiPay({
    username: 'HIPAY-PUBLIC-USERNAME',
    password: 'HIPAY-PUBLIC-PASSWORD',
    environment: 'stage',
    lang: 'en'
});

Add in your payment web page, a new container where the Apple Pay button will be displayed.

HTML

<body>
    <div id="apple-pay-button"></div>
</body>

Apple Pay Button

To create this button, call the create function with the first argument paymentRequestButton and a second one with the configuration of your Apple Pay button.

Note: All parameters below in applePayConfig are required.

JavaScript

// Configuration
const total = {
  label: 'Total',
  amount: '222.50'
};

const request = {
  countryCode: 'FR',
  currencyCode: 'EUR',
  total: total,
  supportedNetworks: ['visa', 'masterCard']
};

const applePayStyle = {
  type: 'plain',
  color: 'black'
};

const options = {
  displayName: 'YOUR COMPANY NAME',
  request: request,
  applePayStyle: applePayStyle,
  selector: 'apple-pay-button'
};

var intanceApplePayButton = hipay.create(
  'paymentRequestButton',
  options
);

intanceApplePayButton can be null if you display the page on an incompatible browser (e.g. Firefox, Chrome, Brave, Edge), so you should check the existence of the instance.

JavaScript

if (intanceApplePayButton) {
       // The Apple Pay button is displayed
} else {
      // Hide Apple Pay button
     document.getElementById('apple-pay-button').style.display = 'none';
}

OPTIONAL

If you want to display the Apple Pay button only if a user has an active card provisioned into Wallet, you should use the canMakePaymentsWithActiveCard function with your own merchant identifier or the one created by HiPay. This function returns a boolean to check if the user has an active card.

JavaScript

hipay.canMakePaymentsWithActiveCard('your-merchant-identifier')
 .then(function(canMakePayments) {
   if (canMakePayments) {
     var intanceApplePayButton = hipay.create('paymentRequestButton', applePayConfig);
     if (intanceApplePayButton) {
       // Apple Pay button displayed
     } else {
       // Hide Apple Pay button
       document.getElementById('apple-pay-button').style.display = 'none';
     }
   }
   else {
     // Hide Apple Pay button
     document.getElementById('apple-pay-button').style.display = 'none';
   }
 });

Payment

When the user clicks on the Apple Pay Button, the Apple Pay official payment sheet will be displayed on Safari. The user will be asked to validate the payment with Touch ID or Face ID.

Once the authentication is done an event called paymentAuthorized is emitted. This function sends you an hipayToken, that you should pass to your backend server (e.g the handlePayment function in the example). Once the server has received the hipayToken, it should call the ORDER API to create a transaction.

The ORDER API response will be used to dismiss the payment sheet and display to your user the payment status. To do so, you have to call the function completePaymentWithSuccess() if the payment succeeds or completePaymentWithFailure() in any other case. These functions are only available for the paymentAuthorized event.

JavaScript

if (intanceApplePayButton) {
 intanceApplePayButton.on('paymentAuthorized', function(hipayToken) {
   handlePayment(hipayToken)
     .then(function(response) {
             // Order processed
             // Handle response
             intanceApplePayButton.completePaymentWithSuccess();
     })
     .catch(function(error) {
             // Handle error
             intanceApplePayButton.completePaymentWithFailure();
     });
 });

You can handle two more events. A cancel event is emitted when the payment sheet is cancelled by the user. A paymentUnauthorized event is emitted if the creation process of an Apple Pay token has failed or the failure of the domain validation.

JavaScript

if (intanceApplePayButton) {
      intanceApplePayButton.on('paymentAuthorized', function(hipayToken) {
         // Handle the HiPay Token
       });
 
       intanceApplePayButton.on('cancel', function() {
         // The user has cancelled its payment
       }
 
       intanceApplePayButton.on('paymentUnauthorized', function(error) {
         // The payment is not authorized (Token creation has failed, domain validation has failed...)
       });
}

JS SDK Reference

CREATE

JavaScript

var instance = hipay.create('paymentRequestButton', options);

options

Name	Type	Description
request required	object	A request which includes information about the payment.
applePayStyle	object	The Apple Pay button can have multiple appearances (buy, subscribe, donate…) See the ApplePayStyle section below for more details.
displayName	string	A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display.
selector	string	Unique div id to generate the button.

request

A request includes all information about the current payment.

Name	Type	Description
total required	object	An object which includes the amount and its associated description. See the Item section below for more details.
countryCode required	string	The merchant’s two-letter ISO 3166 country code.
currencyCode required	string	The three-letter ISO 4217 currency code for the payment.
supportedNetworks	array	This property must be set to one more of the payment network values : visa, masterCard

total

This object contains the amount and a description displayed in the Apple Pay payment sheet.

Name

Type

Description

label

required

string

Provide a business name (must be non-empty)

amount
required

string

It must be greater than or equal to zero

JavaScript

total = {
     label: 'Your Company',
     amount: '9.50'
};

applePayStyle

This configuration customizes the Apple Pay button appearance which includes a type and a color. Each type of button works with the predefined list of colors. The language used by the button is the same as the lang parameter in the HiPay instance.

Name	Type	Description
type required	string	The kind of Apple Pay button, such as a button for purchasing a subscription. (`buy`, `donate`, `subscribe`, `tip` and more)
color required	string	A type that indicates the available appearances for an Apple Pay Button (`black`, `white`, `white-outline`)

JavaScript

applePayStyle = {
     type: 'buy',
     color: 'white-with-line'
};

EVENTS

JavaScript

instance.on(‘event’, callback)

paymentAuthorized

Only for paymentRequestButton type. Emitted when the user has validated the payment with Apple Pay. Response: hipayToken as string.

paymentUnauthorized

Only for paymentRequestButton type. Emitted when an error occured after that the user clicked on the Apple Pay Button.

cancel

Only for paymentRequestButton type. Emitted when the user clicks on the cancel button of the Apple Pay payment sheet.

Testing your integration

We recommend you to test the integration before deploying it to production. In order to do you will need:

HiPay Staging Account

You can use the main account to test Apple Pay, even if we recommend you to use a specific one for Apple Pay, to replicate what you will be doing in production.

Apple Pay Testing Card

You will need to have an Apple sandbox tester account, in order to add testing cards. You can get one following this documentation.

Domain Validation

Make sure that you have validated the URLs that you want to use for testing.