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.
NoteFor 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-associationFollow this link to download the Apple Pay certificate for the PayConex certification environment.
NoteThe 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.
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 V4 API.
Example Merchant Registration API Request
POST /api/v4/accounts/{accountId}/applePay/enrollment
{
"domains": [
"example.com"
],
"merchantUrl": "https://example.com"
}*Required Scopes: pcx:apple_pay:*, pcx:apple_pay:account:*, pcx:apple_pay:account:create
For complete guide on putting together an HTTP request for PayConex V4 API with proper permission scopes, please refer to End-point definitions for the PayConex™ V4 API.
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.
If you are having trouble generating your HMAC headers, refer to API Authentication | ContentHash and check out PayConexHmac.php for precisely calculating ContentHash with our code sample.
| Property | Description |
|---|---|
| id | This property must be set to a PayConex API ID that has the proper permissions configured. See our guide on PayConex API Key Management for more information on setting this up. |
| nonce | A nonce is a unique random string. If a nonce is encountered more than once during a 10-minute period the API call is rejected. It is your responsibility to ensure that the nonce is unique. |
| timestamp | A Unix timestamp. Our service will reject API calls with a timestamp older than 10 minutes. |
| response | The response property is an HMAC-SHA256 hash (in hexadecimal format) created from a string (string-to-hash below) of various API request properties. The string is hashed using a PayConex API Secret Key value. See the following information for a detailed description of how to construct the string that must be hashed and included in this property. |
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/v4/accounts/180000000742/applePay/enrollment\nD1O48xR1TDvDDDKS7L8EFsXrzu\n1670806392214\n\n4c43f07b4dbc4f21c32ce3b5518d9645faf6ad9b422069fd116f56d25c229aabThe key used for the HMAC-SHA256 function is the API Secret Key generated for your PayConex account.
In this case, that value is:
fab64496661cde83dc270e2ebb5c1ef0Creating 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="a2e7d0c678443f827e08b051e5ce022a63295bffdf291d24f49c8fbc9a2e66f2"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="a2e7d0c678443f827e08b051e5ce022a63295bffdf291d24f49c8fbc9a2e66f2"Now that the environment has been configured for Apple Pay the next step is adding Apple Pay to your web page.
Updated 5 days ago