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.
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.
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.
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.
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 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
paymentAuthorizedevent 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
paymentUnauthorizedevent is triggered when a problem occurs during the process.The
cancelevent 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
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 |
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. ( |
color required | string | A type that indicates the available appearances for an Apple Pay Button ( |
applePayStyle = {
type: 'buy',
color: 'white-with-line'
};EVENTS
instance.on(‘event’, callback)
|
|
|
| Only for paymentRequestButton type. Emitted when the user has validated the payment with Apple Pay. | hipayToken : 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
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“
Make sure you have validated your domain.
“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()orcompletePaymentWithFailed()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.