Apple Pay
Apple Pay enables customers to authenticate card payments using Touch ID or Face ID. This eliminates the need for them to manually enter their card and shipping details.
Note
If you plan to process Apple Pay payments through an entity outside of the European Economic Area (EEA) or United Kingdom (UK), contact your account manager or [email protected].
Apple Pay transactions benefit from liability shift due to Apple's built-in authentication mechanisms. Additional authentication from the issuer is not required.
To avoid issues with transactions performed on your app or website, you must:
- provide the correct country code in your payment request
- display the final amount on the payment sheet
Information
For more information, see the Apple documentation for Strong Customer Authentication and Complying with regional regulations.
If the issuer returns an ECI value for the transaction, the value will indicate which party is liable. If the issuer does not return an ECI value, the transaction is not eligible for liability shift.
Card networks may downgrade a transaction's liability shift during the authorization stage, despite the ECI value indicating the downgrade occurred during authentication. The liability shift outcome is determined after authorization.
Information
Apple Pay is also available through Flow. Flow enables you to accept payments on your website using Checkout.com's global network of payment methods with a single integration.
Note
If you process Mada cards through Apple Pay outside of Saudi Arabia, you're required to enforce the use of the Visa or Mastercard schemes.
To process Apple Pay payments, you need an Apple merchant ID.
If you process payments on a website, you can leverage Checkout.com's Apple merchant ID to process payments. This option enables you to integrate Apple Pay faster as you don't need an Apple developer account.
If you process payments using your own Apple merchant ID, you need an Apple developer account. See Apple's enrollment requirements for more information.
To process payments on an app, you must own an Apple developer account and create your own merchant ID.
To set up Apple Pay, you need the following:
- A domain with a valid TLS certificate - meaning your domain should start with
https
. - Access to a Secure Shell (SSH) terminal.
- Access to upload files to your server.
To process Apple Pay payments using our merchant ID:
- Contact your account manager or [email protected], and request to be onboarded to Apple Pay under Checkout.com.
- You receive an
apple-developer-merchantid-domain-association.txt
file. - Upload the
.txt
file to your server so it's accessible at the following location:https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
– Replaceyourdomain.com
with the URL of your domain - Call the Enroll a merchant to the Apple Pay Service endpoint, and set the
domain
field to the domain in which you want to process Apple Pay payments.
1{2"domain": "https://yourdomain.com"3}
If you want to process payments on an app, or on a website using your own Apple Pay merchant ID, follow these steps:
- Create a merchant identifier with Apple.
- Create a certificate signing request.
- Create an Apple Pay payment processing certificate.
- Upload the signed payment processing certificate.
- Register a merchant domain.
- Create your Apple Pay certificate and private keys.
- Test Apple Pay certificate and private key validity.
- Integrate Apple Pay.
- In your Apple Developer account, go to the Add Merchant IDs section, select Merchant IDs and select Continue.
- Add a useful description, like
merchant ID for test environment
. - Enter your desired Merchant ID name in the Identifier section. Use a descriptive name to indicate both the domain and the environment you will use it in. For example,
merchant.com.mywebsite.sandbox
.
Information
We recommend that you create separate merchant IDs for your test and live environments.
To create a certificate signing request (CSR), call the Generate a certificate signing request endpoint.
post
https://api.checkout.com/applepay/signing-requests
You can use the protocol_version
field to specify whether to use the EC or RSA protocol for the CSR encryption.
1{2"protocol_version": "ec_v1"3}
1{2"content": "-----BEGIN CERTIFICATE REQUEST-----MIIBSTCB8AIBADCBjzELMAkGA1UEBhMCR0IxDzANBgNVBAgMBkxvbmRvbjEPMA0GA1UEBwwGTG9uZG9uMRUwEwYDVQQKDAxDaGVja291dC5jb20xCzAJBgNVBA8MAklUMRUwEwYDVQQDDAxjaGVja291dC5jb20xIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAY2hlY2tvdXQuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwjiZ410yhHCkwa04OfrPb0e5bqt4FncefJwAbFpcqARTWefYZNvLyYkV68PmAKoO7cthfAFVfoVNqXBEGzjg1TAKBggqhkjOPQQDAgNIADBFAiAcgJLboQK3GBQX/K5ghNzbcw4mnVcVk/rUmkIxu0M28gIhALO01kH13CZzMkAhRhnkeCUPaP+IqUqQaDdZL8d5xgFc-----END CERTIFICATE REQUEST-----"3}
- On your desktop, create a new plain text file and name it
cko.csr
. - Paste the entire value returned in the response's
content
field into the newcko.csr
file and save it. For example, yourcko.csr
file's contents should look similar to the following:
1-----BEGIN CERTIFICATE REQUEST-----MIIBSTCB8AIBADCBjzELMAkGA1UEBhMCR0IxDzANBgNVBAgMBkxvbmRvbjEPMA0GA1UEBwwGTG9uZG9uMRUwEwYDVQQKDAxDaGVja291dC5jb20xCzAJBgNVBA8MAklUMRUwEwYDVQQDDAxjaGVja291dC5jb20xIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAY2hlY2tvdXQuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwjiZ410yhHCkwa04OfrPb0e5bqt4FncefJwAbFpcqARTWefYZNvLyYkV68PmAKoO7cthfAFVfoVNqXBEGzjg1TAKBggqhkjOPQQDAgNIADBFAiAcgJLboQK3GBQX/K5ghNzbcw4mnVcVk/rUmkIxu0M28gIhALO01kH13CZzMkAhRhnkeCUPaP+IqUqQaDdZL8d5xgFc-----END CERTIFICATE REQUEST-----
Information
The CSR has a Time to Live (TTL) period of 24 hours. You must create your Apple Pay payment processing certificate within this timeframe. If you miss the TTL period, you must generate a new CSR.
- Sign in to your Apple Developer account, go to the Merchant IDs list section, and select the Merchant ID you created earlier.
- In the Apple Pay Payment Processing Certificate section, select Create Certificate.
- Respond No to the question about processing in China and select Continue.
- Upload the
cko.csr
file from the previous step and select Continue. - Select Download to retrieve your payment processing certificate. The certificate file name is
apple_pay.cer
.
- Encode the
apple_pay.cer
in base64 using the following command.
1openssl x509 -inform der -in apple_pay.cer -out base64_converted.cer
- The command creates a new file with the name
base64_converted.cer
.
To enable Checkout.com to use the payment certificate to decrypt Apple Pay tokens and convert them to Checkout.com card tokens, call the Upload a payment processing certificate, and set the content
field to the content of the base64_converted.cer
file.
post
https://api.checkout.com/applepay/certificates
1{2"content": "MIIEfTCCBCOgAwIBAgIID/asezaWNycwCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMMK0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yMTA2MTExMzQ0MjVaFw0yMzA3MTExMzQ0MjRaMIGuMS0wKwYKCZImiZPyLGQBAQwdbWVyY2hhbnQuY29tLmNoZWNrb3V0LnNhbmRib3gxQzBBBgNVBAMMOkFwcGxlIFBheSBQYXltZW50IFByb2Nlc3Npbmc6bWVyY2hhbnQuY29tLmNoZWNrb3V0LnNhbmRib3gxEzARBgNVBAsMCkUzMlhCUUs0UTUxFjAUBgNVBAoMDUNoZWNrb3V0IEx0ZC4xCzAJBgNVBAYTAkdCMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEsvyUM9D1cssldH+VPptEn4VAw/Q6ovJuHVlyBSRaPGLHFce04lCiT/xnXOWRkUxyCzQWKhfG2zo19u4s+evx7aOCAlUwggJRMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUhLaEzDqGYnIWWZToGqO9SN863wswRwYIKwYBBQUHAQEEOzA5MDcGCCsGAQUFBzABhitodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxld3dkcmNhMjAxMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4wgcMGCCsGAQUFBwICMIG2DIGzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBieSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHRhbmNlIG9mIHRoZSB0aGVuIGFwcGxpY2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMgb2YgdXNlLCBjZXJ0aWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3RhdGVtZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmljYXRlYXV0aG9yaXR5LzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXd3ZHJjYTIuY3JsMB0GA1UdDgQWBBRNhvr33NDuM4QxBZd16a+ACbHoEzAOBgNVHQ8BAf8EBAMCAygwTwYJKoZIhvdjZAYgBEIMQDdGRjg0REI5MDE5NkVGN0I5RTc4NDZEMjg4NzZCNkJGRDU2RjM4MDlCNzUyNjAzRDM4QzcxNUJFMTY2M0JENEMwCgYIKoZIzj0EAwIDSAAwRQIgTjywMwOrLX3TwDUrPn7yDGL/dhc+VNudv0uGBOWRyXACIQClFQFvgx+hfTwVdHt8klrswpgtZtbYjs74p9GYuc8Puw=="3}
1{2"id": "aplc_hefptsiydvkexnzzb35zrlqgfq",3"public_key_hash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",4"valid_from": "2021-01-01T17:32:28.000Z",5"valid_until": "2025-01-01T17:32:28.000Z"6}
Information
You must have a valid TLS certificate on your domain.
To display the Apple Pay button in your site, you must register and verify all top-level domains and subdomains where you display the button. This step is necessary if you are processing Apple Pay in a webpage.
- Sign in to your Apple Developer account, go to the Merchant IDs list section and select the Merchant ID you created earlier.
- Under the Merchant Domains section, select Add Domain.
- Enter your domain and select Save.
- Select Download and you'll get a
.txt
file. - Upload this file to your server so it's accessible at the following location (replacing
yourdomain.com
with the URL of your domain):https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
. To do this, create a folder called.well-known
in the root directory of your website and put the.txt
file in that folder. - Once you've uploaded the file, select Verify.
- Open a terminal and create a
.csr
and.key
file using the following command:
1openssl req -out uploadMe.csr -new -newkey rsa:2048 -nodes -keyout certificate_sandbox.key
- In the prompt, enter your details, and when asked for a password, leave it blank and select Enter. This will generate two files:
uploadMe.csr
andcertificate_sandbox.key
. - Sign in to your Apple Developer account, go to the Merchant IDs list section and select the merchant ID you created earlier.
- Under the Apple Pay Merchant Identity Certificate section, select Create Certificate.
- Upload the
uploadMe.csr
file you just created from your terminal. - Select Continue and then select Download to get your
.cer
file. It will probably be namedmerchant_id.cer
. - Convert this
.cer
file into a.pem
file so you can use it in your code. Enter the following command in your terminal:
1openssl x509 -inform der -in merchant_id.cer -out certificate_sandbox.pem
Validate your Apple Pay certificate and private key files by requesting an Apple Pay payment session:
1curl -gv \2--data '{3"merchantIdentifier": "merchant.com.mywebsite.sandbox",4"displayName": "merchant id for test environment",5"domainName": "sandbox.mywebsite.com"6}' \7--cert /path/to/certificate_sandbox.pem \8--key /path/to/certificate_sandbox.key \9https://apple-pay-gateway.apple.com/paymentservices/paymentSession
If you followed the above steps correctly, you should now have the following:
- An Apple merchant ID (for example,
merchant.com.mywebsite.sandbox
). - Checkout.com linked to your merchant ID.
- A domain verified by Apple
- A
.key
and a.pem
certificate file.
Information
If you use an ecommerce platform where we support Apple Pay, such as Magento or WooCommerce, the files and certificates you created are enough to complete your integration. Follow the instructions provided by your particular platform.
You can extract the billing address that the customer set up in their Apple Pay wallet for use in your payment requests.
Set the requiredBillingContactFields: ["postalAddress"]
parameter when you create the ApplePaySession
on the front end.
If done correctly, you should see the billing address displayed in the Apple Pay payment sheet. To specify a different billing address that you have stored on file for the customer, add the billingContact
object. For example:
1requiredBillingContactFields: ["postalAddress"],2billingContact: {3givenName: "Jia Tsang",4addressLines: "123 Anywhere St",5locality: "Anytown",6postalCode: "123456",7administrativeArea: "AL",8country: "US"9}
The billing address is included in the object returned in the onpaymentauthorized()
callback, which is sent to your back end and included in your payment request to Checkout.com.
You can extract the email address and phone number that the customer set up in their Apple Pay wallet for use in your payment requests.
Set the requiredShippingContactFields: ["phone", "email"]
parameter when you create the ApplePaySession
on the front end.
If done correctly, you should see the email address and phone number displayed in the Apple Pay payment sheet. To specify a different email address or phone number that you have stored on file for the customer, add the shippingContact
object. For example:
1requiredShippingContactFields: ["name", "phone", "email"],2shippingContact: {3phoneNumber: "555-0100",4emailAddress: "[email protected]"5}
The email address and phone number are included in the object returned in the onpaymentauthorized()
callback, which is sent to your back end and included in your payment request to Checkout.com.
Once you've completed the integration steps, you can display the Apple Pay button and validate an Apple Pay session.
The following diagram shows a successful Apple Pay payment:
