Apple Pay – Web

Apple Pay offers a secure and smooth payment experience, which can be utilized in apps, physical stores, and online. It employs network tokenization and securely stores payment details on the user’s eligible Apple device, with payments confirmed via Touch ID or Face ID.

Thanks to this documentation you will be able to start accepting Apple Pay payments on your website.

Integration Process

Prerequisites

Devices

To use Apple Pay on your devices, you need to pay attention to several things:

    • The device must be on iOS 11 and later or macOS 10.13 and later.

    • Your environment must be HTTPS protocol (if you want to test in development mode, use https://ngrok.com/).

    • Your device must have a wallet with at least one card configured.

Note

If you want to test Apple Pay in your staging environment, you need to be logged into a test Apple account and have test cards configured.

HiPay enablement

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

Apple Pay certificates

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.

Default certificates

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 – Whitlist IPs

Allow these Apple IP Addresses.

3 – Communicate

Communicate to your Technical Account Manager once this is done.

Custom certificates

Step 1: Create the Merchant ID and Validate Your Domain

This first step involves creating your unique merchant identifier with Apple and then proving that you own the website where Apple Pay will be offered.

1.1 – Create the Merchant ID

To accept Apple Pay, you must first register a unique identifier, called a Merchant ID, for each website or app where you offer this payment method.

    1. Log in to your Apple Developer account.

    2. Navigate to the Certificates, Identifiers & Profiles section, then click on Identifiers.

    3. Next to the “Identifiers” title, click the + button.

    4. Select Merchant IDs from the list and click Continue.

    5. Fill in the Description and Identifier fields:

      • Description: An internal name for you to easily recognize it (e.g., “HiPay Production Store”).

      • Identifier: This ID must be globally unique. The standard convention is to use a reverse-domain name style, for example: merchant.com.hipay.{sitename}.

    6. Once created, your Merchant ID will appear in your list of identifiers.

Best Practice

We strongly recommend creating two separate Merchant IDs:

    • One for your production environment.
    • One for your staging/testing environment.This ensures a secure and complete separation between your tests and live transactions.
1.2 – Add and Validate Your Domain

To use Apple Pay on your website, Apple requires you to prove you control each domain where the payment button will be displayed.

    1. In your list of Identifiers, click on the Merchant ID you just created.

    2. Scroll down to the “Merchant Domain Validation” section and click “Add Domain”.

    3. Enter the fully qualified domain name of your site (e.g., www.your-store.com).

    4. Click “Download” to get the verification file. The filename is apple-developer-merchantid-domain-association.

    5. Host this file on your server at the exact location required by Apple. It must be publicly accessible at the following URL: https://YOUR-DOMAIN.com/.well-known/apple-developer-merchantid-domain-association

    6. Once the file is in place, return to the Apple Developer portal and click the “Verify” button.

    7. A “Verified” status should now appear next to your domain name.

Step 2: Generate Apple Pay certificates

Two types of certificates are required to secure transactions. They are linked to your Merchant ID and must be renewed periodically.

Information

To ensure uninterrupted Apple Pay service, it is critical to renew your certificates before they expire. Please note that the two types of certificates have different validity periods:

    • Payment Processing Certificate: This certificate, used by HiPay to decrypt payment data, is valid for 25 months.

    • Merchant Identity Certificate: This certificate, used by HiPay to authenticate your sessions with Apple, has a shorter lifespan and must be renewed every 12 months.

We strongly advise you to proactively contact your Technical Account Manager (TAM) at least one month before an upcoming expiration to coordinate a smooth renewal process and prevent any service disruption.

A. Payment processing certificate

This certificate is used by HiPay to decrypt the payment data sent by Apple. Without it, we cannot process the transaction.

Creation Processe to the Certificates, Identifiers & Profil

    1. Log in to your Apple Developer account and go to Certificates, Identifiers & Profiles.

    2. In the left-hand menu, click Certificates, then click the + button.

    3. Under the “Services” section, select Apple Pay Payment Processing Certificate and click Continue.

    4. From the drop-down menu, select the Merchant ID you created in Step 1, then click Continue.

    5. Read the following instructions to create a CSR file.

    6. Save the CSR on your disk and continue.

    7. Click Choose File on the Apple Developer portal to upload it.

    8. Click Continue.

    9. The next page allows you to download your certificate. Click Download. You will receive a file named apple_pay.cer.

    10. You must provide this .cer file to HiPay through your back-office or the channel specified by your TAM (Technical Account Manager).

B. Merchant identity certificate

This certificate is used to authenticate your website session with Apple’s servers. It proves that a payment session initiated from your domain is legitimate. It is used for direct communication between your server and Apple’s APIs, particularly for merchant validation.

Creation Process:

    1. Log in to your Apple Developer account and go to Certificates, Identifiers & Profiles.

    2. In the left-hand menu, click Certificates, then click the + button.

    3. This time, under the “Services” section, select Apple Pay Merchant Identity Certificate and click Continue.

    4. Select the same Merchant ID as before and click Continue.

    5. Read the following instructions to create a CSR file.

    6. Save the CSR on your disk and continue.

    7. Upload this .csr file to the Apple Developer portal.

    8. Click Continue, then Download to get the certificate (.cer file).

    9. Double-click the downloaded .cer file. It will automatically be added to your Keychain Access and paired with the private key you created when generating the CSR.

Step 3: Exporting and securely transmitting the certificates

For our platform to process Apple Pay payments on your behalf, HiPay requires both certificates you created. Our system will use these credentials to authenticate transaction sessions and securely decrypt payment data.

You will need to provide us with two separate files.

This certificate, which includes your private key, is required for our servers to authenticate each transaction with Apple on your behalf. You must send it to us in the .p12 format.

Export Procedure (from macOS):

    1. Launch the Keychain Access application on your Mac.

    2. In the “My Certificates” category, find the Apple Pay Payment Processing Certificate and Apple Pay Merchant Identity Certificate you created. It should have a private key nested underneath it (indicated by a small key icon).

    3. Click the arrow to expand the certificate and view the private key.

    4. Select both the certificate and the private key line items. (Hold the Command ⌘ key to select both).

    5. Right-click on the selected items and choose “Export 2 items…”.

    6. A save dialog will appear. Choose the Personal Information Exchange (.p12) file format.

    7. Give the file a name and choose a location to save it.

    8. You will be prompted to create a strong password to protect the file. You must take note of this password, as it will need to be securely shared with HiPay via email : [email protected]

SDK setup

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="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.

This instance will allow us to specify all the options and customizations related to Apple Pay and its button.

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

To determine where to place the Apple Pay button, the SDK needs to know in which div to instantiate the button.

So first, add in your payment web page, a new div container where the Apple Pay button will be displayed. Make sure that the selector div is empty. And ensure that your div has a clear ID, as we will need this ID later.

<body>
    <div id="apple-pay-button"></div>
</body>
Now, we need to inform the SDK that we want to instantiate an Apple Pay button. To do this, you have to call the create function with the first argument paymentRequestButton and a second one with the configuration of your Apple Pay button.
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 instanceApplePayButton = hipay.create(
  'paymentRequestButton',
  options
);
Note
The order in which you place your networks in “supportedNetwork” parameter will determine which network will be used by default in the case of a cobranded board.

Note that, instanceApplePayButton 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.

Below is a basic example. However, you are free to handle this case as you wish.

if (instanceApplePayButton) {
       // 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.

hipay.canMakePaymentsWithActiveCard('your-merchant-identifier')
 .then(function(canMakePayments) {
   if (canMakePayments) {
     var instanceApplePayButton = hipay.create('paymentRequestButton', applePayConfig);
     if (instanceApplePayButton) {
       // Display the Apple Pay button
     } else {
       // Hide Apple Pay button
     }
   }
   else {
     // Hide Apple Pay button
   }
 });

At the end of this step, you should see the Apple Pay button appear. However, be aware that you cannot make a payment yet.

If you don’t see the Apple Pay button, please check the troubleshooting part.

Payment

Explanations

To ensure HiPay has the necessary information to manage the transaction, there are several steps. Some of these steps are invisible to you but help you understand what is happening behind the scenes.

1 – Upon clicking the Apple Pay button, the Apple Pay official payment sheet appears and prompts you to authenticate using FaceID, TouchID, or your password. You can then authenticate, which will initiate the payment process. During this step, in the background, we have sent the payment information such as the amount and currency to Apple. In return, we receive an Apple Pay Token that contains everything we need. This step is invisible to you.

2 – Using your public credentials and the Apple Pay token received just before, we will generate a HiPay token, which will then be used to create the final order of the transaction within HiPay. To decrypt the Apple Pay token, we use the well-known Apple certificates. If an error occurs during steps 1 or 2, the payment will fail.

3 – Once the HiPay token is received, you can manage the creation of the order within your backend using the HiPay PHP SDK or NodeJS SDK.

Handle payment processes

To receive a HiPay token, you need to integrate several events: a success event (paymentAuthorized), a failure event (paymentUnauthorized), and a cancellation event (cancel).

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

    • The paymentAuthorized event is triggered when the entire process has completed successfully. You will then receive the HiPay token that you should pass to your backend server.

    • The paymentUnauthorized event is triggered when a problem occurs during the process.

    • The cancel event is triggered when the user closes the Apple Pay payment window.

To send a feedback message to the user, you need to complete the payment based on the status of the payment process. Calling completePaymentWithSuccess() will display a success message on the Apple Pay popup. Calling completePaymentWithFailure() will display a failure message on the Apple Pay popup. Therefore, you should call one or the other depending on what happens during the payment. Ensure that you call completePaymentWithSuccess() only if the creation of the order on the backend has been successful.

completePaymentWithSuccess()

completePaymentWithFailure()

You can find a basic example below

if (instanceApplePayButton) {
        instanceApplePayButton.on('paymentAuthorized', function (hipayToken) {
          // Call your backend method to create the order.
          // Here, handlePayment() is just an example method.
          handlePayment(hipayToken)
            .then(function (response) {
                // Order processed with success
                // Handle response here
                // and complete the payment with success state
                instanceApplePayButton.completePaymentWithSuccess();
            })
            .catch(function (error) {
              // Error during order creation
              // Handle error here
              // and complete the payment with failure state
              instanceApplePayButton.completePaymentWithFailure();
            });
        });

        instanceApplePayButton.on('cancel', function () {
                // The user has cancelled its payment
                // Handle this case here
                // and complete the payment with failure state
                instanceApplePayButton.completePaymentWithFailure();
        });

       instanceApplePayButton.on('paymentUnauthorized', function(error) {
                // The payment is not authorized (Token creation has failed, domain validation has failed...)
                // Handle error here
                // and complete the payment with failure state
                instanceApplePayButton.completePaymentWithFailure();
       });
}

Once the events are created, make sure to retrieve the HiPay token. If that’s the case, then you have completed the front-end integration. 

To find out how to handle the payment on the backend, you can refer to one of these documentations:

JS SDK Reference

Create

Create a hostedfield instance for Apple Pay.

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

Update

Update Apple Pay instance options.

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

options.request.total.amount = "10.09" // New amount

instance.update(options)

Options

NameTypeDescription

request

required

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.

request

A request includes all information about the current payment.

NameTypeDescription

total

required

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

countryCode

required

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

currencyCode

required

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, cartesBancaires, amex or maestro

total 

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

NameTypeDescription

label

required

stringProvide a business name (must be non-empty)

amount

required

stringIt must be greater than or equal to zero
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) 
applePayStyle = {
     type: 'buy',
     color: 'white-with-line'
};

EVENTS

instance.on(‘event’, callback)


Name


Description


Response

paymentAuthorized

Only for paymentRequestButton type. Emitted when the user has validated the payment with Apple Pay.

hipayToken : object

It will return the same object structure as the function getPaymentData.

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

It is highly recommended to test your integration in your test environment before deploying to production. This will help limit potential issues during the production deployment.

HiPay Staging Account

You can use the main HiPay 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.

Troubleshooting

“I don’t see the Apple Pay button on my checkout page.“

If you do not see the Apple Pay button, it means there is an issue with the “SETUP” part of your integration.

    • Verify that you are in an environment that supports Apple Pay. Make sure you are on an Apple device (macOS or iOS) and that you are using the Safari browser. Also, make sure you are using HTTPS protocol.

    • Make sure your Apple device is connected to an Apple account with a configured payment card. If you are in a test environment, you must use a test Apple account with a test payment card. You can get one Apple test account by following this documentation.

    • Make sure you have validated your domain.

    • Ensure that you have provided all the necessary parameters for the creation of the HiPay instance.

    • Check if the ID of your div matches the one specified in the “selector” parameter.

“The Apple Pay popup appears but fails immediately before authentication is possible“

“After authentication, the payment fails and paymentUnauthorized is called.“

In this case, you must have an issue in the token retrieval process.

    • Verify your HiPay public credentials and ensure they match your environment (stage or production).

    • If you manage your own certificates, a verification of the password and the certificates themselves may be necessary.

    • Ensure that you properly call the methods completePaymentWithSuccess() or completePaymentWithFailed() in your events. If your back-end is not ready to finalize the payment yet, try logging the HiPay token. If you have a HiPay token, everything is fine.