Apple Pay Environment Setup

Before adding an Apple Pay button to your webpage there are environment configuration requirements that need to be addressed. Without this configuration, rendering and using an Apple Pay button on the web will not work.

Requirements

There are two ways you could configure an environment in order to allow the use of an Apple Pay button on a web page.

• Environment configuration with Apple
  • Create a merchant identifier within an Apple Developer account.
  • Create a payment processing certificate.
  • Register merchant domains that will render an Apple Pay button.
• Environment configuration with PayConex
  • Use the payment processing certificate configured for PayConex.
  • Register as an Apple Pay merchant via the PayConex API.

The rest of this guide will focus on configuring an environment using the PayConex API and payment processing certificate.

📘

Note

For more information on configuring an environment via direct registration with Apple Pay they provide a guide that can be referenced here.

General Configuration

Merchants who want to integrate Apple Pay using the PayConex Apple Pay Certificate must set up their server for secure communication with Apple Pay.

• All pages that include Apple Pay must be served over HTTPS.
• Your domain must have a valid SSL certificate.

Upload Apple Pay Certificate

The first step in this environment configuration is uploading the PayConex Apple Pay certificate to the server that will load the web page containing the Apple Pay button.

Apple will expect this certificate file to be available on your server at this location:

https://[MERCHANT_DOMAIN]/.well-known/apple-developer-merchantid-domain-association

Follow this link to download the Apple Pay certificate for the PayConex certification environment.

📘

Note

The test certificate is not validated by Apple and isn't required to test the merchant registration API call.

The PayConex Apple Pay certificate for production use can be accessed by following this link.

Download the file and copy it to your server in a directory named ./well-known with the filename apple-developer-merchantid-domain-association.

📘

Note

When you download the files make sure to remove the .test or .prod extensions.

Send PayConex API Request to Register the Account to use Apple Pay

At this time, any developer wanting to display the Apple Pay button on their pages must register a merchant's PayConex account to use Apple Pay.

To facilitate this requirement an Apple Pay merchant registration API end-point is available via the PayConex API.

Example Merchant Registration API Request

The information below will describe how to make this API request.

HTTP Method

HTTP Method for the end-point is: POST

Base URL

In the cert/test environment, the URL is: https://api-cert.payconex.net

API End-point

The API End-point for this request is: /api/v1/apple_pay/merchant_registration/{account_id}

Where {account_id} is the value of the merchant's PayConex account_id.

Example API Request Body

The following is an example request body for registering a merchant.

{
  "domains": [
    "example.com"
  ],
  "merchantUrl": "https://example.com",
  "partnerMerchantName": "Merchant Name"
}

Authenticating the API Request

This API requires the creation of an HMAC Authorization header to authenticate incoming requests. An Authorization header will contain the following properties.

Calculating the Response Property

The first step for calculating the response property is to create a SHA-256 hash (in hexadecimal format) of the API request body. For the purposes of this article, this value is called the ContentHash.

After computing the ContentHash the next step is to build the string that will eventually be sent through a HMAC-SHA256 hashing function. The string we are building here is called the "string-to-hash" below.

A valid "string-to-hash" contains the; HTTP method, API end-point, nonce, timestamp, and the "ContentHash".

HTTP Method + " " + API end-point + "\n" + nonce + "\n" + timestamp + "\n" + "\n" + ContentHash;

An example string-to-hash would look similar to this:

POST /api/v1/apple_pay/merchant_registration/180000000742\nD1O48xR1TDvDDDKS7L8EFsXrzu\n1670806392214\n\n4c43f07b4dbc4f21c32ce3b5518d9645faf6ad9b422069fd116f56d25c229aab

The key used for the HMAC-SHA256 function is the API Secret Key generated for your PayConex account.

In this case, that value is:

fab64496661cde83dc270e2ebb5c1ef0

Creating the response property value at this point is as easy as running the string through an HMAC-SHA256 hashing function. Most programming languages have packaged HMAC-SHA256 functions, or they can be easily acquired via package managers like NPM (JavaScript/NodeJS), Gradle/Maven (Java), PIP (Python), etc.

The result of hashing the "string-to-hash" generated in this example is:

response="095293ec995297d98f582a50d1fb74db7960ddf9843ad00bfaab4565f1233155"

Now that all the elements above have been calculated/defined it is time to build the HMAC Authorization header.

Authorization: Hmac id="180000000742", nonce="D1O48xR1TDvDDDKS7L8EFsXrzu", timestamp="1670806392214", response="095293ec995297d98f582a50d1fb74db7960ddf9843ad00bfaab4565f1233155"

Now that the environment has been configured for Apple Pay the next step is adding Apple Pay to your web page.