> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenize Google Pay

> Tokenize Google Pay payments and manage the resulting wallet tokens

Google Pay is the first device wallet supported by Guardian [wallet tokens](/products/guardian/tokens/wallet-tokens/overview). You pass the encrypted Google Pay payload to Guardian, which verifies, decrypts, and stores the credential server-side — the decrypted card data never touches your systems.

## Prerequisites

Google Pay encrypts every payload for a specific recipient. Before you can tokenize:

1. Your instance holds an active ECv2 decryption key and is configured with your Google Pay **merchant ID**. Contact support to set this up.
2. You register the public half of that key in the [Google Pay & Wallet Console](https://pay.google.com/business/console/), so Google encrypts payloads your instance can decrypt.

## Tokenizing a Google Pay Payment

When a customer completes a Google Pay sheet, the Google Pay API hands your client a `PaymentMethodToken` envelope. Send it to [Tokenize Google Pay](/products/guardian/api-reference/wallet/tokenize-google-pay) exactly as Google returns it — Guardian verifies the ECv2 signature chain against Google's trusted signing keys, decrypts the payload, and stores the credential as a wallet token.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant C as Customer
    participant M as Merchant
    participant G as Google Pay
    participant H as Guardian
    participant P as PSP / Acquirer

    C->>+G: Confirm payment in Google Pay sheet
    G->>-M: PaymentMethodToken envelope
    M->>+H: POST /api/wallet/google-pay/tokenize
    H->>H: Verify signature chain, decrypt, store
    H->>-M: Wallet token
    M->>+H: POST /api/wallet/{id}/forward
    H->>+P: Request with card data injected
    P->>-H: Authorization result
    H->>-M: Authorization result
```

The same envelope can be tokenized only once: resubmitting it returns `409` with the classifier `GOOGLE_PAY_DUPLICATE_PAYLOAD`.

## Authentication Methods

Google Pay issues two flavors of credential. The `auth_method` field on the wallet token tells you which one you hold, and it determines everything downstream:

|                            | `CRYPTOGRAM_3DS`                          | `PAN_ONLY`                            |
| -------------------------- | ----------------------------------------- | ------------------------------------- |
| Credential                 | Device-bound token: DPAN, cryptogram, ECI | Card on file: funding PAN and expiry  |
| Forwarding                 | Once — the cryptogram is single-use       | Repeatedly                            |
| Promotion to network token | Not eligible                              | Eligible                              |
| 3-D Secure                 | Authentication carried in the cryptogram  | May be required; check `requires_3ds` |

The `requires_3ds` field indicates whether the payment still needs 3-D Secure authentication on your side before authorization.

## Forwarding

[Forwarding a wallet token](/products/guardian/tokens/wallet-tokens/overview#forwarding-wallet-tokens) works the same for every wallet; this section lists the placeholders and rules specific to Google Pay. Which placeholders a token carries depends on its `auth_method`:

| Placeholder          | `CRYPTOGRAM_3DS` | `PAN_ONLY` | Description                    |
| -------------------- | ---------------- | ---------- | ------------------------------ |
| `{{ dpan }}`         | ✓                | —          | The device PAN.                |
| `{{ cryptogram }}`   | ✓                | —          | The 3-D Secure cryptogram.     |
| `{{ eci }}`          | ✓                | —          | Electronic Commerce Indicator. |
| `{{ fpan }}`         | —                | ✓          | The funding PAN.               |
| `{{ expiry_month }}` | ✓                | ✓          | Card expiry month.             |
| `{{ expiry_year }}`  | ✓                | ✓          | Card expiry year.              |

A `CRYPTOGRAM_3DS` token is **single-use**: the first successful forward consumes it, and later attempts return `400` with the classifier `CRYPTOGRAM_CONSUMED`. A `PAN_ONLY` token can be forwarded repeatedly.

If your template references a placeholder the token's `auth_method` does not carry (for example `{{ fpan }}` against a `CRYPTOGRAM_3DS` token), 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.

## Promotion

A `PAN_ONLY` token carries the customer's funding PAN, so you can promote it to a network token when you want a durable card-on-file credential with the [full network token lifecycle](/products/guardian/tokens/network-tokens). `CRYPTOGRAM_3DS` tokens carry no funding PAN and cannot be promoted — attempting to promote one returns `422` with the classifier `UNSUPPORTED_WALLET_TYPE`.

Promotion is a regular [Create token](/products/guardian/api-reference/network/create-token) call with the wallet token as source:

```json theme={null}
{
  "source": {
    "type": "wallet_token",
    "wallet_token_id": "0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2"
  }
}
```

Guardian then:

1. Vaults the wallet token's funding PAN as a new PCI token.
2. Provisions a network token from it with the card scheme.
3. Records the link on the wallet token's `promoted_to` field.

A wallet token can be promoted once — repeating the call returns `422` with the classifier `WALLET_TOKEN_ALREADY_PROMOTED`.