Apple Pay prerequisites

Learn more about the prerequisites for Apple Pay integration.

Prerequisites for accepting Apple Pay transactions

If you are using the Unzer Paypage, there are no special prerequisites for using Apple Pay - it can be used immediately. However, if you are using Unzer UI Components, certain plugins or aiming for direct server integration, you need to verify your domain. This process involves the following steps:

1. Allow access from these IPs to your server.
2. Apple Pay verification file from Apple to your server as follows: https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association.
   

   If the link does not work, you can also save the content of this merchant ID domain association file and remove the extension .txt and add this file to your server as is.
3. Inform your Unzer representative on which domain you are using the Apple Pay button. Then the onboarding process will begin on the Unzer side. If you have a developer domain and want to test from there, please inform us because we need to add this domain too.

Deprecated method for integrations before September 2024

Before you can integrate Apple Pay in your website, make sure you configure Apple Pay on web in your Apple Developer Account.

It includes:

• Creating a payment processing certificate and uploading it to the Unzer system.
• Creating a merchant identity certificate that is required for merchant validation. These certificates and corresponding keys are required during the payment process.
• You must also register and verify the domain of you shop.

To learn more, see the Apple Pay documentation.

Generate the Payment Processing Certificate

The Payment Processing Certificate should initially be uploaded to the Unzer system to process future Apple Pay transactions. To generate a Payment Processing Certificate, you need to:

1. Create a Certificate Signing Request (CSR)
2. Upload the Payment Processing Certificate CSR to Apple Developer Account
3. Download the Apple-signed Payment Processing Certificate

Step 1: Generate a Certificate Signing Request

The CSR is required for creating a valid certificate for accepting Apple Pay transactions. Once it is successfully signed, you can download it from your Apple Developer Account.

Generate an ECC private key

In Elliptic-curve cryptography (ECC), an ECC private key is a variable used to decrypt code that was encrypted with a public key.

You need to generate an ECC private key that is used to create the Certificate Signing Request (CSR).

In your command line tool, run the following OpenSSL command:

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

This command creates an ECC private key and saves it to the ecckey.key file.

Create a Certificate Signing Request (CSR)

Now, use your new ECC private key from the previous step (ecckey.key) to generate a Certificate Signing Request (CSR). In your command line tool, run the following OpenSSL command:

openssl req -new -sha256 -key ecckey.key -out ecccertreq.csr

Step 2: Upload the Payment Processing Certificate CSR to Apple

Upload the Payment Processing Certificate CSR to your Apple Developer Account.

For more information on configuring your Apple Developer Account, see Apple Developer Account Help.

Step 3: Download the Apple-signed Payment Processing Certificate

Download and back up the Apple-signed Payment Processing Certificate (apple_pay.cer).

Step 4: Convert the certificate to a text file

In your command line tool, convert the Apple-signed Payment Processing Certificate to a text file in the .pem format:

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

Step 5: Convert your ECC private key to a non-encrypted PKCS #8 private key

In cryptography, PKCS #8 is a standard syntax for storing private key information.

To use your ECC private key for decrypting, you need to convert it to a non-encrypted PKCS #8 private key, like this:

openssl pkcs8 -topk8 -nocrypt -in ecckey.key -out privatekey.key

Step 6: Upload your PKCS #8 private key and your Payment Processing Certificate to the Unzer system

Now you need to upload both your Apple-signed Payment Processing Certificate and your PKCS #8 private key to Unzer. The files are privatekey.key and apple_pay.pem as described in the previous section.

Upload your PKCS #8 private key to the Unzer system

To upload your PKCS #8 private key privatekey.key to Unzer, make a POST call to https://api.unzer.com/v1/keypair/applepay/privatekeys, with the following parameters in the request body:

POST https://api.unzer.com/v1/keypair/applepay/privatekeys

Body:
{
   "format": "PEM",
   "type": "private-key",
   "certificate": "MHcCAQEEIKTAL4TwcY9Upc/9XdIlxRBvU0fuaFA2BhGkqDNxiBkgoAoGCCqGSM49AwEHoUQDQgAEZVFjAqVtO/2vgaIGJFA7n7WUqewS6lbHcQwK7sCAMmDgKHcikCY5FOl7euO3sEBKtKprrnh/u7nlace+0lPYeg=="
}

Body:
{
    "id": "s-key-1",
    "paymentType": "applepay"
}

Upload the Apple-signed Payment Processing Certificate to the Unzer system

To upload your apple_pay.pem certificate to Unzer, make a POST call to https://api.unzer.com/keypair/applepay/certificates with the following parameters in the request body:

Certificate activation
If you upload an additonal certificate and at the same time, another certificate is already active for that keypair, the newly uploaded certificate is not active and will not be used for payment processing. You must switch to the new certificate by activating it with an additional request described in the Activate the certificate section.

POST https://api.unzer.com/v1/keypair/applepay/certificates

Body:

```json
{
    "format": "PEM",
    "type": "certificate",
    "private-key": "s-key-1",
    "certificate": "MIIEcDCCBBagAwIBAgIIHrTLsxpoEO8wCgYIKoZIzj0EAwxxxxx"
}

{
    "id": "s-crt-1",
    "paymentType": "applepay"
}

Activate the certificate

It is possible to upload multiple certificates, but only one can be active for payment processing.

If you have multiple certificates and want to switch to a new certificate before the old one runs out, you need to activate the new certificate.

Make a POST call with the ID of your certificate resource in the request path:

POST https://api.unzer.com/v1/keypair/applepay/certificates/{certificate_ID}/activate

Body:
{
    "id": "s-crt-2",
    "active": true
}

Generate a Merchant Identity Certificate

The merchant ID Certificate is required for the merchant validation, which is required for each payment request.

Step 1: Generate a Certificate Signing Request (CSR)

The Certificate Signing Request(CSR) for the Merchant Identity Certificate has different requirements than for the Payment Processing certificate. This means that the private key for the CSR must be RSA(2048) (algorithm/size).

In your command line tool, run the following OpenSSL command:

openssl req -newkey rsa:2048 -keyout encrypted_merchant_id.key -out merchant_id.csr

This command creates the RSA key and the CSR at the same time and saves them in files named encrypted_merchant_id.key and merchant_id.csr.
You must specify the password for the private key. In the future, when you need to use the key, you must either decrypt it as described in the convert your RSA section or specify the password each time the key is used.

Step 2: Upload the Merchant Identification Certificate CSR to Apple

Upload the Merchant ID Certificate CSR to your Apple Developer Account.

For more information on configuring your Apple Developer Account, see the Apple Developer Account Help.

Step 3: Download the Apple-signed Merchant Identification Certificate

Download and back up the Apple-signed Merchant ID Certificate (merchant_id.cer).

The certificate plus the private key will be required later for the merchant validation. Store these credentials safely.

Step 4: (Conditional) Convert the certificate and key to a text files

Depending on your system, the required format of the certificate and key can vary.
In the following we show how to create a .pem certificate and a non-encrypted private key from merchant_id.cer and encrypted_merchant_id.key.

Convert the certificate

In your command line tool, convert the Apple-signed Merchant ID Certificate to a text file in the .pem format:

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

Convert your RSA private key

In cryptography, PKCS #8 is a standard syntax for storing private key information. To convert it to a non-encrypted PKCS #8 private key, run the following command in your command line tool:

openssl rsa -in encrypted_merchant_id.key -out merchant_id.key

You can also use the encrypted_merchant_id.key directly, as long as you provide the password when using it.

You should now have merchant_id.pem and merchant_id.key files that can be used for the merchant validation of Apple Pay.

See also

Apple Pay documentation links:

• Configure Apple Pay
• Apple Pay - Payment Token Format Reference
• Create a certificate signing request
• merchant validation