Apple Pay

Start seamlessly accepting credit card payments and eliminate the need for your customers to type card and shipping details manually. Apple Pay payments are authorized through Touch ID and Face ID.

To enable Apple Pay in the UAE or Saudi Arabia, please request activation from your customer success manager.

Overview

Apple Pay integration and payments can be simplified into a three-step method:

  1. Integrate with Apple Pay
  2. Generate an Apple Pay token
  3. Request a payment using Apple Pay

Additionally, we support using pre-decrypted Apple Pay tokens to request a payment.

Please note:
Apple Pay payments using Mastercard and American Express enjoy a liability shift to the card issuer — similar to 3-D secure payments. Please be aware that although this is a known practice, the issuers are not bound by these terms and can change the liability agreement at any time.

Before you start

To get started with Apple Pay payments, you must first download your Certificate Signing Request from the Hub and upload it to the Apple Developer Center.

You can find step-by-step instructions for this under Settings > Apple Pay in the Hub.

Step 1: Integrate with Apple Pay

To process Apple Pay payments, you must configure your Apple Developer account, complete the certification process, and enhance your iOS app or website to have the capability to access Apple Pay payments.

For Apple Pay configuration resources, please refer to the following:

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 2: Generate an Apple Pay token

By using this endpoint, you can support Apple Pay on your iOS app and website.

The request

Use the details below to set up your 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
String
required

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

Request example

This following code snippet is an example of the request body for an Apple Pay payment.

{
  "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

The token returned in the response can be used to request a payment in step 3.

{
  "type": "applepay",
  "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
  "expires_on": "2018-10-22T15:10:42Z"
}

Step 3: Request a payment using Apple Pay

Once you have the token, you can request a payment. Take the token from the previous response and use it in the body of a card token payment request from your application or website's backend server.

The currency and amount fields are required for Apple Pay payments. These will need to be added to the card token payment request when performing a charge.

Payments with pre-decrypted tokens

We support the ability to make payments using Apple Pay tokens that you have decrypted. To make use of this feature, you can use the network_token source type and specify the token_type as applepay. This source type allows you to provide the details about the token, as well as the cryptogram and ECI value obtained from the Apple Pay token.

The request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the request a card payment.

Content-Type
Required

application/json

Body parameters

Field name
Description

token
String
required

The network token PAN.

expiry_month
String
required

The two-digit expiry month of the token.

expiry_year
String
required

The four-digit expiry year of the token.

token_type
String
required

The type of token. Set this to applepay.

eci
String
required

For VISA only:
The Electronic Commerce Indicator security level associated with the token. Required unless the previous_payment_id is specified.

For more information, see stored card details.

cryptogram
String
required

For VISA only:
Cryptographic identifier used by card schemes to validate the token verification result. Required unless the previous_payment_id is specified.

For more information, see stored card details.

Request example

This code snippet is an example of the request body — not all fields are required, so you can custom build your request based on the information you need.

{
  "source": {
    "type": "network_token",
    "token": "4242424242424242",
    "token_type": "applepay",
    "expiry_month": "10",
    "expiry_year": "2025",
    "eci": "06",
    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA",
  },
  "amount": 1000,
  "currency": "USD",
}

The response

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

If you received a 202 response, the payment requires a redirect. For example, if the payment is 3-D Secure.

A successful response will include a payment_account_reference value, which is a unique reference to the underlying card for network tokens. If the card scheme provided us with an eci value, it will be included in the response. The value indicates the security level that the card scheme decided to request the payment with.

Apple Pay test cards for sandbox

Apple Pay charges can be tested and simulated by using either one of the test cards below. For additional information, please refer to our testing guide. Standard test cards will not work with Apple Pay.

Card
Number
Expiry
CVV

Visa

4761 1200 1000 0492

11/2022

533

Mastercard

5204 2477 5000 1471

11/2022

111

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.

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.