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

# Wallets reference

> Shared and per-provider options for Apple Pay and Google Pay.

## Factories

```typescript theme={null}
overflow.applePay(options?: ApplePayElementOptions): ApplePayElement
overflow.googlePay(options?: GooglePayElementOptions): GooglePayElement
```

## Shared options

Both wallets extend the same base:

| Key           | Type                        | Default                         |
| ------------- | --------------------------- | ------------------------------- |
| `disabled`    | `boolean`                   | `false`                         |
| `id`          | `string`                    | auto                            |
| `ariaLabel`   | `string`                    | none                            |
| `locale`      | `string`                    | Overflow instance locale        |
| `required`    | `boolean`                   | `true`                          |
| `validate`    | `(value) => string \| null` | none                            |
| `transaction` | `WalletTransactionOptions`  | required for a chargeable sheet |
| `require`     | `WalletRequireOptions`      | `{}`                            |

### `WalletTransactionOptions`

```typescript theme={null}
type WalletTransactionOptions = {
  amount?: number;              // minor units (e.g. cents)
  currency?: string;            // ISO 4217, e.g. 'USD'
  countryCode?: string;         // ISO 3166-1 alpha-2, e.g. 'US'
  label?: string;               // shown above the total in the sheet
  lineItems?: { label: string; amount: number }[];
};
```

Amounts are minor units. Every supported wallet currency uses 2 decimals.

### `WalletRequireOptions`

```typescript theme={null}
type WalletRequireOptions = {
  name?: boolean;             // default false
  email?: boolean;            // default false
  phone?: boolean;            // default false
  billingAddress?: boolean;   // default false
  shippingAddress?: boolean;  // default false
};
```

Each `true` value asks the sheet to collect that field.

### Provider mapping

| `require` key     | Apple Pay                                                                                                 | Google Pay                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `name`            | Collected via billing contact                                                                             | Included with billing address automatically |
| `email`           | Collected via shipping contact (Apple returns email/phone in the shipping contact regardless of shipping) | `emailRequired: true`                       |
| `phone`           | Collected via billing contact                                                                             | Adds phone to billing address parameters    |
| `billingAddress`  | Collected via billing contact                                                                             | `billingAddressRequired: true`              |
| `shippingAddress` | Collected via shipping contact                                                                            | `shippingAddressRequired: true`             |

## Apple Pay-specific options

| Key                       | Type                                  | Default          |
| ------------------------- | ------------------------------------- | ---------------- |
| `buttonType`              | Apple button type union               | `'plain'`        |
| `buttonStyle`             | Apple button style union              | `'black'`        |
| `supportedNetworks`       | `string[]`                            | provider default |
| `renderApplePayCodeAs`    | `'modal' \| 'window'`                 | `'modal'`        |
| `recurringPaymentRequest` | Apple recurring payment request shape | none             |
| `requirements`            | `ApplePayRequirementOptions`          | `{}`             |

### `ApplePayRequirementOptions`

```typescript theme={null}
type ApplePayRequirementOptions = {
  shippingMethods?: unknown[];                    // passed through verbatim
  requiredBillingContactFields?: unknown[];        // replaces derived array
  requiredShippingContactFields?: unknown[];       // replaces derived array
};
```

When either `requiredBillingContactFields` or `requiredShippingContactFields` is set, it fully replaces the array derived from `require`. Use this as an escape hatch for fields not covered by `require` (e.g. `phoneticName`).

## Google Pay-specific options

| Key              | Type                          | Default          |
| ---------------- | ----------------------------- | ---------------- |
| `buttonType`     | Google button type union      | `'buy'`          |
| `buttonColor`    | Google button color union     | `'default'`      |
| `buttonSizeMode` | Google button size mode       | provider default |
| `requirements`   | `GooglePayRequirementOptions` | `{}`             |

### `GooglePayRequirementOptions`

```typescript theme={null}
type GooglePayRequirementOptions = {
  billingAddressParameters?: BillingAddressParameters;   // merged on top of derived params
  shippingAddressParameters?: ShippingAddressParameters; // passed through verbatim
  shippingOptionRequired?: boolean;
};
```

## Value

```typescript theme={null}
type WalletValue = {
  paymentToken: string;
  brand?: string;
  last4?: string;
  contact?: { email?: string; name?: string; phone?: string };
  billingAddress?: Address;
  shippingAddress?: Address;
};
```

## Events

Wallets emit `onReady`, `onChange`, `onSubmit`, `onError`, `onFocus`, `onBlur`, `onClick`, and `onExit`. `onEscapeKeyPressed` is not emitted from wallets (the sheet owns escape handling).

## Methods

* `wallet.mount(selector)`
* `wallet.update(partialOptions)`
* `wallet.unmount()`
* `wallet.destroy()`
* `wallet.on(event, handler)`

Wallets do not expose `.submit()`. The wallet button is the submit action.