Apple Pay Passthrough | Finix Guides

Apple Pay Passthrough

If you decrypt Apple Pay tokens outside of Finix, use the passthrough path to send the wallet authentication fields including the Electronic Commerce Indicator (ECI) directly to Finix.

The ECI is a one-or-two-digit value that card networks and issuers factor into liability and risk decisions on the authorization.

PCI Level 1 Required

The passthrough path transmits raw PAN (DPAN) data. Only customers that are PCI Level 1 compliant are permitted to use it. Sending number without PCI Level 1 approval returns a 422 error.

How It Works

There are two ways to submit Apple Pay or Google Pay data to POST /payment_instruments:

Path How it works
Encrypted token (default) Send the encrypted third_party_token. Finix decrypts it and extracts all fields, including ECI.
Passthrough Decrypt the token yourself and send the individual fields (number, cryptogram, expiration_month, expiration_year, electronic_commerce_indicator_code) directly.

You cannot send both number and third_party_token in the same request. Doing so returns a 422 error.

Passthrough Fields

Field Type Required Description
number string Yes Network token PAN (DPAN) from the decrypted token. For Google Pay, this may be a raw PAN.
cryptogram string Yes Wallet-generated cryptogram from the decrypted token. Required for Apple Pay. Optional for Google Pay — PAN_ONLY tokens do not produce a cryptogram.
expiration_month integer No Card expiration month (1–12).
expiration_year integer No Card expiration year (4-digit).
electronic_commerce_indicator_code string No One-or-two-digit value indicating the authentication method. The card network and issuer factor this into liability and risk decisions on the authorization.

Create a Payment Instrument (Passthrough)

When your server receives the decrypted fields from the Apple Pay token, pass them directly in the POST /payment_instruments request body instead of third_party_token.

Example

API Definition

post /payment_instruments

Sandbox server
https://finix.sandbox-payments-api.com/payment_instruments

cURL

curl -i -X POST
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda
https://finix.sandbox-payments-api.com/payment_instruments
-H 'Content-Type: application/json'
-H 'Finix-Version: 2022-02-01'
-d '{\n "address": {\n "city": "San Francisco",\n "country": "USA",\n "line1": "900 Metro Center Blv",\n "line2": "APT 200",\n "postal_code": "94404",\n "region": "CA"\n },\n "cryptogram": "abc",\n "electronic_commerce_indicator_code": "07",\n "expiration_month": 11,\n "expiration_year": 2026,\n "identity": "IDmj1yA97RS4rMjiQgvK3Vio",\n "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n",\n "name": "John Smith",\n "number": "5200828282828210",\n "type": "APPLE_PAY"\n }'

Example

API Definition

Payment Instrument - Apple Pay - Passthrough

{\n "id": "PIwpqpJZCharsZAt6WKVopPS",\n "created_at": "2025-05-08T18:44:58.56Z",\n "updated_at": "2025-05-08T18:44:58.56Z",\n "application": "APc9vhYcPsRuTSpKD9KpMtPe",\n "created_via": "API",\n "currency": "USD",\n "disabled_code": null,\n "disabled_message": null,\n "enabled": true,\n "fingerprint": "FPR88YBDbK4TqYMUNU8t8fbeQ",\n "identity": "IDmj1yA97RS4rMjiQgvK3Vio",\n "instrument_type": "APPLE_PAY",\n "address": {\n "line1": "900 Metro Center Blv",\n "line2": "APT 200",\n "city": "San Francisco",\n "region": "CA",\n "postal_code": "94404",\n "country": "USA"\n },\n "bin": "370382",\n "brand": "AMERICAN_EXPRESS",\n "card_type": "CREDIT",\n "expiration_month": 11,\n "expiration_year": 2026,\n "issuer_country": "USA",\n "last_four": "1234",\n "name": "John Smith",\n "tags": {},\n "third_party": null,\n "third_party_token": null,\n "type": "APPLE_PAY",\n "_links": {\n "self": {\n "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS"\n },\n "authorizations": {\n "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS/authorizations"\n },\n "transfers": {\n "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS/transfers"\n },\n "verifications": {\n "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS/verifications"\n },\n "application": {\n "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"\n },\n "identity": {\n "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio"\n }\n }\n }

The response shape is identical to the standard Apple Pay path. The electronic_commerce_indicator_code value is not echoed back in the response.

Error Responses

Scenario Status Error code Message
number and third_party_token both sent 422 INVALID_FIELD Only one of number or third_party_token is allowed in a request.
number sent without cryptogram 422 INVALID_FIELD cryptogram field is required.
Neither number nor third_party_token sent 422 INVALID_FIELD Either number or third_party_token must be provided
electronic_commerce_indicator_code is not 1 or 2 numeric digits 422 INVALID_FIELD electronic_commerce_indicator_code must be 1 or 2 numeric digits
Customer is not PCI Level 1 compliant 422 UNPROCESSABLE_ENTITY Unless you are PCI Level 1 compliant, you must send the encrypted APPLE_PAY token in the third_party_token field.