Apple Pay

This page is subject to change. Apple Pay support is under development. Details here can change until the integration is finalized.

Overview and Prerequisites

Apple Pay lets your customers pay with a card from their Apple Wallet. Your customer authorizes the payment in Apple's payment sheet, and Apple returns encrypted payment data. You send that data to Interchecks. Interchecks decrypts it, creates the payment account, and creates the transaction in one call.

Apple Pay works with both AFT and OCT transactions.

How you integrate

You build the Apple Pay experience in your own checkout and call the Interchecks API to complete the payment. You write Apple Pay JS code to show the Apple Pay button and open the payment sheet.

The flow at a glance

Merchant Validation

Your page shows the Apple Pay button and opens the payment sheet.
Your page asks your server for a merchant session, and your server requests it from Interchecks.
Your page passes the signed merchant session from Interchecks to Apple Pay JS, and your customer authorizes the payment.

Transaction Endpoint

Apple returns the payment object to your page.
Your page sends the payment object to your server, which sends it to Interchecks to create the transaction.
Your server handles the response.

Prerequisites

Complete these steps before you integrate. Interchecks registers you as an Apple Pay merchant and manages your Merchant ID and certificates, so you do not need your own Apple Developer account.

Step	Owner	Notes
Onboard with Interchecks	You	Required before you integrate.
Create the recipient with Create Recipient	You	The recipient must exist before you create an Apple Pay transaction.
Tell Interchecks every domain and subdomain that shows the Apple Pay button	You	Do this before you call Merchant Validation. Interchecks adds each domain to your Apple Pay settings and verifies it once you host the file. A domain that is not registered returns `ERR_APPLE_PAY_DOMAIN_NOT_REGISTERED`.
Host Apple's domain-verification file on each of those domains	You	Interchecks supplies one file, the same for every domain. Host it at `https://<domain>/.well-known/apple-developer-merchantid-domain-association`, with no file extension. Verification is file-based over HTTPS, and there is no DNS option. A domain Apple has not verified returns `ERR_APPLE_PAY_DOMAIN_NOT_VERIFIED`.
Register you as an Apple Pay merchant and hold the certificates	Interchecks	Interchecks registers you as an Apple Pay merchant with your own merchant ID, and holds the certificates on your behalf.

You never receive or manage a certificate. Interchecks manages the full certificate lifecycle with Apple on your behalf.

Keep your domains verified

Hosting the verification file is permanent, not a one-time step. Apple re-validates each domain periodically. To keep a domain verified:

Let Apple's validation requests reach /.well-known/ through your CDN or WAF, with no proxy or redirect. Apple publishes the IP addresses of its verification bot, so you can use a narrow IP allowlist in place of a blanket path exemption.
Keep each domain's TLS certificate valid and its certificate chain stable. If either changes unexpectedly, verification fails and the domain drops out of Apple Pay.
Tell Interchecks before you add a new domain or subdomain.

Merchant Validation

Apple requires merchant validation for every Apple Pay integration. Apple enforces a strict session timeout, so validation has to finish quickly.

Step 1. Show the button. Your page uses Apple Pay JS to show the Apple Pay button. When your customer taps it, your page creates an ApplePaySession and calls begin() to open the payment sheet. The sheet stays inactive until you complete merchant validation in Step 3. In the payment request, set requiredBillingContactFields to ["postalAddress"] so Apple returns the cardholder's name and billing address, which Interchecks requires. See Apple's requiredBillingContactFields reference.

Step 2. Validate the merchant. When the payment sheet opens, Apple Pay JS fires the onvalidatemerchant event on your page. Your page sends a request to your server, and your server calls the Interchecks Merchant Validation endpoint with your domain_name. Interchecks calls Apple with its own certificate and returns the signed merchant session.

Step 3. Complete the session. Your server returns the merchant session to your page, which passes it to Apple Pay JS with completeMerchantValidation. The payment sheet becomes active, and your customer authorizes the payment.

Merchant Validation is a public endpoint that uses the same authentication as the other v2 endpoints. Call it from your server, never from the browser, so your API credentials stay on your server.

Call POST /api/v2/{payer_id}/transactions/digital-wallet/apple-pay/validate when Apple's onvalidatemerchant event fires.

Field	Send
`domain_name`	The host name of the page showing your Apple Pay button, such as `checkout.example.com`, with no `https://`, path, or port. It must match one of the domains Interchecks added to your Apple Pay settings, and `example.com` and `www.example.com` count as different domains. See Prerequisites.

Interchecks asks Apple for the merchant session on your behalf, using your configured display name, so your customers do not see Interchecks branding. The response is 200 with Apple's merchant session object, returned unchanged. Pass it straight to Apple's completeMerchantValidation.

If the call fails, you get one of these errors:

Error code	HTTP	Meaning
`ERR_INVALID_PARAMETER`	400	`domain_name` is missing or blank, or the request body is not valid JSON.
`ERR_APPLE_PAY_NOT_ENABLED`	403	Your account is not enabled for Apple Pay.
`ERR_APPLE_PAY_DOMAIN_NOT_REGISTERED`	400	`domain_name` is not registered on your Apple Pay settings. Tell Interchecks the domain so it can register it.
`ERR_APPLE_PAY_DOMAIN_NOT_VERIFIED`	422	Apple rejected the session request. Usually the domain is not verified with Apple, for example because the domain-verification file is not hosted on it.
`ERR_PROVIDER_UNAVAILABLE`	502, 503	Apple Pay is not configured in this environment, Apple returned an error, or Apple timed out or could not be reached. A `503` is safe to retry.
`ERR_PROVIDER_ACCOUNT_MISCONFIGURATION`	500	Apple rejected the Interchecks certificate or platform setup. You cannot retry this.
`ERR_INTERNAL_SERVER_ERROR`	500	Unexpected failure.

For the full endpoint reference, see Merchant Validation in the API Reference.

Transaction Endpoint

After your customer authorizes the payment, you create the transaction.

Step 1. Collect the payment object. Apple returns its payment object to your onpaymentauthorized handler as event.payment. It contains token and billingContact. Send the whole object to your server unchanged.

Step 2. Create the transaction. Your server calls Create Apple Pay Transaction. Send these values:

Field	Send
`recipient_id`	The recipient you created with Create Recipient. See Prerequisites.
`type` and `method`	`DEBIT` with `INSTANT_FUNDING` for AFT, or `CREDIT` with `INSTANT_DEPOSIT` for OCT. A type that does not match the method returns `400` and `ERR_INVALID_TRANSACTION_TYPE`.
`apple_payment_data`	Apple's payment object, exactly as Apple returned it, as a JSON object or the JSON string Apple hands you.
`location.ip_address`	The customer's IP address. Required for AFT.
`funding_options`	Optional, but strongly recommended. It holds `user_segment`, `ip_address`, `user_agent`, and `device_id`, all optional strings. They give Interchecks more identity data to defend future disputes. For AFT, `funding_options.ip_address` does not replace `location.ip_address`.

Interchecks decrypts the payment data, creates the payment account, and creates the transaction. You do not send an account_id, an amount, a currency_code, or billing details. Interchecks reads the amount and currency from the decrypted payment data, and the cardholder name and billing address from Apple's billingContact.

Step 3. Handle the response. A 201 means Interchecks created the transaction. Check status. PAID means approved. PROCESSING or UNKNOWN means the outcome is not final yet, so treat it as pending, not failed. The response includes account_id, the payment account this call created or reused, and digital_wallet, which is APPLE_PAY. A 200 with an error body means the payment failed. A network decline returns ERR_AFT_DECLINE for AFT, or ERR_OCT_DECLINE for OCT. If the card fails validation first, for example ERR_CARD_PAV_FAILURE for AFT, no transaction is created. See API Error Codes for the Apple Pay errors.

Step 4. Close the payment sheet. Your server returns the result to your page, which calls Apple Pay JS completePayment with a success or failure status. Apple then closes the payment sheet.

Send `apple_payment_data` unchanged

Pass Apple's payment object exactly as Apple returns it. Apple uses camelCase keys and puts token at the top level. Do not rename keys, restructure, or drop fields. You can pass it as a JSON object, or as the JSON string Apple returns.

Apple owns this schema, so this guide does not define its fields. See Apple's ApplePayPayment and Payment token format reference.

Billing address requirements

Apple includes billingContact because you set requiredBillingContactFields in Merchant Validation Step 1.

A request without billingContact is rejected with 400 and ERR_INVALID_PARAMETER.

Within billingContact, these are required: givenName, familyName, at least one addressLines entry, locality, administrativeArea, and postalCode. Interchecks treats every address as a US address and ignores countryCode, so administrativeArea must be a US state abbreviation such as MA. The street lines, locality, and postalCode must be plain ASCII. Otherwise the request is rejected with 400 and ERR_INVALID_ADDRESS_PARAMETERS.

Send the token within five minutes

Send the payment object within 5 minutes of your customer authorizing the payment. If Apple signed the token more than 5 minutes before Interchecks receives it, Interchecks returns 400 and ERR_DIGITAL_WALLET_TOKEN_EXPIRED, and your customer must authorize again.

Pay in US dollars

Apple Pay supports only USD. Interchecks reads the currency from the payment data and rejects any other currency with 400 and ERR_INVALID_CURRENCY_CODE.

Use an idempotency key

Send an Idempotency-Key header on every call. The header is optional, but Interchecks strongly recommends it. If you repeat a request with the same key, Interchecks returns 102 while the first request is still processing, and 409 with the original response once it has returned a 200 or 201. If the first request failed with a 4xx or 5xx, the repeat is processed again. Resending an Apple Pay payment token follows the same rules, even with a different key.

For every field and response code, see Create Transaction for Apple Pay in the API Reference.