Apple Pay for Payment Setup API

Last updated: June 17, 2026

To process Apple Pay payments using the Payment Setup API, you need your own Apple developer account, and an Apple merchant ID.

See Apple's enrollment requirements for more information.

To set up Apple Pay, you need the following:

An Apple developer account.
A domain with a valid TLS certificate (your domain must start with https).
Access to a Secure Shell (SSH) terminal.
Access to upload files to your server.

To process payments on an app or on a website using the Payment Setup API, 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 > 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. For example, merchant.com.mywebsite.sandbox.

Information

You must create separate merchant IDs for your sandbox and production environments.

To create a certificate signing request (CSR), call the Generate a certificate signing request endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.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 new cko.csr file and save it. For example, your cko.csr file's contents 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 time frame. 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 our card tokens, call the Upload a payment processing certificate, and set the content field to the content of the base64_converted.cer file.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.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

Your domain must have a valid TLS certificate.

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're 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 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. The command generates two files: uploadMe.csr and certificate_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. The file is typically named merchant_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

After completing the previous steps, you 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, the billing address is 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: {
3  givenName: "Jia Tsang",
4  addressLines: "123 Anywhere St",
5  locality: "Anytown",
6  postalCode: "123456",
7  administrativeArea: "AL",
8  country: "US"
9}

The billing address is returned in the object in the onpaymentauthorized() callback, which you can send to your back end to include in your payment request to us.

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, the email address and phone number are 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: {
3  phoneNumber: "555-0100",
4  emailAddress: "jia.tsang@example.com"
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 us.

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:

To accept Apple Pay payments, you must:

Create a payment setup.
Update the payment setup with the Apple Pay token.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Apple Pay payment",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  }
12}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "GBP",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Apple Pay payment",
9  "payment_methods": {
10    "applepay": {
11      "status": "action_required",
12      "flags": [
13        "token_or_token_data_required"
14      ]
15    }
16  },
17  "available_payment_methods": [
18    "applepay"
19  ],
20  "settings": {
21    "success_url": "https://example.com/payments/success",
22    "failure_url": "https://example.com/payments/failure"
23  }
24}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

For Apple Pay, payment_methods contains the following fields:

status – The status of the payment method.
flags – An array of error codes or indicators that highlight missing or invalid information.

When the customer selects Apple Pay as the payment method, Apple generates a payment token. To process a payment using the Apple Pay token, you can:

Convert it to a Checkout.com card token
Decrypt it and use the token data

Call the Update a payment setup endpoint to submit the token. Provide the following fields, depending on the token you use:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Required
`processing_channel_id` string	The processing channel's unique identifier. Pattern: `^(pc)_(\w{26})$` Required
`settings.failure_url` string	The URL to redirect the customer after a failed authorization. Format: uri Required
`settings.success_url` string	The URL to redirect the customer after a successful authorization. Format: uri Required
`payment_methods.applepay.token` object	The Checkout.com Apple Pay token. Required
`payment_methods.applepay.token.id` string	The token identifier, prefixed by `tok_`. Pattern: `^(tok)_(\w{26})$` Required
`payment_methods.applepay.token.expires_on` string	The date and time at which the token expires. Format: date-time
`payment_methods.applepay.account_holder` object	The Apple Pay account holder details.
`payment_methods.applepay.account_holder.first_name` string	The account holder's first name.
`payment_methods.applepay.account_holder.last_name` string	The account holder's last name.
`payment_methods.applepay.account_holder.middle_name` string	The account holder's middle name.
`payment_methods.applepay.account_holder.type` string	Supported values: `individual` `corporate` `government`
`payment_methods.applepay.account_holder.account_name_inquiry` boolean	Indicates whether to perform an account name inquiry with the card scheme (Visa or Mastercard).
`payment_methods.applepay.phone` object	The customer's phone number details.
`payment_methods.applepay.phone.country_code` string	The international dialing code for the customer's phone number.
`payment_methods.applepay.phone.number` string	The customer's phone number.
`payment_methods.applepay.store_for_future_use` boolean	Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Apple Pay payment",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  },
12  "payment_methods": {
13    "applepay": {
14      "token": {
15        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
16        "expires_on": "2026-09-15T16:12:05Z"
17      }
18    }
19  }
20}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "GBP",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Apple Pay payment",
9  "payment_methods": {
10    "applepay": {
11      "status": "ready",
12      "token": {
13        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
14        "expires_on": "2026-09-15T16:12:05Z"
15      },
16      "flags": []
17    }
18  },
19  "available_payment_methods": [
20    "applepay"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

The response returns a ready status when the token has been successfully validated. The payment is ready to confirm.

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Required
`processing_channel_id` string	The processing channel's unique identifier. Pattern: `^(pc)_(\w{26})$` Required
`settings.failure_url` string	The URL to redirect the customer after a failed authorization. Format: uri Required
`settings.success_url` string	The URL to redirect the customer after a successful authorization. Format: uri Required
`payment_methods.applepay.token_data` object	The Apple Pay payment token data object, returned by the Apple Pay API. Required
`payment_methods.applepay.token_data.version` string	The version of the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data. Required
`payment_methods.applepay.token_data.data` string	The encrypted payment data, Base64-encoded. Required
`payment_methods.applepay.token_data.signature` string	The signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm. Required
`payment_methods.applepay.token_data.header` object	Additional version-dependent information used to decrypt and verify the payment. Required
`payment_methods.applepay.token_data.header.ephemeral_public_key` string	The ephemeral public key.
`payment_methods.applepay.token_data.header.public_key_hash` string	The public key hash.
`payment_methods.applepay.token_data.header.transaction_id` string	The transaction ID.
`payment_methods.applepay.account_holder` object	The Apple Pay account holder details.
`payment_methods.applepay.account_holder.first_name` string	The account holder's first name.
`payment_methods.applepay.account_holder.last_name` string	The account holder's last name.
`payment_methods.applepay.account_holder.middle_name` string	The account holder's middle name.
`payment_methods.applepay.account_holder.type` string	Supported values: `individual` `corporate` `government`
`payment_methods.applepay.account_holder.account_name_inquiry` boolean	Indicates whether to perform an account name inquiry with the card scheme (Visa or Mastercard).
`payment_methods.applepay.phone` object	The customer's phone number details.
`payment_methods.applepay.phone.country_code` string	The international dialing code for the customer's phone number.
`payment_methods.applepay.phone.number` string	The customer's phone number.
`payment_methods.applepay.store_for_future_use` boolean	Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Apple Pay payment",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  },
12  "payment_methods": {
13    "applepay": {
14      "token_data": {
15        "version": "EC_v1",
16        "data": "jMvlopbdmvRYOCSOdzmvvYrBmco8CLAVZHOFgKeVEtFdHHIm...",
17        "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgA...",
18        "header": {
19          "ephemeral_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMr6/nWeR6i1m...",
20          "public_key_hash": "fs98t0RqW8mMsSb7jdz6q7lg+0a1sKvXFTlckNN/DVc=",
21          "transaction_id": "a86b32a8009c49c4235c6b2beda29c885298588802fa81b83c8764a0d68a9eb9"
22        }
23      }
24    }
25  }
26}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "GBP",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Apple Pay payment",
9  "payment_methods": {
10    "applepay": {
11      "status": "ready",
12      "token": {
13        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
14        "expires_on": "2026-09-15T16:12:05Z"
15      },
16      "flags": []
17    }
18  },
19  "available_payment_methods": [
20    "applepay"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

The response returns a ready status when the token data is successfully validated and the payment is ready to confirm.

Information

The API returns payment_methods.applepay.status: unavailable for all non-validation technical failures occurring during the tokenization process.

When the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
applepay as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/applepay

Apple Pay for Payment Setup API

Before you start

Set up Apple Pay

Create a merchant identifier

Information

Create a certificate signing request

Information

Request example

Response example

Information

Create a processing certificate

Upload the signed payment processing certificate

Information

Request example

Response example

Register a merchant domain

Information

Create your Apple Pay certificate and private keys

Test Apple Pay certificate and private key

Integrate Apple Pay

Information

Extract customer billing address

Extract customer email address and phone number

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Request example

Response example

Information

Confirm the payment