Apple Pay
Overview
Accepting Apple Pay through Forter takes three steps:
- Register your Apple Pay Merchant ID with Forter's Payment Processing Certificate, so Apple encrypts payments for Forter.
- Send the encrypted Apple Pay payment token to the Forter Tokenization API, which returns Forter tokens.
- Send the Forter tokens to your PSP through the Detokenization Proxy.
Forter decrypts the Apple Pay token inside its PCI environment, so your servers never see the device account number or cryptogram.
sequenceDiagram
participant B as Browser / App
participant A as Apple Pay
participant M as Merchant backend
participant T as Forter Tokenization API
participant P as Forter Detokenization Proxy
participant S as PSP
B->>A: Show Apple Pay sheet
A-->>B: encrypted payment token
B->>M: payment token
M->>T: POST /v1/wallet/tokenize-apple-pay
T-->>M: applePayDeviceDataToken, paymentCredentialsToken
M->>P: PSP request with placeholders + token headers
P->>S: PSP request with card data
S-->>M: authorization resultPrerequisites
- Forter Tokenization API credentials (site_id and site_secret). See Tokenization API.
- Detokenization Proxy set up, including Forter's CA certificate. See Detokenization Proxy.
- An Apple Developer account with access to Certificates, Identifiers & Profiles.
- An Apple Pay integration that follows Apple's Apple Pay documentation, on the web (Apple Pay JS or Payment Request API) or in an iOS app (PassKit).
Environments
Apple Pay environment | Forter site | Tokenization API base URL |
|---|---|---|
Sandbox (Apple sandbox tester accounts) | Sandbox (test) site | |
Production | Production site |
Forter stores Apple Pay keys and certificates per Forter site. Your sandbox and production sites each need their own Payment Processing Certificate, created from a separate Forter CSR for each site.
Step 1: Set up Apple Pay with Forter
What you exchange with Forter
Setup is a short exchange with Forter, repeated for your sandbox and production sites.
Forter sends you:
Item | What you do with it |
|---|---|
site_id and site_secret, one pair per site | Authenticate Tokenization API calls (HTTP Basic) and Detokenization Proxy requests (proxy-authorization header). Keep them on your servers only. |
Forter's CA certificate | Add it to your HTTP client's trusted CAs (for example NODE_EXTRA_CA_CERTS) so it accepts the Detokenization Proxy's TLS certificate. |
A Certificate Signing Request (CSR) file, one per site | Upload it to Apple to create the Payment Processing Certificate for that site's Merchant ID (step 3 below). Don't generate this CSR yourself: Forter holds its private key, and that key is what lets Forter decrypt your payments. |
A lifecycle notification URL | Set it as tokenNotificationURL in recurring, automatic reload and deferred payment requests. See Lifecycle notifications. |
You send Forter:
Item | When |
|---|---|
Your organization name and country | When you request the CSR. Forter includes them in the CSR. |
The Payment Processing Certificate (.cer) Apple issues | After step 3 below, once per site. Tokenization works only after Forter installs it. |
You keep: your Apple Developer account and your Merchant Identity Certificate with its private key. Never send them to Forter.
Register your Merchant ID and certificates
Apple encrypts each payment with the public key of your Payment Processing Certificate. Forter generates that certificate's key, so only Forter can decrypt your payments.
- Register a Merchant ID. In your Apple Developer account, go to Identifiers → + → Merchant IDs. Use a reverse-domain identifier, for example merchant.com.yourdomain.appname.
- Verify your domain (web only). In the Merchant ID's Merchant Domains, add your domain and host Apple's verification file at /.well-known/apple-developer-merchantid-domain-association.txt over HTTPS, with no redirects.
- Create the Payment Processing Certificate. Under Certificates → +, select Apple Pay Payment Processing Certificate, link it to your Merchant ID and upload the CSR Forter sent you (ECC P-256). Apple rejects any other key type here.
- Send the .cer file to Forter. Download the certificate and send it to Forter. Forter checks that it was created from Forter's CSR and rejects any other certificate. Note its expiration date.
- Create the Merchant Identity Certificate (web only). Generate your own RSA 2048 key and CSR, upload it as an Apple Pay Merchant Identity Certificate and install the certificate on your server. Your server uses it for merchant validation. Never share this private key with Forter.
Certificate | CSR key type | Who generates the CSR | Purpose |
|---|---|---|---|
Payment Processing Certificate | ECC P-256 | Forter | Lets Forter decrypt the payment token |
Merchant Identity Certificate | RSA 2048 | You | Authenticates your server to Apple for merchant validation |
Each Forter site holds one Payment Processing Certificate, so use one Merchant ID per site. Domain verification and certificates expire on separate dates, so track both. To renew the Payment Processing Certificate, ask Forter for a CSR, create the new certificate from it and send it to Forter before the old one expires.
Configure the Apple Pay payment request
Use the Merchant ID you registered with Forter. Apple Pay returns a payment token encrypted for Forter's certificate.
const request = {
countryCode: "US",
currencyCode: "USD",
supportedNetworks: ["visa", "masterCard", "amex", "discover"],
merchantCapabilities: ["supports3DS"],
total: { label: "Example Merchant", amount: "10.00" },
};
const session = new ApplePaySession(3, request);
// Merchant validation runs on your server with your Merchant Identity Certificate
session.onvalidatemerchant = async (event) => {
const merchantSession = await fetch("/api/apple-pay/validate-merchant", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ validationURL: event.validationURL }),
}).then((r) => r.json());
session.completeMerchantValidation(merchantSession);
};
session.onpaymentauthorized = async (event) => {
// Step 2: send the encrypted token to your backend
await fetch("/api/apple-pay/token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ paymentData: event.payment.token.paymentData }),
});
};
session.begin();In an iOS app, use PKPaymentRequest with the same Merchant ID and send payment.token.paymentData to your backend.
Apple Pay returns one of these credentials:
Credential | When Apple returns it | What it contains |
|---|---|---|
DPAN (device token) | One-time payments | Device account number, expiry, cryptogram and ECI |
MPAN (merchant token) | Recurring, automatic reload and deferred payment requests | Merchant token, merchantTokenIdentifier, card metadata, cryptogram and ECI |
Step 2: Tokenize the Apple Pay token
Never call this endpoint from the browser or a mobile app, because the site_secret must stay on your servers. Pass the token from the browser or app to your backend, then call Forter from there.
From your backend, call the Tokenization API with HTTP Basic authentication:
const res = await fetch("https://pci-tokenization-sandbox.checkouttools.com/v1/wallet/tokenize-apple-pay", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Basic " + Buffer.from(`${SITE_ID}:${SITE_SECRET}`).toString("base64"),
},
body: JSON.stringify({
payload: { token: { paymentData: paymentDataFromClient } },
customerId: "customer-123", // optional
}),
});
const tokens = await res.json();Request body
Field | Type | Required | Description |
|---|---|---|---|
payload.token.paymentData | object | Yes | The paymentData object from Apple's ApplePayPaymentToken (version, data, signature, header). Send it unchanged. |
customerId | string (2–100 characters) | No | Your ID for the shopper who owns this payment method. It makes it easier to delete a shopper's payment methods later and helps with GDPR compliance. |
tokenAliases | object | No | Up to 5 key/value pairs that map your own identifiers to the Forter token. Keys are 2–50 characters and values 5–100 characters. |
Response
200
{
"applePayDeviceDataToken": "<device data token>",
"paymentCredentialsToken": "<payment credentials token>"
}Token | Contains | Lifetime |
|---|---|---|
applePayDeviceDataToken | Device account number (DPAN or MPAN), expiration date, cardholder name, device and merchant token metadata | Same as a Forter multi-use token |
paymentCredentialsToken | Cryptogram, ECI and EMV data for this transaction | 24 hours; use for a single authorization |
Tokens are scoped to the site that created them, so use them only with that site's credentials.
Step 3: Authorize through the Detokenization Proxy
Send your PSP request through the Detokenization Proxy, adding the Apple Pay token headers and placeholders where the PSP expects card data. The proxy swaps the placeholders for decrypted values before forwarding.
Headers
Header | Value |
|---|---|
forter-apple-pay-device-data-token | applePayDeviceDataToken. Always required. |
forter-apple-pay-payment-credentials-token | paymentCredentialsToken. Required for the cryptogram, ECI and EMV data placeholders. Omit it otherwise, for example for merchant-initiated payments. |
Placeholders
Placeholder | Description |
|---|---|
{{apple_pay_device_account_number}} | The device account number: the DPAN, or the MPAN for merchant-token payments. |
{{apple_pay_cryptogram}} | The cryptogram. Requires the payment credentials token. |
{{apple_pay_eci}} | The ECI. Requires the payment credentials token. |
{{apple_pay_emv_data}} | The EMV data. Requires the payment credentials token. |
{{apple_pay_expiration_m}} | Expiration month as a single digit (e.g., 3). |
{{apple_pay_expiration_mm}} | Expiration month as two digits (e.g., 03). |
{{apple_pay_expiration_yy}} | Expiration year as two digits (e.g., 28). |
{{apple_pay_expiration_yyyy}} | Expiration year as four digits (e.g., 2028). |
{{apple_pay_cardholder_name}} | The cardholder name. |
Example
The PSP endpoint and body are illustrative only.
// Trust Forter's proxy CA before the app starts:
// export NODE_EXTRA_CA_CERTS=[your CA certificate file path]
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";
const proxyAgent = new HttpsProxyAgent("https://pci-proxy-sandbox.checkouttools.com", {
headers: {
"proxy-authorization": `Basic ${Buffer.from(`${SITE_ID}:${SITE_SECRET}`).toString("base64")}`,
"forter-apple-pay-device-data-token": tokens.applePayDeviceDataToken,
"forter-apple-pay-payment-credentials-token": tokens.paymentCredentialsToken,
},
});
await axios.post(
"https://api.example-psp.com/v1/payments",
{
orderId: "123456",
amount: { value: 1000, currency: "USD" },
card: {
number: "{{apple_pay_device_account_number}}",
expMonth: "{{apple_pay_expiration_mm}}",
expYear: "{{apple_pay_expiration_yyyy}}",
},
wallet: {
type: "APPLE_PAY",
cryptogram: "{{apple_pay_cryptogram}}",
eci: "{{apple_pay_eci}}",
},
},
{
httpsAgent: proxyAgent,
proxy: false,
headers: { Authorization: "Bearer <PSP API key>" },
},
);Mark the request as an Apple Pay or network-token payment in your PSP's own field. Field names differ by PSP.
Recurring payments and merchant tokens (MPAN)
For subscriptions, automatic reload and deferred payments, request an Apple Pay merchant token with a recurring, automatic reload or deferred payment request. A merchant token isn't tied to one device, so it keeps working when the shopper replaces their iPhone.
- First payment. Tokenize the payment and authorize with the cryptogram, as in Steps 2 and 3. Save the applePayDeviceDataToken and the network transaction ID your PSP returns.
- Later payments. Send only the forter-apple-pay-device-data-token header through the Detokenization Proxy, since the payment credentials token expires after 24 hours. Don't use the cryptogram, ECI or EMV data placeholders. Flag the request as merchant-initiated and include the original network transaction ID, following your PSP's stored-credential fields. See MIT Flows.
Lifecycle notifications
Set tokenNotificationURL inside your recurringPaymentRequest, automaticReloadPaymentRequest or deferredPaymentRequest to the URL Forter gives you, in the form https://<forter-webhooks-host>/apple-pay/lifecycle/{siteId}. Forter receives Apple's notifications when a merchant token is updated or suspended and keeps your tokens in sync, so you don't need your own endpoint. It's optional but recommended.
One-time DPAN payments have no merchant token, so lifecycle notifications don't apply to them.
Errors
Tokenization API
The Tokenization API returns HTTP 400 with { "message": "..." }:
Message | Cause |
|---|---|
Apple Pay not configured for this merchant | Forter hasn't installed a Payment Processing Certificate for this site yet. Send Forter the .cer from Step 1. |
Apple Pay private key not found | No Forter CSR key exists for this site. Ask Forter for a CSR and repeat Step 1. |
Invalid Apple Pay token | The token couldn't be verified or decrypted. Check that paymentData is sent unchanged and that the Merchant ID's Payment Processing Certificate was created from this site's Forter CSR. |
Detokenization Proxy
Status | Meaning |
|---|---|
407 | Proxy authentication error (check credentials) |
555 | Token not found: it doesn't exist, belongs to another site, or has expired |
556 | Validation error, for example a cryptogram placeholder sent without the payment credentials token (Apple Pay payment credentials placeholders require payment credentials token) |
If a token is missing or expired, don't retry. Ask the shopper to pay with Apple Pay again and tokenize the new token.