Skip to content

Instantly share code, notes, and snippets.

@randyburden

randyburden/Updating Apple Pay Certificates.md

Created October 3, 2022 15:52
Show Gist options
  • Save randyburden/bac588ed3017a6eadf858523e9917d0d to your computer and use it in GitHub Desktop.
Save randyburden/bac588ed3017a6eadf858523e9917d0d to your computer and use it in GitHub Desktop.
Download ZIP
How to update Apple Pay certificates that are expiring
Raw
Updating Apple Pay Certificates.md

Updating Apple Pay Certificates

Overview

This document covers how to update the following Apple Pay certificates:

  • Apple Pay Payment Processing Certificate
    • Used to decrypt Apple Pay requests
  • Apple Pay Merchant Identity Certificate
    • Used to make requests to Apple Pay APIs

Expiration Email Notifications

  • Apple Pay certificates expire every 25 months and must be updated by creating new Apple Pay certificates.
  • Apple will send several email notifications starting 30 days before expiration.

Part 1 - Updating the Apple Pay Payment Processing Certificate

  1. Log into Apple Developer Portal

  2. Navigate to the certificates that are expiring:

    • After login, click "Certificates, IDs & Profiles"
    • On the "Certificates, Identifiers & Profiles" page on the left-side nav click Identifiers
    • Then click the dropdown on the right side and select "Merchant IDs"
    • Select "merchant.com.$YOUR_COMPANY_NAME$" from the list of Merchant IDs

  3. On the "Edit or Configure Merchant ID" page, click "Create Certificate" under the "Apple Pay Payment Processing Certificate" section

    • Note that if the "Create Certificate" button is not clickable, then you will have to revoke the older non-activate certificate as there can only be 2 certificates created at a time. Be careful not to revoke the current Activate Certificate as that will immediately prevent Apple Pay payments.

  4. On the "Create a New Certificate" page under the "Upload a Certificate Signing Request" section, there is a "Choose File" button that will open a file picker so you can select the Certificate Signing Request (CSR) file. In the next steps we will create the CSR file using the openSSL command line tool.

    • 4.1. Open a command/terminal window and navigate to a working directory:
      • C:\temp\cert\
        • This will be our working directory where we will create many files.
        • Create this directory if it does not exist.
    • 4.2. Run the following command below to generate a private key for the CSR: 
openssl ecparam -name prime256v1 -genkey -out ApplePayPaymentProcessingCertificateSigningRequestPrivateKey.key
  • 4.3. Run the following command to create the CSR file itself by supplying the private key we just created.
    • It will prompt for several fields to be entered.
openssl req -new -sha256 -key ApplePayPaymentProcessingCertificateSigningRequestPrivateKey.key -nodes -out ApplePayPaymentProcessingCertificateSigningRequest.csr

  1. Now back on the "Create a New Certificate" page under the "Upload a Certificate Signing Request" section, click on the "Choose File" button, and select the newly created CSR file.

  2. Apple will then hand us back a ".cer" file in return. Save that file to our working directory. That certificate, once converted to a PKCS #12 file (.p12 file extension), will allow us to actually verify the Apple Payment Token's signature and decrypt its payload so we can process the transaction ourselves or pass it along to our payment processor that does not support Apple Pay.

  3. To convert the ".cer" file Apple provided after uploading the CSR:

    • 7.1. Rename the ".cer" file to:

      • ApplePayPaymentProcessingCertificate.cer

    • 7.2. In our working directory, run the following command below to convert the ".cer" file to a ".pem" file:

openssl x509 -inform DER -outform PEM -in ApplePayPaymentProcessingCertificate.cer -out ApplePayPaymentProcessingCertificate.pem
  • 7.3. Run the following command below to convert the ".pem" file to a ".p12" file based off the original CSR private key file as well as the ".pem" file we just created.
    • Note that the command includes the parameter "-passout pass:" which means we are NOT supplying a password to the ".p12" file. This example uses no password, but you may choose to use a password.
openssl pkcs12 -export -passout pass: -inkey ApplePayPaymentProcessingCertificateSigningRequestPrivateKey.key -in ApplePayPaymentProcessingCertificate.pem -out ApplePayPaymentProcessingCertificate.p12

  1. Now we need to create the private key “.der” file

    • 8.1. Run the following command below to export the private key from the “.p12” file.
      • If/when prompted for a password just press ENTER to bypass.
opnssl pkcs12 -nocerts -nodes -in ApplePayPaymentProcessingCertificate.p12 -out ApplePayPaymentProcessingCertificatePrivateKey.key
  • 8.2. Run the following command below to convert the private key file into “.der” format.
openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt -in ApplePayPaymentProcessingCertificatePrivateKey.key -out ApplePayPaymentProcessingCertificatePrivateKey.der

  1. Once completed you should have the following 7 files created (files are listed in the order created). Keep all these files as they will be needed later.

    • ApplePayPaymentProcessingCertificateSigningRequestPrivateKey.key
    • ApplePayPaymentProcessingCertificateSigningRequest.csr
    • ApplePayPaymentProcessingCertificate.cer
    • ApplePayPaymentProcessingCertificate.pem
    • ApplePayPaymentProcessingCertificate.p12
    • ApplePayPaymentProcessingCertificatePrivateKey.key
    • ApplePayPaymentProcessingCertificatePrivateKey.der

Part 2 - Updating the Apple Pay Merchant Identity Certificate

  1. Repeat Part 1 steps 1 and 2 to navigate to the "Edit or Configure Merchant ID" page.

  2. On the "Edit or Configure Merchant ID" page, click "Create Certificate" under the "Apple Pay Merchant Identity Certificate" section.

    • Note that if the "Create Certificate" button is not clickable, then you will have to revoke the older non-activate certificate as there can only be 2 certificates created at a time. Be careful not to revoke the current Activate Certificate as that will immediately prevent Apple Pay payments.

  3. On the "Create a New Certificate" page under the "Upload a Certificate Signing Request" section, there is a "Choose File" button that will open a file picker so you can select the Certificate Signing Request (CSR) file. In the next steps we will create the CSR file for the Apple Pay Merchant Identity Certificate which uses different commands than the Apple Pay Payment Processing Certificate CSR.

    • 3.1. In our working directory, run the following command below to generate the private key for the CSR using RSA-2048 encryption.
openssl genrsa -out ApplePayMerchantIdentityCertificateSigningRequestPrivateKey.key 2048
  • 3.2. Run the following command to create the CSR file itself by supplying the private key we just created. It will prompt for several fields to be entered.
openssl req -new -key ApplePayMerchantIdentityCertificateSigningRequestPrivateKey.key -out ApplePayMerchantIdentityCertificateSigningRequest.csr

  1. Now back on the "Create a New Certificate" page under the "Upload a Certificate Signing Request" section, click on the "Choose File" button, and select the newly created CSR file.

  2. Apple will then hand us back a ".cer" file in return. Save that file to our working directory. That certificate, once converted to a PKCS #12 file (.p12 file extension) and installed on your application servers or certificate store, will allow us to call Apple Pay APIs to create Apple Pay sessions.

  3. To convert the ".cer" file Apple provided after uploading the CSR:

    • 6.1. Rename the “.cer” file to:
      • ApplePayMerchantIdentityCertificate.cer
    • 6.2. In our working directory, run the following command below to convert the ".cer" file to a ".pem" file:
openssl x509 -inform DER -outform PEM -in ApplePayMerchantIdentityCertificate.cer -out ApplePayMerchantIdentityCertificate.pem
  • 6.3. Run the following command below to convert the ".pem" file to a ".p12" file based off the original CSR private key file as well as the ".pem" file we just created.
    • Note that the command includes the parameter "-passout pass:" which means we are NOT supplying a password to the ".p12" file.
openssl pkcs12 -export -passout pass: -inkey ApplePayMerchantIdentityCertificateSigningRequestPrivateKey.key -in ApplePayMerchantIdentityCertificate.pem -out ApplePayMerchantIdentityCertificate.p12

  1. Once completed you should have the following 6 files created during Part 2 below (files are listed in the order created). Keep all these files as they will be needed later.

    • ApplePayMerchantIdentityCertificateSigningRequestPrivateKey.key
    • ApplePayMerchantIdentityCertificateSigningRequest.csr
    • ApplePayMerchantIdentityCertificate.cer
    • ApplePayMerchantIdentityCertificate.pem
    • ApplePayMerchantIdentityCertificate.p12

Installing the Certificates on Windows

If you are using Windows and need the certificate installed on each application server, please proceed.

Steps to install the .p12 certificate on each applicable application server:

  1. Select Run from the Start menu, and enter certlm.msc

  2. In the Certificate Manager tool, expand Personal > Certificates

  3. Right-click on Personal > Certificates

  4. Select All Tasks | Import

  5. Click Next on the wizard and click the Browse button and select the file:

    • ApplePayMerchantIdentityCertificate.p12

  6. Do NOT enter a password.

  7. Check the "Mark this key as exportable" box.

  8. Select Next, then Finish and wait a few seconds until it displays a success message.

  9. Then under Personal > Certificates, in the right-side pane, find the new certificate that was just installed, right-click on the certificate, Select All Tasks | Manage Private Keys

  10. Click Add and type "IIS_IUSRS" to allow the default IIS Identity Pools access to the certificates private key. Then click OK and OK.

    • If we ever run our applications under a different Identity, we need to make sure that the account the application runs under has access to the certificates private key.
    • An alternative is to allow the "Everyone" account to have read access to the certificates private key.

  11. After installation, immediately activate the Apple Pay Payment Processing Certificate on the Apple Pay Developer Portal.

    • Login to the Apple Pay Developer Portal:
    • Navigate to the applicable Merchant ID
    • Click the "Activate" button on the newly created certificate(s)

  12. Now test that Apple Pay is working.

Notes

  • The .der extension

    • DER is the method of encoding the data that makes up the certificate. DER itself could represent any kind of data, but usually it describes an encoded certificate or a CMS container.

  • The .pem extension

    • PEM is a method of encoding binary data as a string (ASCII armor). It contains a header and a footer line (specifying the type of data that is encoded and showing begin/end if the data is chained together) and the data in the middle is the base 64 data. In the case that it encodes a certificate it would simply contain the base 64 encoding of the DER certificate. PEM stands for Privacy Enhanced Mail; mail cannot contain un-encoded binary values such as DER directly.
    • PEM may also encode / protect other kinds of data that is related to certificates such as public / private keys, certificate requests, etc. If the contents are a common X509v3 certificate then the PEM is encoded as:
-----BEGIN CERTIFICATE-----
... base 64 encoding of the DER encoded certificate
    with line endings and padding with equals signs ...
-----END CERTIFICATE-----

  • The .cer or .crt extension

    • .cer just stands for certificate. It is normally DER encoded data, but Windows may also accept PEM encoded data. You need to take a look at the content (e.g. using the file utility on posix systems) to see what is within the file to be 100% sure.

  • The .p12 extension

    • .p12 is an alternate extension for what is generally referred to as a "PFX file" and is the combined format that holds the private key and certificate and is the format most modern signing utilities use.
    • A .p12 and .pfx are the exact same binary format.
      • The reason, that there are two file extensions is historical. PFX was a Microsoft extension, while P12 was the Netscape one. In the meantime, both formats have been adapted to be identical. The file extensions are interchangeable.

Sources

Sources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment