Apple Pay
Last updated: May 31, 2023
Start seamlessly accepting credit card payments from your customers via Touch ID and Face ID, eliminating the need for them to manually enter their card and shipping details.
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 instead.
For Apple Pay liability shift eligibility, refer to our 3D Secure page.
Before you can accept Apple Pay payments, you need to set up and configure Apple Pay.
Note
If you plan to process Apple Pay payments through an entity outside the European Economic Area (EEA) or United Kingdom (UK), contact your Account Manager or Integration Engineer.
To start setting up Apple Pay, you need the following:
- an Apple Developer account (learn more about enrollment requirements)
- a domain with a valid SSL certificate (meaning your domain should start with
https
) - access to a Secure Shell (SSH) terminal
- access to your server's files, so you can upload files to your server
Information
We recommend that you create separate merchant IDs for your test environment and for your live/production environment.
- 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. We recommend that you use a descriptive name to indicate both the domain and the environment you will use it in, like
merchant.com.mywebsite.sandbox
.
Next, you need to generate a certificate signing request using the following endpoint. You'll receive a .csr
file in the response that you'll need to upload to your Apple Developer account in the next step.
To get a detailed view of all required and optional fields, see our API reference.
post
https://api.checkout.com/applepay/signing-requests
1curl --location --request POST 'https://api.sandbox.checkout.com/applepay/signing-requests' \2--header 'Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxx' \
1{2"content": "--- --BEGIN CERTIFICATE REQUEST--- --MIIBSTCB8AIBADCBjzELMAkGA1UEBhMCR0IxDzANBgNVBAgMBkxvbmRvbjEPMA0GA1UEBwwGTG9uZG9uMRUwEwYDVQQKDAxDaGVja291dC5jb20xCzAJBgNVBA8MAklUMRUwEwYDVQQDDAxjaGVja291dC5jb20xIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAY2hlY2tvdXQuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwjiZ410yhHCkwa04OfrPb0e5bqt4FncefJwAbFpcqARTWefYZNvLyYkV68PmAKoO7cthfAFVfoVNqXBEGzjg1TAKBggqhkjOPQQDAgNIADBFAiAcgJLboQK3GBQX/K5ghNzbcw4mnVcVk/rUmkIxu0M28gIhALO01kH13CZzMkAhRhnkeCUPaP+IqUqQaDdZL8d5xgFc--- --END CERTIFICATE REQUEST--- --"3}
- Log in to your Apple Developer account, go to the Merchant IDs list section, and select the merchant ID you created in step 1.
- In the Apple Pay Payment Processing Certificate section (make sure you’re not in the Apple Pay Merchant Identity Certificate section), select Create Certificate.
- Respond No to the question about processing in China and select Continue.
- Upload the
.csr
file from the previous step and select Continue. - Select Download to get your payment processing certificate – a
.cer
file.
Once you've generated the payment processing certificate, you need to upload it using the following endpoint. We use this certificate to decrypt Apple Pay tokens and turn them into Checkout.com card tokens you can use to request a payment.
To get a detailed view of all required and optional fields, see our API reference.
Information
The .cer
file you downloaded in step 3 needs to be base64 encoded so you can pass the content into the /applepay/certificates
endpoint.
To convert the .cer
file to a base64 string, use the following command:
1openssl x509 -inform der -in apple_pay.cer -out base64_converted.cer
post
https://api.checkout.com/applepay/certificates
1curl --location --request POST 'https://api.sandbox.checkout.com/applepay/certificates' \2--header 'Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxx' \3--header 'Content-Type: application/json' \4--data-raw '{5"content": "MIIEfTCCBCOgAwIBAgIID/asezaWNycwCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMMK0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yMTA2MTExMzQ0MjVaFw0yMzA3MTExMzQ0MjRaMIGuMS0wKwYKCZImiZPyLGQBAQwdbWVyY2hhbnQuY29tLmNoZWNrb3V0LnNhbmRib3gxQzBBBgNVBAMMOkFwcGxlIFBheSBQYXltZW50IFByb2Nlc3Npbmc6bWVyY2hhbnQuY29tLmNoZWNrb3V0LnNhbmRib3gxEzARBgNVBAsMCkUzMlhCUUs0UTUxFjAUBgNVBAoMDUNoZWNrb3V0IEx0ZC4xCzAJBgNVBAYTAkdCMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEsvyUM9D1cssldH+VPptEn4VAw/Q6ovJuHVlyBSRaPGLHFce04lCiT/xnXOWRkUxyCzQWKhfG2zo19u4s+evx7aOCAlUwggJRMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUhLaEzDqGYnIWWZToGqO9SN863wswRwYIKwYBBQUHAQEEOzA5MDcGCCsGAQUFBzABhitodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxld3dkcmNhMjAxMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4wgcMGCCsGAQUFBwICMIG2DIGzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBieSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHRhbmNlIG9mIHRoZSB0aGVuIGFwcGxpY2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMgb2YgdXNlLCBjZXJ0aWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3RhdGVtZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmljYXRlYXV0aG9yaXR5LzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXd3ZHJjYTIuY3JsMB0GA1UdDgQWBBRNhvr33NDuM4QxBZd16a+ACbHoEzAOBgNVHQ8BAf8EBAMCAygwTwYJKoZIhvdjZAYgBEIMQDdGRjg0REI5MDE5NkVGN0I5RTc4NDZEMjg4NzZCNkJGRDU2RjM4MDlCNzUyNjAzRDM4QzcxNUJFMTY2M0JENEMwCgYIKoZIzj0EAwIDSAAwRQIgTjywMwOrLX3TwDUrPn7yDGL/dhc+VNudv0uGBOWRyXACIQClFQFvgx+hfTwVdHt8klrswpgtZtbYjs74p9GYuc8Puw=="6}'
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 SSL certificate on your domain (meaning it begins with https
).
- Log in to your Apple Developer account, go to the Merchant IDs list section and select the merchant ID you created in step 1.
- 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.txt. 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 this 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. You will get a
.csr
and.key
file. Keep the.key
file at hand. - Log in to your Apple Developer account, go to the Merchant IDs list section and select the merchant ID you created in step 1.
- Under the Apple Pay Merchant Identity Certificate section (make sure you're not in the Apple Pay Payment Processing Certificate section), select Create Certificate.
- Upload the
.csr
file you just created from your terminal. It should be calleduploadMe.csr
if you copy-pasted the command. - 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
If you followed the above steps correctly, you should now have the following:
- a 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
We recommend that you repeat the above steps so you have a merchant ID, domain (it can be the same domain) and certificates for your test environment and your production environment. You should use descriptive names for each environment to avoid mismatches.
Information
If you use an ecommerce platform where we support Apple Pay, like Magento or WooCommerce, the files and certificates you got in the configuration process above are enough to complete your integration. Just follow the instructions provided by your particular platform.
Follow Apple Pay's integration documentation to integrate Apple Pay:
- Apple Pay Web — see a demo
- Apple Pay Mobile
Once you've completed the integration steps, you will be able to display the Apple Pay button and validate an Apple Pay Session (required for the web version).
For an in-depth view, see the following payment flow walkthrough:
Here's a diagram of the full payment flow:

Once you've set up and configured Apple Pay, you're ready to accept Apple Pay payments through our payment gateway.
After your customer validates their transaction with biometrics, Apple will generate a payment token.
The first step in processing an Apple Pay transaction is to convert this Apple Pay token into a Checkout.com card token. Alternatively, if you want to decrypt the Apple Pay token yourself and process a payment, skip to step 2.
For the full API specification, see the API reference.
post
https://api.checkout.com/tokens
1{2"type": "applepay",3"token_data": {4"version": "EC_v1",5"data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",6"signature": "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",7"header": {8"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",9"publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",10"transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"11}12}13}
1{2"type": "applepay",3"token": "tok_ymu4qlccztkedmd6b7c3hcf6ae",4"expires_on": "2019-10-21T10:48:35Z",5"expiry_month": 8,6"expiry_year": 2023,7"scheme": "Visa",8"last4": "6222",9"bin": "481891",10"card_type": "DEBIT",11"card_category": "CONSUMER",12"issuer": "Test Bank",13"issuer_country": "GB",14"product_id": "F",15"product_type": "Visa Classic"16}
Using the token (tok_...)
you got in the response above, make a standard payment request.
For the full API specification, see the API reference.
post
https://api.checkout.com/payments
1{2"source": {3"type": "token",4"token": "tok_ymu4qlccztkedmd6b7c3hcf6ae"5},6"amount": 6500,7"currency": "USD"8}
If you get a 201 Success
response and the approved
field is true
, your payment was successful. If the transaction failed, it's likely that the payment request was made with an invalid/expired card, or a valid card with an insufficient available balance.
To test Apple Pay payments, you'll need the following:
- an Apple Pay compatible device
- a sandbox Apple Pay wallet, which you can add a test card to (see Test Cards for Apps and the Web on Apple Pay's sandbox testing page)
For more information about testing, see our testing resources.
Note
When testing in a sandbox environment, you cannot use a real Apple Pay wallet with real cards.
If something goes wrong, make sure you're using the correct keys, merchant ID and certificates. This is the most common issue we encounter. We recommend using descriptive names for your merchant IDs to clearly separate between your test and production environments.
If you don't have a card in your Apple Pay wallet, or you have a card that is not accepted based on the settings configured for Apple Pay (supported networks), your Apple Pay button might not be displayed if you display it conditionally (session.canMakePaymentsWithActiveCard(...))
.
When validating the Apple Pay Session, make sure that:
- you're using the correct merchant ID, and the correct
.key
and.pem
certificates associated with it - if you configured your merchant ID in sandbox, you're using the sandbox environment