Apple Pay

Apple Pay lets payers pay with a card stored on their Apple device instead of entering card details. Payers can use Apple Pay on iPhone, iPad, Mac, and Apple Watch. For the full list of supported devices, see Apple's compatibility documentation.

On the Checkout page, Apple Pay works with no additional development on your side. On the S2S protocols you obtain the Apple Pay payment token yourself and pass it in the SALE request.

Before your first payment, Apple Pay has to be enabled on your merchant account. There are two ways to do that, and which one applies to you determines whether you need your own Apple Developer account.

Payment method properties

Property	Value
Payment method family	Wallet
Payment confirmation	Customer-initiated
Protocols	Checkout, S2S CARD, S2S APM, Checkout SDK
Token handling	Virtual flow by default, card flow with token decryption
DMS, recurring (MIT), smart routing, cascading	Require card flow and provider support
Two-stage authorization (auth=Y)	S2S APM only, if the connector supports the mode

Payers can use Apple Pay only in the countries and regions Apple lists as participating. Within those, the currencies you can present and the card networks you can accept depend on your acquirer and on the networks enabled for your MID. Contact your account manager for the list that applies to your account.

Which setup applies to you

	Through Akurateco	Your own Apple Developer account
Apple Developer account	Ours	Yours
Apple Merchant ID	Not required	You create it
Merchant Identity Certificate	Managed by us	You generate and provide it
Payment Processing Certificate	Managed by us	You generate and provide it
Domain verification	We register and verify your checkout domains	You download the file from Apple, we host it
What you provide	Your checkout domain names	Merchant ID, certificates, and keys
Scale	Built for registering many merchants	Apple caps the number of Merchant IDs per developer account

Both setups support the same protocols, the same parameters, and the same operations. Nothing in the Accept Apple Pay payments section below changes between them.

Our support team configures your setup. Contact your account manager to confirm which one is active on your account, or to switch.

info

If you already process Apple Pay with your own Apple Developer account, nothing changes for you. Existing configurations keep working and do not need to be migrated.

Set up through Akurateco

In this setup, Akurateco is registered with Apple as the payment platform, and your business is registered under it. You do not create an Apple Developer account, you do not create a Merchant ID, and you do not generate any certificates.

What you provide

Send the following to your account manager or to support:

• Checkout domain names. Every domain and subdomain that displays the Apple Pay button, in production and in testing. For example, example.com, www.example.com, and shop.example.com are three separate entries. Apple allows up to 99 domains per merchant, and you can send them to us in batches rather than all at once.
• Display name. The business name payers see in the Apple Pay sheet.
• Country code. The country your business operates in.

What we do

• Register your business with Apple as a merchant under our payment platform.
• Register and verify each of your checkout domains with Apple.
• Configure the certificates and keys on your merchant account.
• Confirm to you when Apple Pay is live on your account.

note

Do not follow Apple's own merchant onboarding instructions for this setup. You do not need to create a Merchant ID or a Merchant Identity Certificate in an Apple Developer account of your own. Certificates created that way do not work on an account configured through Akurateco.

Domain verification

Apple requires every domain that shows the Apple Pay button to be verified before payments can be processed on it. In this setup we handle verification for you, including hosting the domain association file.

If your checkout is served from a domain you control rather than one of ours, we send you a verification file that must be served from this exact path:

https://your-domain.com/.well-known/apple-developer-merchantid-domain-association

The file must be reachable over HTTPS, returned with HTTP 200, and must stay in place for as long as the domain is in use, because Apple re-checks it periodically. Adding a new checkout domain later means repeating verification for that domain.

Set up with your own Apple Developer account

In this setup you hold the Apple Developer account, you create the Merchant ID, and you generate the certificates. Apple's portal is the authoritative reference for these steps: see Setting up Apple Pay.

In your Apple Developer account:

1. Create a Merchant ID in Certificates, Identifiers & Profiles.
2. Register your domains in Merchant Domains, including the checkout page URL. Download the verification file Apple provides for each domain and send it to support. We host it at /.well-known/apple-developer-merchantid-domain-association on the domain, after which you complete verification on Apple's side.
3. Create a Merchant Identity Certificate. Generate a .csr and .key pair, upload the .csr, create the certificate from it, and download the resulting .pem.
4. Create a Payment Processing Certificate. Generate a second .csr and .key pair and upload the .csr. The .key from this pair is the Processing Private Key, which is what allows the platform to decrypt payment tokens and enables card flow.

note

You can also get the .csr file from the payment provider that processes your Apple Pay payments.

Then enter the data into the admin panel. Go to Merchants, start editing your merchant, open the Wallets tab, and fill in the Apple Pay settings:

Field	Value
Merchant Identifier	The Merchant ID from step 1
Certificate	The .pem file from step 3
Private Key	The .key file from the pair generated in step 3
Processing Private Key	The .key file from the pair generated in step 4, required for token decryption. Paste it as one continuous line, with no spaces or line breaks, using only the text between BEGIN and END.
Country, Shop Name	As set in your Apple Developer account
Merchant Capabilities, Supported Networks	The card networks offered in the Apple Pay sheet

warning

Apple Pay certificates expire and must be renewed before they do. Apple notifies the holder of the Apple Developer account, which in this setup is you. Forward Apple's expiry notice to support well before the expiry date, because Apple Pay stops working on your account as soon as a certificate lapses.

Get the payment token

This applies to the S2S protocols only. On Checkout and with the Checkout SDK, the platform renders the Apple Pay button and gets the token for you.

On the S2S protocols you implement Apple Pay on your own page and get the token yourself. Apple documents the client-side steps in Apple Pay on the Web:

1. Check each payment for Apple Pay availability.
2. Show the Apple Pay button to your payers.
3. Validate the merchant identity.
4. Provide a payment request and create a session.
5. Receive the Apple Pay payment token, which is the paymentData object.

The token you receive from Apple looks like this. You pass it to the platform unchanged:

{
  "paymentData": {
    "data": "YOUR_ENCRYPTED_DATA",
    "signature": "YOUR_SIGNATURE",
    "header": {
      "publicKeyHash": "YOUR_PUBLIC_KEY_HASH",
      "ephemeralPublicKey": "YOUR_EPHEMERAL_PUBLIC_KEY",
      "transactionId": "YOUR_TRANSACTION_ID"
    },
    "version": "EC_v1"
  },
  "paymentMethod": {
    "displayName": "Visa 6244",
    "network": "Visa",
    "type": "credit"
  },
  "transactionIdentifier": "YOUR_TRANSACTION_IDENTIFIER"
}

warning

Send the token as you received it. Do not re-encode, pretty-print, or alter it. The token is signed by Apple and has a short lifetime, so a modified or stale token fails decryption and the payment is rejected with 250003 The payment token signature has expired.

Accept Apple Pay payments

The parameters below are identical in both setups described above.

Checkout

Include applepay in the methods array of the Authentication request. No additional development is required on your side: the platform renders the Apple Pay button and handles the session and the token.

See Payment methods for the Checkout catalogue entry.

S2S CARD

Send digital_wallet and payment_token in the SALE request. When you send a digital wallet token, omit the card data parameters card_number, card_exp_month, card_exp_year, and card_cvv2.

Parameter	Value
digital_wallet	applepay
payment_token	The Apple Pay payment token

Request example

curl -d "action=SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&order_id=ORDER12345&order_amount=1.99&order_currency=USD&order_description=Product&payer_first_name=John&payer_last_name=Doe&payer_address=BigStreet&payer_country=US&payer_state=CA&payer_city=City&payer_zip=123456&[email protected]&payer_phone=199999999&payer_ip=123.123.123.123&term_url_3ds=http://client.site.com/return.php&digital_wallet=applepay&payment_token={"paymentData":{"data":"YOUR_ENCRYPTED_DATA","signature":"YOUR_SIGNATURE","header":{"publicKeyHash":"YOUR_PUBLIC_KEY_HASH","ephemeralPublicKey":"YOUR_EPHEMERAL_PUBLIC_KEY","transactionId":"YOUR_TRANSACTION_ID"},"version":"EC_v1"},"paymentMethod":{"displayName":"Visa 6244","network":"Visa","type":"credit"},"transactionIdentifier":"YOUR_TRANSACTION_IDENTIFIER"}&hash=2702ae0c4f99506dc29b5615ba9ee3c0" https://test.apiurl.com -k

warning

The hash formula is different for wallet payments. When you send payment_token instead of card_number or card_token, use Appendix A, Formula 8, not Formula 1.

S2S APM

Send brand and the token inside parameters.

Parameter	Value
brand	applepay
parameters[paymentToken]	The Apple Pay payment token

Request example

curl -d "action=SALE&client_key=YOUR_CLIENT_KEY&brand=applepay&order_id=ORDER12345&order_amount=100.01&order_currency=USD&order_description=Product&payer_ip=123.123.123.123&return_url=http://client.site.com/return.php&identifier=USER_IDENTIFIER&parameters[paymentToken]={\"paymentData\":{\"data\":\"YOUR_ENCRYPTED_DATA\",\"signature\":\"YOUR_SIGNATURE\",\"header\":{\"publicKeyHash\":\"YOUR_PUBLIC_KEY_HASH\",\"ephemeralPublicKey\":\"YOUR_EPHEMERAL_PUBLIC_KEY\",\"transactionId\":\"YOUR_TRANSACTION_ID\"},\"version\":\"EC_v1\"},\"paymentMethod\":{\"displayName\":\"Visa 6244\",\"network\":\"Visa\",\"type\":\"credit\"},\"transactionIdentifier\":\"YOUR_TRANSACTION_IDENTIFIER\"}&hash=YOUR_HASH" https://test.apiurl.com/post -k

To authorize without capturing, send auth=Y and capture later with action=CAPTURE, or release the hold with action=CREDITVOID. This is available for the wallet brands applepay and googlepay only, and only if the connector supports the mode. See Capture.

Checkout SDK

The SDK renders the Apple Pay button and handles the session. getAvailableBrands() returns applepay when Apple Pay is available for the payer's device and your configuration. See Checkout SDK for branding.

Virtual flow and card flow

By default, Apple Pay payments are processed as virtual payments. In this mode card details are not stored, and functionality is limited for DMS payments and for creating recurring transactions.

Card flow gives you more:

• Post-transaction operations, such as capture in DMS mode.
• Recurring payments (MIT), scheduled or on demand.
• Smart routing for optimized payment processing.
• Payment cascading for improved success rates.

To use card flow, both of the following must be true:

• The Processing Private Key is configured on your merchant account, which enables token decryption.
• Your payment provider supports card flow processing. Contact support to check.

When both are met, the platform decrypts the Apple Pay token during payment and stores the decrypted card data for future transactions. You can view the decrypted card details in the Transaction Details section of the admin panel.

If your provider supports card flow but does not accept decrypted data, the platform can still store the card details for processing, but smart routing and cascading are not available.

warning

The behaviour when a requirement is not met depends on the protocol. On the Checkout protocol the payment falls back to the virtual flow. On the S2S CARD protocol the SALE request returns an error.

In the transaction status response, digital_wallet reports the wallet provider used for the payment. When the token was decrypted, pan_type tells you which card number you received: DPAN (Digital Primary Account Number) or FPAN (Funding Primary Account Number).

Test Apple Pay

The platform's standard test cards do not work with Apple Pay. Apple Pay needs a real card in a real Apple Wallet, on a supported device, on a page served over HTTPS from a verified domain. The sandbox card scenarios in Testing and sandbox therefore do not apply to the wallet itself.

To test end to end:

• Use a supported Apple device with a card added to Wallet, in Safari.
• Serve your page over HTTPS from a domain that has been verified for Apple Pay. The Apple Pay button does not render on an unverified domain.
• Send the resulting token to the sandbox base URL with your test credentials, so no real money moves.

Apple also provides an Apple Pay demo and a sandbox testing programme with test cards for Apple's own sandbox accounts.

Troubleshooting

Symptom	Likely cause
The Apple Pay button does not render	The domain is not verified, the page is not served over HTTPS, the device or browser does not support Apple Pay, or no card is provisioned in Wallet.
204018 Payment digital wallet not supported	The MID does not accept Apple Pay. Enable the wallet on the MID, or route the payment to a MID that supports it.
250003 The payment token signature has expired	The token reached the platform after its signature expired, or it was altered in transit. Obtain a fresh token and send it unchanged.
The payment is processed as virtual when card flow was expected	The Processing Private Key is not configured, or the provider does not support card flow.
The hash is rejected on a wallet SALE	Formula 1 was used. Wallet payments that send payment_token use Formula 8.

See also API error reference and Troubleshooting.

Support

For anything on this page, including which setup is active on your account, switching between setups, adding a new checkout domain, or renewing a certificate, contact your account manager or raise a request with support.