Apple Pay

Start seamlessly accepting credit card payments from your customers via Touch ID and Face ID, eliminating the need for them to manually type in their card and shipping details.

Apple Pay is automatically enabled on your account, unless you process payments in UAE or Saudi Arabia. If you operate in these regions, contact your customer success manager to activate Apple Pay.

Before you start

Before you get started with Apple Pay, you will need the following:

  • An Apple Developer account. Sign up for one here.
  • 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.

Configure Apple Pay

Step 1: Create your merchant IDs in your Apple Pay Developer account

We recommend that you create separate merchant IDs for your test environment and for your live/production environment.

  1. In your Apple Developer account, go to the Add Merchant IDs section, select Merchant IDs and click Continue.

  2. Add a useful description, like merchant id for test environment.

  3. Type 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.

Step 2: Add Checkout.com as a payment processor

  1. Log in to your Hub account, go to Settings > Apple Pay and click New Certificate.

  2. Click Download your certificate signing request. This will give you .csr file that you'll need for your Apple Developer account.

  3. Click Continue until step 3 and then leave this page open.

  4. Log in to your Apple Developer account, go to the Merchant IDs list section, and click on the merchant ID you created in step 1.

  5. In the Apple Pay Payment Processing Certificate section (make sure you're not in the Apple Pay Merchant Identity Certificate section), click Create Certificate.

  6. Respond No to the question about processing in China and click Continue.

  7. Upload the .csr file from earlier and click Continue.

  8. Click Download to get your .cer file.

  9. Go back to your Hub account and upload this .cer file.

Step 3: Validate your domain

You must have a valid SSL certificate on your domain (meaning it begins with https).

  1. Log in to your Apple Developer account, go to the Merchant IDs list section and click on the merchant ID you created in step 1.

  2. Under the Merchant Domains section, click Add Domain.

  3. Enter your domain and click Save.

  4. Click Download and you'll get a .txt file.

  5. 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.

  6. Once you've uploaded the file, click Verify.

Step 4: Create your Apple Pay certificates

  1. Open a terminal and create a .csr and .key file using this command:
    openssl req -out uploadMe.csr -new -newkey rsa:2048 -nodes -keyout certificate_sandbox.key.

  2. In the prompt, enter your details, and when asked for a password, leave it blank and click Enter. You will get a .csr and .key file. Keep the .key file at hand.

  3. Log in to your Apple Developer account, go to the Merchant IDs list section and click on the merchant ID you created in step 1.

  4. Under the Apple Pay Merchant Identity Certificate section (make sure you're not in the Apple Pay Payment Processing Certificate section), click Create Certificate.

  5. Upload the .csr file you just created from your terminal. It should be called uploadMe.csr if you copy-pasted the command.

  6. Click Continue and then click Download to get your .cer file. It will probably be named merchant_id.cer.

  7. Convert this .cer file into a .pem file so you can use it in your code. Enter the following command in your terminal:
    openssl x509 -inform der -in merchant_id.cer -out certificate_sandbox.pem

Step 5: Configuration outcome

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.

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.

Integrate with Apple Pay

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:

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).

If you're struggling, watch this payment flow walkthrough:

Here's a diagram of the full payment flow:

Click to enlarge.

Click to enlarge.

Integrate with Checkout.com

Once you've configured and integrated with Apple Pay, you're ready to accept Apple Pay payments through our payment gateway.

If you plan to process Apple Pay payment through an entity outside the European Economic Area (EEA), please contact your customer success manager or integration engineer.

Supporting Mada cards
Within Saudi Arabia, Mada cards can be processed in much the same way as other cards with Apple Pay, but you need to make sure that the device's payments permission is enabled for your merchant ID, and include Mada in the supportedNetworks array.

Step 1: Generate a Checkout.com token from the Apple Pay token

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.

The request

Endpoints

Live

https://api.checkout.com/tokens

Sandbox

https://api.sandbox.checkout.com/tokens

Header parameters

Header
Value

Authorization
Required

public key

Use the valid public key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

Field name
Description

type
String
required

The type of card details to be tokenized. Set this to applepay.

token_data
Object
required

The Apple Pay payment token.

token_data.version
String
required

Version information about the payment token. The token uses EC_v1 for ECC-encrypted data, and RSA_v1 for RSA-encrypted data.

token_data.data
String
required

Encrypted payment data. Base64 encoded as a string.

token_data.signature
String
required

Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.

token_data.header
Object
required

Additional version-dependent information used to decrypt and verify the payment.

Request example

{
  "type": "applepay",
  "token_data": {
    "version": "EC_v1",
    "data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",
    "signature": "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",
    "header": {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",
      "publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
      "transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
    }
  }
}

The response

Response example

{ 
  "type": 'applepay',
  "token": 'tok_ymu4qlccztkedmd6b7c3hcf6ae',
  "expires_on": '2019-10-21T10:48:35Z',
  "expiry_month": 8,
  "expiry_year": 2023,
  "scheme": 'Visa',
  "last4": '6222',
  "bin": '481891',
  "card_type": 'Debit',
  "card_category": 'Consumer',
  "issuer": 'HSBC BANK PLC',
  "issuer_country": 'GB',
  "product_id": 'F',
  "product_type": 'Visa Classic'
}

Supporting Mada cards
If accepting Mada cards via Apple Pay, do not include the supportsEMV value in the merchantCapabilities array, otherwise it may cause a failure with a 20030 format error.

Step 2: Request a payment

Using the token (tok_...) you got in the response above, make a standard payment request.

The request

Endpoints

Live

https://api.checkout.com/payments

Sandbox

https://api.sandbox.checkout.com/payments

Header parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

The table below describes the minimum recommended fields. For the full API specification, see the API reference.

Field name
Description

source
Object
required

Details about the payment source.

source.type
String
required

The type of payment source. Set this to token.

source.token
String
required

The token you got in the response of step 2.

amount
integer
required

The payment amount in your chosen currency.
The format depends on the currency. For more information, see calculating the value.

currency
String
required

A three-letter ISO currency code representing the currency of the payment.

Request example

{
  "source": {
    "type": "token",
    "token": "tok_ymu4qlccztkedmd6b7c3hcf6ae"
  },
  "amount": 6500,
  "currency": "USD"
}

The response

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.

If you want to decrypt the Apple Pay token yourself and process a payment, follow our pay with a pre-decrypted token guide.

Testing Apple Pay

Before you start

To test Apple Pay payments, you'll need the following:

Apple Pay test cards

Once you've got a compatible device and a sandbox Apple Pay wallet, you can add one of the following test cards to it. See our testing guide for more information.

Card
Number
Expiry
CVV

Visa

4761 1200 1000 0492

11/2022

533

Mastercard

5204 2477 5000 1471

11/2022

111

Troubleshooting

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.

Displaying the Apple Pay button

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(...)).

Validating the Apple Pay Session

When validating the Apple Pay Session, keep note of the following:

  • Make sure you're using the correct merchant ID, and the correct .key and .pem certificates associated with it.
  • If you process payments for more than one business with us, make sure you are using the correct merchant ID and keys for each business.
  • The same goes for the environment; if you configured your merchant ID in sandbox, make sure you are using the sandbox environment.

Making a payment

If you are processing payments in UAE or Saudi Arabia, make sure you contact your customer success manager so they can enable Apple Pay on your account.

Also, if you configured Apple Pay for one of your businesses, but then tried to send a payment request using the keys for another of your businesses, you may get an error.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].

Updated 13 days ago

Apple Pay


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.