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

# Google Pay Wallet Provisioning

> Complete guide to integrating Google Pay card provisioning (Add to Google Wallet) with OTP verification

Google Pay Wallet Provisioning allows your cardholders to add their cards to Google Wallet for contactless payments. When a cardholder adds their card, the platform verifies ownership through a one-time password (OTP) flow before activating the digital card.

***

## Overview

When a cardholder taps "Add to Google Wallet" on their device, Mastercard verifies the card's eligibility and initiates a verification flow. UTGL generates a 6-digit verification code, delivers it via SMS and webhook, and the cardholder enters the code in Google Wallet to complete activation.

### Key Benefits

* **Contactless Payments** - Enable cardholders to pay with their phone via NFC
* **Real-time Webhook** - Receive the verification code programmatically to surface in your app
* **Secure Verification** - OTP-based ownership verification before activation
* **Multi-channel Delivery** - Code delivered via both SMS and webhook

***

## How It Works

The provisioning flow involves Mastercard, UTGL, and your system working together to verify the cardholder's identity:

```mermaid theme={null}
sequenceDiagram
    participant Cardholder
    participant GoogleWallet as Google Wallet
    participant Mastercard
    participant UTGL as UTGL Platform
    participant YourSystem as Your Backend

    Cardholder->>GoogleWallet: Tap "Add to Google Wallet"
    GoogleWallet->>Mastercard: Request card provisioning
    Mastercard->>UTGL: Verify card eligibility
    UTGL->>UTGL: Generate 6-digit verification code
    
    par Notification Channels
        UTGL->>Cardholder: SMS with verification code
        UTGL->>YourSystem: Webhook with verification code
    end
    
    YourSystem-->>Cardholder: (Optional) Display code in your app
    Cardholder->>GoogleWallet: Enter verification code
    GoogleWallet->>Mastercard: Verify code
    Mastercard->>UTGL: Confirm activation
    Note over GoogleWallet: Card activated in Google Wallet
```

### Provisioning Lifecycle

1. **Initiation** - Cardholder taps "Add to Google Wallet" on their device
2. **Eligibility Check** - Mastercard verifies the card is eligible for provisioning
3. **Code Generation** - UTGL generates a 6-digit verification code
4. **Code Delivery** - Code is sent via SMS to the cardholder and via webhook to your system
5. **Verification** - Cardholder enters the code in Google Wallet
6. **Activation** - Card is activated and ready for contactless payments

***

## Prerequisites

Before your cardholders can add cards to Google Wallet, ensure the following:

<Warning>
  All three prerequisites must be met. If any are missing, the provisioning flow will not be triggered.
</Warning>

1. **Google Pay Enabled** - Your card product must have Google Pay provisioning enabled. Contact your solution manager to enable this feature.
2. **Registered Mobile Number** - The cardholder must have a mobile phone number on file for SMS delivery.
3. **Email Address** - The cardholder must have an email address on file for confirmation notifications.

***

## Webhook Event

### `cardaccount.googlepay.verification-code-delivered`

This webhook is fired when a Google Pay verification code is generated and delivered. Use this to surface the code in your app UI or trigger additional cardholder communications.

#### Event Structure

```json theme={null}
{
  "event": "cardaccount.googlepay.verification-code-delivered",
  "id": "evt_1a2b3c4d5e6f7g8h9i0j",
  "time": "2026-02-05T10:30:00.000Z",
  "data": {
    "cardId": "438f4574-8d75-4938-8667-e626d181da19",
    "verificationCode": "482916"
  }
}
```

#### Event Data Fields

| Field              | Type     | Description                                             |
| ------------------ | -------- | ------------------------------------------------------- |
| `cardId`           | `string` | The ID of the card being provisioned                    |
| `verificationCode` | `string` | 6-digit code the cardholder must enter in Google Wallet |

#### Webhook Handler Example

```javascript theme={null}
app.post('/webhooks/utgl', async (req, res) => {
  const signature = req.headers['x-utgl-signature'];
  if (!verifyWebhookSignature(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  if (event.event === 'cardaccount.googlepay.verification-code-delivered') {
    const { cardId, verificationCode } = event.data;

    // Option 1: Display the code in your app
    await notifyCardholder(cardId, {
      type: 'google_pay_verification',
      code: verificationCode,
      message: 'Enter this code in Google Wallet to complete setup'
    });

    // Option 2: Log for support reference
    await logProvisioningEvent(cardId, verificationCode);
  }

  res.status(200).json({ received: true });
});
```

***

## Notification Channels

When a verification code is generated, it is delivered through multiple channels:

| Channel     | Recipient          | Purpose                                                                           |
| ----------- | ------------------ | --------------------------------------------------------------------------------- |
| **SMS**     | Cardholder's phone | Direct OTP delivery for Google Wallet verification                                |
| **Webhook** | Your system        | Programmatic notification via `cardaccount.googlepay.verification-code-delivered` |
| **Email**   | Cardholder's email | Confirmation of the provisioning request                                          |

<Note>
  The SMS is sent automatically by UTGL. The webhook allows you to **optionally** display the code within your own app for a better user experience.
</Note>

***

## Timing and Expiry

| Parameter         | Value                 |
| ----------------- | --------------------- |
| Code length       | 6 digits              |
| Code validity     | **10 minutes**        |
| Delivery channels | SMS + Webhook + Email |

<Warning>
  **Code Expiry:** The verification code expires after **10 minutes**. If the cardholder does not enter the code within this window, they must restart the "Add to Google Wallet" process from their device.
</Warning>

***

## Integration Guide

### Step 1: Configure Webhook Endpoint

Ensure your webhook endpoint is set up to receive `cardaccount.googlepay.verification-code-delivered` events.

See [Webhooks Overview](/issuing/guides/webhooks-1) for setup instructions.

### Step 2: Handle the Verification Code

When you receive the webhook, you can optionally surface the code in your app:

* **Push Notification** - Send a push notification to the cardholder's device with the code
* **In-App Display** - Show the code in a dedicated section of your app
* **SMS Fallback** - The cardholder will also receive the code via SMS (handled by UTGL)

### Step 3: Monitor Activation

After the cardholder enters the code, the card is activated in Google Wallet. You can verify the provisioning status through your card management flow.

***

## Best Practices

### User Experience

1. **Surface the Code** - Use the webhook to display the verification code in your app for a seamless experience
2. **Show Expiry Timer** - Display a countdown timer so the cardholder knows how long the code is valid
3. **Clear Instructions** - Guide the cardholder to enter the code in Google Wallet, not in your app

### Reliability

1. **Idempotency** - Use the event `id` field to prevent duplicate processing
2. **Event Logging** - Log all provisioning events for support and debugging
3. **Webhook Signature Verification** - Always verify incoming webhook signatures

### Security

1. **Don't Store Codes** - Treat verification codes as transient; do not persist them long-term
2. **Secure Display** - If displaying the code in your app, ensure the display is secure and time-limited
3. **Verify Webhook Origin** - Always validate webhook signatures before processing

***

## Troubleshooting

| Issue                                         | Possible Cause                                 | Solution                                                 |
| --------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
| Cardholder doesn't see "Add to Google Wallet" | Google Pay not enabled on card product         | Contact your solution manager to enable Google Pay       |
| No webhook received                           | Webhook endpoint not configured or unreachable | Verify webhook endpoint configuration and network access |
| SMS not received                              | No mobile number on file                       | Ensure the cardholder has a registered mobile number     |
| Code expired before entry                     | Cardholder took longer than 10 minutes         | Cardholder must restart the process from their device    |
| Provisioning fails after code entry           | Network or system error                        | Cardholder should retry; contact support if persistent   |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks Overview" icon="webhook" href="/issuing/guides/webhooks-1">
    Set up your webhook endpoint
  </Card>

  <Card title="Webhook Events" icon="bell" href="/issuing/guides/webhook-events-1">
    View all available webhook events
  </Card>
</CardGroup>