Skip to main content
Apple Pay is a device wallet supported by Guardian wallet tokens. You pass the encrypted Apple Pay payload to Guardian, which verifies, decrypts, and stores the credential server-side, so the decrypted card data never touches your systems. Unlike a card-on-file credential, an Apple Pay payment always yields a device-bound token: a device PAN (DPAN) with a single-use cryptogram and ECI. Guardian never sees or stores the underlying funding PAN.

​
Operating Modes

Every Guardian deployment runs Apple Pay in one of two modes, set by the operator:
  • self_managed (the default): you upload your own Apple identity to Guardian and manage the certificates yourself. This is the flow this page describes. The RSA identity certificate is a merchant identity certificate.
  • sf_operated: Starfish operates the Apple Developer relationship, and the Apple identity and certificates come from Guardian’s configuration (mounted by Starfish). On these deployments the settings-upload and certificate-management endpoints are disabled and return 409 with the classifier APPLE_PAY_CERT_MANAGEMENT_UNAVAILABLE. Only domain registration and the runtime flow (sessions, tokenize, forward) are available to you. Here the same RSA identity certificate is a platform integrator identity certificate.
You can check which mode an instance runs in with Get settings.

​
Prerequisites

Apple Pay encrypts every payload for a specific merchant and requires Apple to trust your domain before the browser will present the payment sheet. Before you can tokenize, complete the one-time setup below. All setup endpoints are administrative and separate from the runtime tokenization flow.
1

Upload your Apple Pay settings

Before Guardian can generate CSRs, register domains, or validate sessions, it needs your Apple identity. Call Update settings with:
  • merchant_identifier: your Apple Pay merchant identifier.
  • display_name: the merchant display name shown in the Apple Pay sheet.
  • domain_association_content: the byte-exact body of the domain-association file Apple issued, which Guardian serves verbatim.
  • csr_common_name: the common name to embed in the CSRs Guardian generates.
Guardian reads the merchant identifier, display name, CSR common name, and served domain-association body from these settings. The upload is a partial update: fields you omit keep their current values. Until all are uploaded, the steps below return 400 with the classifier APPLE_PAY_NOT_CONFIGURED.On Starfish-operated (sf_operated) instances this step and the certificate steps below are managed by Starfish; those endpoints return 409 with the classifier APPLE_PAY_CERT_MANAGEMENT_UNAVAILABLE.
2

Register your payment processing certificate

Guardian holds the private key inside its PCI boundary and only ever emits a signing request. Call Create certificates to have Guardian generate the certificate signing requests (CSRs): an EC payment processing CSR and an RSA merchant identity CSR.Submit each csr_pem to Apple in the Apple Developer portal, download the signed certificates, and return them with Upload a certificate. Once uploaded, the certificate moves to active and becomes the one Guardian uses to decrypt payloads and authenticate to Apple.
3

Register your domain

Every domain that shows the Apple Pay button must be registered with Apple. Fetch the domain-association file from your Guardian instance at GET /.well-known/apple-developer-merchantid-domain-association.txt (public, no authentication) and serve it from your domain at the same path. Register the domain in the Apple Developer portal, where Apple fetches that file to attest your ownership.Then call Register a domain with the fully-qualified domain, for example pay.example.com. On a self_managed instance Guardian trusts your attestation and marks the domain verified immediately. On sf_operated instances Guardian instead registers the domain with Apple’s Web Merchant Registration API in the background; the domain starts as pending and moves to verified once Apple accepts it. Verify a domain re-triggers verification for a pending or failed domain.
Guardian verifies every payload’s signature against Apple’s root certificate authority, which is seeded on your instance; no setup is needed. If Apple ever rotates its root CA, replace the trust anchor with Replace trust anchor and inspect the active one with Get trust anchor.

​
Merchant Validation

When a customer opens the Apple Pay sheet in a browser, Apple fires onvalidatemerchant with a validation URL. Your client sends that to your backend, which asks Guardian to complete the exchange with Apple on your behalf. Call Validate Apple Pay session with the domain_name (a verified domain); Guardian reads your merchant identifier and display name from the Apple Pay settings. Guardian performs the mTLS handshake with Apple using the active identity certificate and returns Apple’s session object verbatim. Pass it straight to session.completeMerchantValidation(...) in the browser. A request for an unregistered or unverified domain returns 422 with the classifier APPLE_PAY_DOMAIN_NOT_VERIFIED. If Apple rejects the validation, Guardian returns 502 with APPLE_PAY_SESSION_ERROR; if no active identity certificate exists, 500 with APPLE_PAY_NO_ACTIVE_CERTIFICATE.

​
Tokenizing an Apple Pay Payment

When the customer authorizes the payment, the Apple Pay JS API hands your client a PKPaymentToken whose paymentData is the encrypted EC_v1 envelope. Send that envelope to Tokenize Apple Pay exactly as Apple returns it, as the payment_data field. Guardian verifies the signature against Apple’s trusted certificates, decrypts the payload with your active payment processing certificate, and stores the credential as a wallet token. Tokenization is idempotent on the encrypted payload: resubmitting the same envelope returns the existing wallet token rather than creating a duplicate. If that payload’s wallet token was already deleted, the request returns 409 with the classifier APPLE_PAY_TOKEN_DELETED. Rejected envelopes return 422 with a classifier naming the cause: If no active payment processing certificate exists, tokenization returns 500 with the classifier APPLE_PAY_NO_ACTIVE_CERTIFICATE.

​
Forwarding

Forwarding a wallet token works the same for every wallet; this section lists the placeholders and rules specific to Apple Pay. An Apple Pay token is a device-bound token, so it carries the following placeholders: An Apple Pay token is single-use: the first successful forward consumes its cryptogram, and later attempts return 400 with the classifier CRYPTOGRAM_CONSUMED. If your template references a placeholder the token does not carry, the forward is rejected with 422 and the classifier DESTINATION_POLICY_VIOLATION; a placeholder the token does carry but that has no value on this specific credential returns 422 with PLACEHOLDER_VALUE_MISSING. Both name the offending placeholder. Because an Apple Pay token carries no funding PAN, it cannot be promoted to a network token.