Documentation

Apple Pay

Get started with Apple Pay

This page provides a comprehensive guide to successfully integrate Apple Pay with DEUNA.

Apple Pay is a digital wallet platform and payment system that enables secure purchases in apps and websites. It allows users to make online payments from Safari on Mac, iPhone, iPad, and Apple Watch, using card data stored securely within the Apple ecosystem.

How it works

Integrating with Apple Pay is significantly different from other traditional payment methods, so it's important to understand how it works before integrating with DEUNA.

Apple Pay encrypts the buyer's card information using a payment token generated by Apple. This token is transmitted to the merchant's server, where DEUNA decrypts it and sends the card information to the configured payment processor.

Apple Pay Payment Token

The Apple Pay payment token is an encrypted object generated by Apple's servers during each transaction. It contains the buyer's card information securely encrypted using the public key from the merchant's payment processing certificate.

This token is unique to each transaction, ensuring that even if intercepted, it cannot be reused by third parties.

Cryptogram

A cryptogram is a dynamic, transaction-specific code generated during a payment to authenticate and protect the process. Apple Pay uses the 3DSecure payment type, in which case the cryptogram is transmitted as OnlinePaymentCryptogram within the decrypted token.

The cryptogram is validated by the card network to authorize the transaction. If present, it must always be sent to the PSP — otherwise, the transaction will fail.

ApplePay Configuration

⚠️

An active Apple Developer account is required to configure Apple Pay.

This section details the complete Apple Pay configuration process, from creating the Merchant ID in the Apple Developer portal to registering the credentials in DEUNA.

Use this guide to prepare and configure Apple Pay with DEUNA.

  • Apple Developer Configuration: Create a Merchant ID, generate and convert the required certificates and keys, and verify your merchant domains.
  • DEUNA Admin setup: Add the Apple Pay connection, configure routing, and enable Apple Pay.

Once finished, you'll be ready to choose your integration path (SDK or Direct).

Apple Pay certificate options

In the DEUNA Admin, you will find two certificate options for Apple Pay:

  • DEUNA: For merchants who do not have an Apple Developer account or a native mobile app (i.e., web-only). In this case, you must register your domain via the API to use DEUNA's certificates.
  • Own: For merchants who have a native mobile app and an Apple Developer account. In this case, follow the steps in this document to generate your certificates and add your credentials in the Admin.

1 Merchant Certification

1.1 Configure Apple Pay in the Apple Developer portal

Docs: https://developer.apple.com/documentation/applepayontheweb/configuring-your-environment

1.1 Create a Merchant ID

  1. Sign in to your Apple Developer account.
  2. Go to Identifiers under the Certificates, Identifiers & Profiles section.
  3. Click the (+) button.
  4. Select Merchant IDs and click Continue.
  5. Enter the Description and Identifier for the merchant, then click Continue.
📘

The Merchant ID follows a reverse-domain format, for example: merchant.com.yourdomain.pay

  1. Click Register to complete the registration.

1.2 Create the Apple Pay Payment Processing Certificate

This certificate is used by Apple to encrypt the buyer's card data. DEUNA uses it to decrypt the payment token.

  1. Generate the Certificate Signing Request (CSR) and its private key by running the following commands in your terminal:
# Generate an EC private key using the P-256 curve
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out payment_processing_private_key.pem

# Create a CSR using the private key
openssl req -new -sha256 \
    -key payment_processing_private_key.pem \
    -out payment_processing_csr.csr
  1. The second command will prompt you for information to generate the certificate. Fill in the fields as follows:
Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: New York
Locality Name (eg, city) []: New York
Organization Name (eg, company) [Internet Widgits Pty Ltd]: DEUNA test  # Merchant description
Organizational Unit Name (eg, section) []:                            # optional
Common Name (e.g. server FQDN or YOUR name) []: merchant.io.deuna.pay # Merchant ID
Email Address []:                                                     # optional

A challenge password []:                                              # optional
An optional company name []:                                          # optional
  1. As a result you will get two files that you must keep:
  • payment_processing_private_key.pem
  • payment_processing_csr.csr
  1. Back in the Apple portal, Click on the Merchant ID you just created.
  2. Under the Apple Pay Payment Processing Certificate section, click Create Certificate.
  3. Click Choose File and select the payment_processing_csr.csr file you just generated.
  4. Click Continue.
  5. Download and keep the apple_pay.cer certificate generated by Apple.

1.3 Create the Apple Pay Merchant Identity Certificate

This certificate is used to authenticate the TLS communication between DEUNA's servers and Apple's servers when requesting a payment session.

  1. Click on the Merchant ID you created.
  2. Under the Apple Pay Merchant Identity Certificate section, click Create Certificate.
  3. Generate the CSR and its RSA private key by running the following commands in your terminal:
# Generate an RSA 2048-bit private key
openssl genrsa -out merchant_identity_rsa_private_key.pem 2048

# Create a CSR using the RSA private key
openssl req -new -sha256 \
    -key merchant_identity_rsa_private_key.pem \
    -out merchant_identity_rsa_csr.csr
  1. The second command will prompt you for information to generate the certificate. Fill in the fields the same way as in the previous step:
Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: New York
Locality Name (eg, city) []: New York
Organization Name (eg, company) [Internet Widgits Pty Ltd]: DEUNA test  # Merchant description
Organizational Unit Name (eg, section) []:                            # optional
Common Name (e.g. server FQDN or YOUR name) []: merchant.io.deuna.pay   # Merchant ID
Email Address []:                                                     # optional

A challenge password []:                                              # optional
An optional company name []:                                          # optional
  1. As a result you will get two files that you must keep:
  • merchant_identity_rsa_private_key.pem
  • merchant_identity_rsa_csr.csr
  1. Back in the Apple portal, click Choose File and select the merchant_identity_rsa_csr.csr file you just generated.
  2. Click Continue.
  3. Download and keep the merchant_id.cer certificate generated by Apple.

1.4 Register a domain

  1. Click on the Merchant ID you created.
  2. Under the Merchant Domains section, click Add Domain.
  3. Enter your domain and click Save.
  4. Download the .txt file required for domain verification.

1.5 Verify the domain

  1. Place the downloaded .txt file inside a .well-known folder on your server. When accessing https://<domain>/.well-known/apple-developer-merchantid-domain-association.txt, the server must return the contents of that .txt file.
  2. Go back to the Merchant ID in the Apple portal.
  3. Under the Merchant Domains section, click Verify.
  4. The domain should now show a Verified status.
📘

For testing environments, you can use localhost as the domain when registering credentials in DEUNA.

2. Register credentials in DEUNA with your owns certificates

Once all certificates have been downloaded, you need to extract their contents in PEM format to register them in DEUNA.

  • Merchant name
  • ApplePay Merchant ID: Merchant ID created in Apple Pay, e.g. merchant.com.yourdomain.pay
  • Payment Processing Certificate:
    • For this step you will need the apple_pay.cer file downloaded when registering the Apple Pay Payment Processing Certificate.
    • Run the following commands in your terminal, from the folder where the file is located:
openssl x509 -inform DER -in "apple_pay.cer" -out certificate.pem
openssl x509 -in "certificate.pem" -text -noout
echo -e "const merchantCertificate:"
awk 'NR>1{printf "\\n"}{ printf "%s", $0 }' certificate.pem
echo -e ""
rm certificate.pem
  • El resultado debería en la sección Payment Processing Certificate en el campo Apple Pay Certificate.
-----BEGIN CERTIFICATE-----\nMIIEbDCCBBKgAwIBAgIILCdFbC/W4kcwCgYIKoZIzj0EAwIwgYAxNDAy...\n-----END CERTIFICATE-----
  • Payment Processing Private Key
    • ⚠️ For this step you will need the payment_processing_private_key.pem file generated when creating the CSR for the Apple Pay Payment Processing Certificate.
openssl rsa -in "payment_processing_private_key.pem" -text -noout
echo -e "const merchantPrivateKey:"
awk 'NR>1{printf "\\n"}{ printf "%s", $0 }' payment_processing_private_key.pem
echo -e ""
  • The output should go in the Payment Processing Certificate section, in the Private Key field.
-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg...\n-----END PRIVATE KEY-----
  • Merchant Identity Certificate
    • For this step you will need the merchant_id.cer file downloaded when registering the Apple Pay Merchant Identity Certificate.
openssl x509 -inform DER -in "merchant_id.cer" -out certificate.pem
openssl x509 -in "certificate.pem" -text -noout
echo -e "const merchantCertificate:"
awk 'NR>1{printf "\\n"}{ printf "%s", $0 }' certificate.pem
echo -e ""
rm certificate.pem
  • The output should go in the Merchant Identity Certificate section, in the Apple Pay Certificate field.
-----BEGIN CERTIFICATE-----\nMIIGDTCCBPWgAwIBAgIQKcUD7Csg6A8Fxtg6/9tOyTANBgkqhkiG...\n-----END CERTIFICATE-----
  • Merchant Identity Private Key
    • For this step you will need the merchant_identity_rsa_private_key.pem file generated when creating the CSR for the Apple Pay Merchant Identity Certificate.
openssl rsa -in "merchant_identity_rsa_private_key.pem" -text -noout
echo -e "const merchantPrivateKey:"
awk 'NR>1{printf "\\n"}{ printf "%s", $0 }' merchant_identity_rsa_private_key.pem
echo -e ""
  • The output should go in the Merchant Identity Certificate section, in the Private Key field.
-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCa...\n-----END PRIVATE KEY-----
  • Add Merchant Domains
  • Select the card networks
  • Select allowed auth methods (always select 3DS)

3. Register credentials managed by DEUNA

  • Merchant name
  • ApplePay Merchant ID: Merchant ID created in Apple Pay, e.g. merchant.com.yourdomain.pay
  • Add Merchant Domains
  • Select the card networks
  • Select allowed auth methods (always select 3DS)

Updated about 5 hours ago