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:

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.

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.

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. Download the file called “apple-app-site-association” received from HiPay by email.

      2. Insert the downloaded file in your website at this address https://your-domain.com/.well-known/apple-developer-merchantid-domain-association and make it public.

      3. Allow these Apple IP Addresses.

      4. 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>
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.

<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 completePaymentAuthorizedSuccess() if the payment succeeds or completePaymentAuthorizedFailure() 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.completePaymentAuthorizedSuccess();
     })
     .catch(function(error) {
             // Handle error
             intanceApplePayButton.completePaymentAuthorizedFailure();
     });
 });
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

CREATE

var instance = hipay.create('paymentRequestButton', 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

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.

NameTypeDescription
type

required

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

required

stringA 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.