Apple Pay

Apple Pay is a digital payment method that allows cardholders to use their Apple devices to securely make purchases online or in person. By integrating with Apple Pay on PayFields, you can enhance your customers' checkout experience on your website or app by providing them with a trusted and convenient payment option.

Prerequisites

• You must have openssl installed on your computer.
• You must have a merchant ID that uniquely identifies your business as a merchant able to accept payments.

Your merchant ID allows Apple to identify you as a merchant that can accept payments. This ID never expires, and you can use it on multiple websites and iOS apps.

To create your merchant ID, log in to your Apple Developer Account using the Account Holder, Admin, or App Manager role. Do not log in using a Developer role or as a Sandbox Tester user.

1. In Certificates, Identifiers & Profiles, select Identifiers from the sidebar.
2. Select App IDs in the upper-right corner, and then select Merchant IDs.
3. Select the Add button (+).
4. On the Identifier Type screen, accept the default selections by clicking Continue.
5. Enter the merchant description and identifier name, and then select Continue.
6. Review the settings, and then select Register.

The identifier name you entered is your merchant ID.

Note: If you have multiple environments, such as test and production, you may choose to create additional merchant IDs for each environment.
Example merchant IDs:

• Production - merchant.com.paygateway.product-name.merchant-unique-name
• Test - merchant.com.paygateway.test.product-name.merchant-unique-name

Payment processing certificate

A certificate associated with the merchant ID that is used to secure transaction data.
Note: The payment processing certificate expires after 25 months. When the certificate expires, follow these instructions again to create a new certificate.

Create the private key and the Certificate Signing Request (CSR)

1. Create the private key for the payment processing certificate.
   openssl ecparam -out private_payment_processing_test.key -name prime256v1 -genkey

2. Create the CSR. This is required later to generate the payment processing certificate.
   openssl req -new -sha256 -key private_payment_processing_test.key -nodes -out private_payment_processing_test.csr

You will need to provide the following:

• Country name
• State or province name
• Locality name
• Organization name
• Organization unit name
• Common name – The merchant ID associated with the environment you’re using
• Email address
• Challenge password
• An optional company name

Generate the payment processing certificate and upload the CSR

1. Log in to your Apple Developer account.
2. In Certificates, Identifiers & Profiles, select Identifiers from the sidebar.
3. Under Identifiers, select Merchant IDs using the filter in the top-right.
4. Select the relevant merchant ID from the list.
5. Under Apple Pay Payment Processing Certificate, select Create Certificate.
6. Answer the question on whether the payments associated with this merchant ID are to be processed exclusively in mainland China.
7. Select Choose File.
8. Select the CSR file you previously created, and then select Continue.
9. 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_test.key -out private_payment_processing_test.key-pkcs8.key -nocrypt

Merchant identity certificate

A Transport Layer Security (TLS) certificate that is associated with your merchant ID and is used to authenticate sessions with the Apple Pay servers.

Note: The merchant identity certificate is only required for Apple Pay on the web. It’s not required for iOS apps.
Create the private key and the Certificate Signing Request (CSR)

openssl req -new -newkey rsa:2048 -nodes -keyout merchant.com.paygateway.test.web.key -out merchant.com.paygateway.test.web.csr

You will need to provide the following:

• Country name
• State or province name
• Locality name
• Organization name
• Organization unit name
• Common name – The merchant ID associated with the environment you’re using
• Email address
• Challenge password
• An optional company name

Generate the merchant identity certificate

1. Log in to your Apple Developer account.
2. In Certificates, Identifiers & Profiles
   , select Identifiers from the sidebar.
3. Under Identifiers, select Merchant IDs using the filter in the top-right.
4. Select the relevant merchant ID from the list.
5. Under Apple Pay Merchant Identity Certificate, select Create Certificate.
6. Select Choose File.
7. Select the CSR file you previously created, and then select Choose.
8. Select Continue.
9. Select Download. The certificate file ( with a .cer file extension) appears in your Downloads folder.
10. Convert the downloaded .cer file to a .pem file.

openssl x509 -inform der -in merchant_id.cer -out merchant.com.paygateway.test.web.pem

11. Concatenate the private key with the .PEM file. This concatenated certificate/key combination is needed for Apple Pay on the web.
    cat merchant.com.paygateway.test.web.pem merchant.com.paygateway.test.web.key > merchant.com.paygateway.test.web.final.pem

To start processing transactions, you need to first register and verify your domain for Apple Pay.
Apple Pay servers don’t require domain verification for the testing or sandbox environment. You only receive domain verification files for merchant IDs that are used for the production environment.

To register and verify your domain:

1. Log in to your Apple Developer account.
2. In Certificates, Identifiers & Profiles
   , select Identifiers from the sidebar.
3. Under Identifiers, select Merchant IDs from the pop-up menu in the top right.
4. Select your merchant ID.
5. Under Merchant Domains, select Add Domain.
6. Add the name of your domain, and then select Save.
7. Under Merchant Domains and next to the domain you have added, click Verify.
8. To download the domain verification file, select Download.
9. Host the domain verification file in the following path: https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association.txt
10. To verify the domain, click OK.
11. Select Done.

Note: Keep the browser page open; you'll need to use it later to validate the URL.

Create a group of merchants

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.

** Note:** All terminals in a group will be able to add, delete, and update terminals in the same group. However, you can’t create a new group using a terminal that is already linked to a group. To create a new group, you must delete a terminal from the current group, and then use that terminal to create a new group.

To create a group of merchants, use the Merchant Management API to send a POST request to the relevant endpoint. For group_name, spaces are not permitted and alphanumeric symbols are accepted.

Endpoints

Header parameters

{
    "group_name": "BMW-Of-ButterField",
    "entity_type": "merchant_key",
    "entity_list": ["{{terminal_A_merchant_key}}, "{{terminal_B_mk}}""]
}
}))

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

Update a group name

To update a group name, use the Merchant Management API to send a PATCH request including the group_id to the relevant endpoint.

Endpoints

Header parameters

Request

{
    "group_name": "BMW-Of-ButterField-US",
}
}))

Response

{
    "group_id": "1411077945",
    "group_name": "BMW-Of-ButterField-US",
    "entity_type": "merchant_key",
    "entity_list": ["{{terminal_A_merchant_key}}, "{{terminal_B_mk}}""]
    "created_by": "{{terminal_A_mk}}",
    "created_date": "2023-05-18T19:38:19Z"
    "modified_by": "906000103556",
    "modified_date": "2023-06-18T19:45:19Z"
}
}))

Update a group entity list

To update a group entity list, use the Merchant Management API to send a PATCH request to the relevant endpoint.

Endpoints

Header parameters

Request

{
    "entity_type": "merchant_key",
    "entity_list": ["{{terminal_C_merchant_key}}, "{{terminal_D_mk}}""]
}

}))

Response

{
    "group_id": "1411077945",
    "group_name": "BMW-Of-ButterField-US",
    "entity_type": "merchant_key",
    "entity_list": ["{{terminal_C_merchant_key}}, "{{terminal_D_mk}}""]
    "created_by": "{{terminal_A_mk}}",
    "created_date": "2023-05-18T19:38:19Z"
    "modified_by": "906000103556",
    "modified_date": "2023-06-18T19:45:19Z"
}

}))

Delete a group

To delete a group of merchants, use the Merchant Management API to send a DELETE request including the group_id to the relevant endpoint.

Endpoints

Header parameters

Retrieve a group of merchants

To retrieve a group of merchants, use the Merchant Management API to send a GET request to the relevant endpoint.

Endpoints

Header parameters

Retrieve a group by entity type and entity value

To retrieve a group of merchants by entity type and value, use the Merchant Management API to send a GET request to the relevant endpoint.

Endpoints

Header parameters

Create a configuration

To configure Apple Pay for a website, you need the following:

• An Apple Merchant ID
• An Apple-verified domain
• An Apple merchant identity certificate for hosting and enabling the Apple Pay button
• An Apple payment processing certificate for payment data processing
• A group_id to link the configuration to
  To create an Apple Pay configuration, use the Merchant 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.

IMPORTANT: Please ensure to take a note of the group ID (group_id) and the configuration ID (config_id) returned in the response. Both parameters are required for any future updates to your configuration.

Endpoints

Header parameters

Request

{
config_request: {
"config_type": "apple-pay",  
"group_id" : "{{group_id}}",
"config_attributes":[
      {
         "name":"merchant_identity",
         "value":"{{your-apple-merchant-id}}"
      },
      {
         "name":"merchant_domain_name",
         "value":"{{domain_hosting_verified_w_apple}}"
      },
{
         "name":"merchant_identity_certificate",
         "value":"file1"
      },
{
         "name":"merchant_processing_certificate",
         "value":"file2"
      }
   ]
}
file1: <<pathTo/merchant.com.domain.product.final.pem>>
file2: <<pathTo/private_payement_processing_test.key-pkcs8.key>>

}

}))

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"
}
 
}))

Update a configuration

To update an Apple Pay configuration, use the Merchant Management API to send a PATCH request to the relevant endpoint.

Endpoints

Header parameters

Request

{
config_request: {
"config_type": "apple-pay",  
"group_id" : "{{current_group_id}}",
"config_attributes":[
      {
         "name":"merchant_identity",
         "value":"{{your-apple-merchant-id}}"
      },
      {
         "name":"merchant_domain_name",
         "value":"{{domain_host_verified_w_apple}}"
      },
{
         "name":"merchant_identity_certificate",
         "value":"file1"
      },
{
         "name":"merchant_processing_certificate",
         "value":"file2"
      }
   ]
}
file1: <<pathTo/merchant.com.domain.product.final.pem>>
file2: <<pathTo/private_payement_processing_test.key-pkcs8.key>>

}

}))

Response

{
    "config_id": "{{config_id}}",

"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-XXXXXXXXXXXXX"
      },
{
         "name":"merchant_processing_certificate",
         "value":"SCRT-XXXXXXXXXXXXX"
      }
   ]

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

}))

Delete a configuration

To delete an Apple Pay configuration, use the Merchant Management API to send a DELETE request to the relevant endpoint.

Endpoints

Header parameters

Retrieve a configuration

To retrieve an Apple Pay configuration group, use the Merchant Management API to send a GET request to the relevant endpoint.

Endpoints

Header parameters

Prerequisite

Encrypt account credentials
Important: Encrypting account credentials is only required once and not per transaction. Account credentials received from the merchant must be encrypted and stored in their encrypted state for reuse with every future transaction.

To integrate Apple Pay with PayFields, the account_credential parameter must be encrypted when you use it to generate the authTokenV2. To do so, encrypt xwebid in locationid:terminalid:authkey. Account credentials are encrypted because they are used client-side on a consumer device, and this prevents exposing the credentials when used on the Apple device.

Once encrypted, the account_credential can be used to generate the authTokenV2 which is required when configuring your payment page.

Endpoints

Header parameters

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"
}

}))

Configure your payment page

To integrate with PayFields, you first need to configure your payment page. For more information, go to Configuring your payment page.

1. You must link our JavaScript library to your payment page. To do so, include the following JavaScript tag in the header of your page.

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

2. Generate the authTokenV2 to be included in step 3. For information on how to generate the authTokenV2, refer to our Developer Portal.
3. To start processing Apple Pay transactions, add your credentials to the Global Payments library.
   Note: The authorization must be refreshed each time you process an Apple Pay transaction.

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

}))

Enable the Apple Pay button

To enable the Apple Pay button, update your payment page with the following configuration for the button. To customize your Apple Pay button, see the Apple Pay button documentation.

Note: The total object is part of the Apple Wallet processing page.

const paymentRequestForm = GlobalPayments.paymentRequest.setup("#paymentRequestPlainButton", {
    total: { label: 'Donation', amount: { currency: 'USD', value: '34.00' } },
  }, [{
    supportedMethods: 'basic-card',
    data: {supportedNetworks:  ['amex', 'diners', 'discover', 'jcb', 'mastercard', 'unionpay',
        'visa', 'mir'], supportedTypes: ['debit', 'credit', 'prepaid']},
  }, {
    supportedMethods: "https://apple.com/apple-pay",
    data: {
      version: 3,
      merchantIdentifier: "{{your-apple-merchant-identifier}}", // usually starts with merchant.com....
      merchantCapabilities: ["supports3DS", "supportsCredit", "supportsDebit"],
      supportedNetworks: ["amex", "discover", "masterCard", "visa"],
      countryCode: "US",
      storeDisplayName: "{{store_name}}"
    },
  }]);

}))

Handling callback calls

The gateway returns a token-success response when a customer completes and submits the pay fields. This response includes a temporary_token that you must submit to the gateway for transaction requests.

paymentRequestForm.on("token-success", (resp) => {
// Payment data was successfully tokenized
console.log('payment api token is here', resp);

// TODO: POST data with the token to your server and send it to the transaction api

// Mark the payment as `success`, `fail`, or `unknown` based on the. transaction api response
GlobalPayments.paymentRequest.complete("success");
});

}))

If this is the first time processing using PayFields, you must create a transaction reference_id in your request.

Endpoints

Header parameters

Request

{  "reference_id": "{{transaction_reference_d}}",
  "card": {
    "temporary_token": "{{temp_token}}"
  },
  "customer": {
    "billing_address": {
      "line1": "8200 Central Ave.",
      "postal_code": "94560"
    }
  },
  "payment": {
    "amount": "0.00",
    "currency_code": "840"
  },
  "transaction": {
    "country_code": "840",
    "processing_indicators": {
      "create_token": true,
      "address_verification_service": true,
      "generate_receipt": true
    }
  }
}

}))

Response

{
    "sale_id": "000000003015",
    "status": "Approved",
    "approval_code": "005741",
    "cardsecurity_response": "match",
    "processor_response": "DEVELOPMENT APPROVAL",
    "card": {
        "masked_card_number": "545454XXXXXX5454",
        "expiry_month": "12",
        "expiry_year": "23",
        "type": "MasterCard"
    },
    "payment": {
        "amount": "33.00",
        "currency_code": "840",
        "reference_id": "PAYAPI-8f07eb9a-6e05-4a9f-b03d-7b05280a4ae6",
        "type": "Credit"
    },
    "transaction": {
        "batch_amount": "543.00",
        "batch_number": "000253",
        "entry_type": "Keyed",
        "language": "en-US"
    },
}

}))