Apple Pay for API only

Last updated: November 6, 2024

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

To process Apple Pay payments in Kuwait, you must use the KNET network. For the integration instructions, see Apple Pay via KNET.

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 Request a payment.

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.

Although the field is optional, including the customer's billing address in your payment requests can help to:

reduce interchange fees
enable the issuer to perform Address Verification Service (AVS) checks
improve acceptance rates

Similarly, including the customer's email address and phone number in your payment requests can help to enrich data for reporting and fraud screening purposes.

You can use your front end to extract the customer's billing address, email address, and phone number from their Apple Pay Wallet, and include them in your 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  "billing_address":{
7    "address_line1": "123 Anywhere St.",
8    "city": "Anytown",
9    "state": "AL",
10    "zip": "123456",
11    "country": "US"
12  },
13  "phone": {
14    "country_code": "1",
15    "number": "555-0100"
16  },
17  "customer": {
18    "email": "[email protected]"
19  },
20  "amount": 6500,
21  "currency": "USD"
22}

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 make a payment using an Apple Pay token that you have decrypted, 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.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "network_token",
4    "token": "4242424242424242",
5    "token_type": "applepay",
6    "expiry_month": "10",
7    "expiry_year": "2025",
8    "eci": "06",
9    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA"
10  },
11  "amount": 1000,
12  "currency": "USD"
13}

If the approved field is true, your authorization was successful. 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.

Information

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.

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

Apple Pay for API only

Payment Flow

Generate a Checkout.com token from the Apple Pay token

Request example

Response example

Request a payment

Request example

Response example

Request example

Response example

Information

Testing Apple Pay

Note

Troubleshooting

Displaying the Apple Pay button

Validating the Apple Pay Session