
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.
<script type="text/javascript" src="https://libs.hipay.com/js/sdkjs.js"></script>
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.
<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.
// 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.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.
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.
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();
});
});
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
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. (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)
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.