Apple Pay decryption docs reportedly list wrong KDF inputs; archived page still correct

Live page and archive disagree

According to a dev.to post by Tom Wang, Apple's current reference page for decrypting Apple Pay payment tokens contains errors in its key derivation function table. The table reportedly lists a hash function in the position where the ECDH shared secret belongs and omits the byte sequence identifying the id-aes256-GCM algorithm entirely. Wang notes that an archived copy of the same page shows the correct values, so the mistakes appear to have crept into the live page rather than being there from the start.

The failure mode is quiet. A decryptor built strictly from the live documentation derives a key that never opens the ciphertext, and AES-GCM produces no error pointing back to a malformed KDF input. The surrounding code looks correct; the key is simply wrong, and nothing tells you why.

What sits inside an Apple Pay token

When the payment sheet completes, the token's payment data is a JSON object with four top-level keys: a version, base64 ciphertext, a detached PKCS #7 signature, and a header carrying the ephemeral public key, a public key hash, a transaction ID and optional application data.

The version is EC_v1 almost everywhere. Apple says RSA_v1 appears in regions where regulatory concerns make ECC encryption unavailable, and its March 2026 technote TN3206 effectively maps this to China mainland: the Payment Processing certificate signing request is a 256-bit ECC key globally and a 2048-bit RSA key there. An RSA_v1 header substitutes wrappedKey for ephemeralPublicKey.

Wang singles out publicKeyHash as the field that matters most. It is the only signal identifying which of your private keys the token was encrypted to, which makes it central to surviving certificate rotation without outages.

The derivation, as the archived page describes it

For EC_v1, decryption is ECDH, then a single-pass NIST SP 800-56A concatenation KDF, then AES-GCM. The steps, per Wang's write-up:

1. Select the key by matching header.publicKeyHash against the SHA-256 of each Payment Processing certificate public key you hold.
2. Agree on a secret via ECDH between your private key and the token's ephemeralPublicKey. Apple specifies only a 256-bit ECC key pair; open-source decryptors treat it as P-256.
3. Derive the key by taking SHA-256 over a counter of 0x00000001, the ECDH shared secret Z, the AlgorithmID, PartyUInfo and PartyVInfo. AlgorithmID is the length-prefix byte 0x0D followed by the ASCII string id-aes256-GCM, which is 13 characters. PartyUInfo is the ASCII string "Apple". PartyVInfo is the SHA-256 of your merchant identifier, either hashed from the UID in the certificate subject or hex-decoded from the extension at OID 1.2.840.113635.100.6.32.
4. Decrypt the data with AES-256-GCM using an IV of 16 zero bytes and no associated data; the final 16 bytes of the ciphertext are the GCM tag.

Why it matters

When reference documentation doubles as the de facto specification, a transcription error in a KDF table becomes a silent change to the spec. Teams implementing decryption from the live page will ship code that fails authentication, then spend days auditing their own ECDH, certificate handling and GCM parameters before thinking to check the docs. The mitigations are unglamorous: diff the live page against its archived version, validate any new decryptor against a known-good open-source implementation, and pin test vectors. Wang also raises the broader question his guide circles around — whether most teams should be decrypting tokens themselves at all, rather than handing them to a payment service provider. For those who must own the decryption path, the lesson is that in key derivation every byte is load-bearing, and documentation bugs fail exactly as loudly as your own.