Apple Pay - Configuration

Your Merchant ID uniquely identifies you as an Apple Pay merchant. The Merchant ID never expires and can be used across multiple apps and websites. The ID should be unique for each environment; Test and Production. To create your Merchant ID, complete the following steps.

1. Log in to your Apple Developer Account
   • Role required: Account Holder, Admin, or App Manager (Note: Do not use Developer role or Sandbox Tester User)
2. Navigate to Merchant ID setup
   • Go to: Certificates, Identifiers & Profiles
   • In the sidebar, select Identifiers
   • At the top‑right, filter by Merchant IDs
3. Create a new Merchant ID
   • Click the Add (+) button
   • On Identifier Type screen, leave defaults selected and click Continue
4. Provide Merchant details
   • Enter Description (e.g. "My Store – Production")
   • Enter Identifier (e.g. merchant.com.paygateway.productname.unique)
   • Click Continue
5. Review & Register
   • Review your details
   • Click Register

Apple Pay requires two certificates linked to your Merchant ID:

• Payment Processing Certificate – Encrypts and secures payment data
• Merchant Identity Certificate – Authenticates your merchant domain for Apple Pay on the web

2.1 Payment Processing Certificate

The Payment Processing Certificate is used to secure transaction data between Apple Pay and your payment gateway by associating the certificate with your Merchant ID. The Certificate expires after 25 months and must be renewed before expiration. To create your Payment Processing Certificate, complete the following steps.

Step 1. Create the Private Key for the payment processing certificate.

openssl ecparam -out private_payment_processing.key -name prime256v1 -genkey

Step 2. Create the Certificate Signing Request (CSR) that is required later to generate the payment processing certificate.

openssl req -new -sha256 -key private_payment_processing.key -nodes -out private_payment_processing.csr

Step 3. You will need to provide the following details:
(i) Country Name
(ii) State or Province Name
(iii) Locality Name
(iv) Organization Name
(v) Organizational Unit Name
(vi) Common Name (Merchant ID)
(vii) Email Address
(viii) Challenge Password (optional)
(ix) Company Name (optional)

Step 4. Upload the CSR to your Apple Developer account

• Log in to Apple Developer account
• Navigate to: Certificates, Identifiers & Profiles > Identifiers > Merchant IDs
• Select your Merchant ID
• Under Apple Pay Payment Processing Certificate, click Create Certificate
• Answer China processing question if prompted
• Upload your .csr file

To use the private key you created for decrypting, first convert it to a non-encrypted PKCS#8 private key. This private key is stored in the Apple Pay configuration.

openssl pkcs8 -topk8 -in private_payment_processing.key -out private_payment_processing.pkcs8.key -nocrypt

2.2 Merchant Identity Certificate

The Merchant Identity Certificate is a Transport Layer Security (TLS) certificate that is associated with your merchant ID and is used to authenticate sessions with the Apple Pay servers. It is required for Apple Pay on the Web (not for iOS apps).

Step 1. Create Private Key & CSR

openssl req -new -newkey rsa:2048 -nodes -keyout merchant_identity.key -out merchant_identity.csr

Step 2. Provide the same details as above (with the relevant Merchant ID as Common Name).

Step 3. Upload CSR to your Apple Developer account

• Log in to Apple Developer account
• Navigate to: Certificates, Identifiers & Profiles > Identifiers > Merchant IDs
• Select your Merchant ID
• Under Apple Pay Merchant Identity Certificate, click Create Certificate
• Upload .csr
• Select Download. The certificate file ( with a .cer file extension) appears in your Downloads folder.

Step 4. Convert the downloaded .cer file to a .pem file.

openssl x509 -inform der -in merchant_identity.cer -out merchant_identity.pem

Step 5. Concatenate the private key with the .PEM file. This concatenated certificate/key combination is needed for Apple Pay on the web.

cat merchant_identity.pem merchant_identity.key > merchant_identity.final.pem

Note: Store .pem and .key files securely. Never commit to source control.

To start processing transactions, you need to first register and verify your domain for Apple Pay. You only receive domain verification files for merchant IDs that are used for the production environment. It is required for Apple Pay on the Web (not for iOS apps).

Complete the following steps:

1. Log in to your Apple Developer account.
2. Navigate to Certificates, Identifiers & Profiles > Identifiers.
3. Filter by Merchant IDs and select your Merchant ID.
4. Under Merchant Domains, click Add Domain and enter your domain, and then select Save.
5. Under Merchant Domains and next to the domain you have added, click Verify. To download the domain verification file, select Download.
6. Host the file at: https://<DOMAIN_NAME>/.well-known/apple-developer-merchantid-domain-association.txt.
7. To verify the domain, click OK and Select Done.

Use Groups to associate merchant keys (each tied to a terminal) that should share a single Apple Pay configuration. A Configuration binds Apple Pay artifacts (merchant ID, verified domain, certificates) to that group so every terminal in it can transact with the same setup.

Important: Save both group_id and config_id for future configuration updates.

Prerequisites

• Apple Merchant ID
• Apple-verified domain (via domain association file)
• Apple Merchant Identity certificate (for button / session)
• Apple Payment Processing certificate (for payment data)
• Naming: group_name is alphanumeric with no spaces (e.g., RetailNorth01)

Quick start

• Create a group.
• Add merchant keys to that group.
• Create Apple Pay configuration (link it to the group_id).
• Switch to Production Endpoints (once testing is complete).

Create a group of merchants to contain all of the merchant keys that will be sharing the same Apple Pay configuration. Each merchant key is linked to a terminal ID.
With credentials scoped to the group, you can add, update, or remove terminals in that group only—no cross-group changes. A terminal can belong to only one group at a time. If it’s already assigned, remove from its current group before using it to create a new group.

For more information on the other methods associated with groups, such as update, retrieve or delete, please refer to the Digital Wallets Management API Reference.

Endpoints

Sample Request

{
    "group_name": "BMW-Of-ButterField",
    "entity_type": "merchant_key",
    "entity_list": ["151359010056","122636414785"]
}

Sample Response

{
    "group_id": "1411077945",
    "group_name": "BMW-Of-ButterField",
    "created_by": "{{terminal_A_mk}}",
    "created_date": "2023-05-18T19:38:19Z"
}

To create an Apple Pay configuration, use the Digital Wallets Management API to send a POST request to the relevant endpoint. Once the configuration is completed, all terminals or group members can use this configuration to run transactions. To update, retrieve or delete a configuration, please refer to the Digital Wallets Management API Reference.

As part of the request message body, you must add the following form-data as individual keys:

• configuration request file (config_request)
• merchant identity certificate (file1)
• payment processing certificate (file2)

Endpoints

Sample request

curl -L 'https://api.paygateway.com/merchant-management/configurations' \
-H 'Accept: application/json' \
-H 'Authorization: 12345' \
-H 'Content-Type: multipart/form-data' \
-H 'X-GP-Api-Key: 12345' \
-H 'X-GP-Version: 2021-05-11' \
-F 'config_request="{
    \"config_type\": \"apple-pay\",
    \"group_id\": \"Sample Value\",
    \"config_attributes\": [
        {
            \"name\": \"merchant_identity\",
            \"value\": \"Sample Value\"
        },
        {
            \"name\": \"merchant_domain_name\",
            \"value\": \"Sample Value\"
        },
        {
            \"name\": \"merchant_identity_certificate\",
            \"value\": \"file1\"
        },
        {
            \"name\": \"merchant_processing_certificate\",
            \"value\": \"file2\"
        }
    ]
}"' \
-F 'file1=@"merchant_identity.final.pem"' \
-F 'file2=@"private_payment_processing.pkcs8.key"'

Sample Response

{
    "config_id": "1411077945",
    "config_type": "apple-pay",
    "group_id": "{{group_id}}",
    "config_attributes": [
        {
            "name": "merchant_identity",
            "value": "XXXXXXXXXXXXX"
        },
        {
            "name": "merchant_domain_name",
            "value": "XXXXXXXXXXXXXXX"
        },
        {
            "name": "merchant_identity_certificate",
            "value": "SCRT-XXXXXXXXXXXXXXXX"
        },
        {
            "name": "merchant_processing_certificate",
            "value": "SCRT-XXXXXXXXXXXXX"
        }
    ]

    "created_by": "{{terminal_A_mk}}",
    "created_date": "2023-05-18T19:38:19Z"
}

With Apple Pay, it is necessary to encrypt the merchant’s credentials because the Digital Wallet runs on the customer’s device. You only need to do this once, you can then store the encrypted value (account_credential) and reuse it each time you process a transaction.

You create the account_credential parameter by encrypting the merchant’s credentials: location_id:terminal_id:auth_key For each transaction, use the stored account_credential to generate a new AuthTokenV2, then use that token when configuring your payment page. For more information, please refer to Authenticating Your Requests.

Endpoints

Request parameters

Request

{
  "app_name": "Silverstar Home Rental Services",
  "auth_key": "WaZva*****40*******************z",
  "merchant_id": "800000000000",
  "terminal_id": "80000000"
}

Response

{
"account_credential": "gNgAAe9VQKjnBBGFnoAodEfxq1zfWWHATPgmhxdHVC78kQw2rccsDFHZ50upTQZg5YtgVUlJapucdY5/wVgmbM1Bg3VhmRumwR/1JV7VWDXx2dwb"
}

Step 1. Load the Hosted Fields library. Add this script tag to your page, in the head or before the body.

<script src="https://js.paygateway.com/secure_payment/v1/globalpayments.js"></script>

Step 2. Generate an AuthTokenV2 (per transaction).
Create a fresh AuthTokenV2 on your server and return it to the page.
See AuthTokenV2.

Step 3. Initialize Hosted Fields with your credentials. Use the token from step 2 when you configure the library.

‘X-GP-Api-Key’ : “QwAnDXXXXXXXXXXXXXXXXXXXXXXETHqV”,
‘X-GP-Environment’ : “test”,
'enableAutocomplete': true,
'Authorization' : "AuthToken {{authTokenV2}}", 
'X-GP-Merchant-Key': "{{terminal-merchant-key}}" 

Always generate a new AuthTokenV2 for each Apple Pay transaction.