Apple Pay – Web

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:


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


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.

IntegrationHiPay CertificateYour 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.


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


      • iOS 11 and later or macOS 10.13 and later

      • HTTPS (if you want to test in development mode, use

      • 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:


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

For example, if you’re validating, make that file available at


Allow these Apple IP Addresses.


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.


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.

<script type="text/javascript" src=""></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.
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.

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

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.

// 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(
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.
if (intanceApplePayButton) {
       // The Apple Pay button is displayed
} else {
      // Hide Apple Pay button
     document.getElementById('apple-pay-button').style.display = 'none';


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.

 .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';


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.

if (intanceApplePayButton) {
 intanceApplePayButton.on('paymentAuthorized', function(hipayToken) {
     .then(function(response) {
             // Order processed
             // Handle response
     .catch(function(error) {
             // Handle error
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.
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


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





objectA request which includes information about the payment.
applePayStyleobjectThe Apple Pay button can have multiple appearances (buy, subscribe, donate…) See the ApplePayStyle section below for more details.
displayNamestringA string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display.
selectorstringUnique div id to generate the button.


A request includes all information about the current payment.

objectAn object which includes the amount and its associated description. See the Item section below for more details.



stringThe merchant’s two-letter ISO 3166 country code.



stringThe three-letter ISO 4217 currency code for the payment.
supportedNetworksarrayThis property must be set to one more of the payment network values : visa, masterCard


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




stringProvide a business name (must be non-empty)
stringIt must be greater than or equal to zero
total = {
     label: 'Your Company',
     amount: '9.50'


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.



stringThe kind of Apple Pay button, such as a button for purchasing a subscription. (buy, donate, subscribe, tip and more)


stringA type that indicates the available appearances for an Apple Pay Button (black, white, white-outline)
applePayStyle = {
     type: 'buy',
     color: 'white-with-line'


instance.on(‘event’, callback)


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


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


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.