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

# Frontend components - component usage

> How to integrate frontend components to embed payment capabilities into merchant pages.

Waffo provides the frontend SDK `@waffo/payment-sdk`, which supports directly integrating payment and card binding capabilities into merchant pages.

## Installation

```bash theme={null}
npm install @waffo/payment-sdk
```

## Initialization

```typescript theme={null}
import WaffoSDK from '@waffo/payment-sdk';

const sdk = new WaffoSDK('your-client-api-key', {
  env: 'prod',    // 'prod' | 'testing' | 'sandbox'
  locale: 'en'    // optional, defaults to 'en'
});
```

## Feature overview

| Feature           | Method                     | Description                                                 |
| ----------------- | -------------------------- | ----------------------------------------------------------- |
| Card tokenization | `sdk.tokenizationSubmit()` | Securely submits card information and generates a token     |
| Embedded checkout | `WaffoSDK.renderIframe()`  | Embeds the Waffo checkout as an iframe in the merchant page |

## Card tokenization (tokenizationSubmit)

Encrypts and submits the user's card information to Waffo. The merchant server never touches the plaintext card number.

### Prerequisites

The merchant backend must first call the [Generate API](/en/developer-docs/integration/tokenization/generate) to obtain a `tokenSessionId`.

### Submit card

```typescript theme={null}
const result = await sdk.tokenizationSubmit('tokenSessionId', {
  tokenData: {
    pan: '4111111111111111',  // Card number
    name: 'John Doe',         // Cardholder name
    expiry: '12/2025',        // Expiry date MM/YYYY
    cvv: '123'                // CVV (optional)
  },
  billingAddress: {            // Optional
    countryCode: 'USA',
    region: 'CA',
    city: 'San Francisco',
    postalCode: '94102',
    address: '123 Main St'
  }
});
```

### Handle result

```typescript theme={null}
if (result.success) {
  if (result.data.validateUrl) {
    // 3DS verification required, redirect the user
    window.location.href = result.data.validateUrl;
  } else {
    // Card binding successful, wait for Webhook to receive tokenId
  }
}
```

For the complete flow, see [Card binding and token management](/en/developer-docs/integration/tokenization/overview).

## Embedded checkout (renderIframe)

Embeds the Waffo checkout as an iframe in the merchant page. Suitable for merchants who do not want to build their own checkout UI.

```typescript theme={null}
WaffoSDK.renderIframe({
  // Customize theme color, logo, Apple Pay, etc.
});
```

Supports:

* Custom theme colors
* Custom logo
* Apple Pay / Google Pay buttons
* Multiple languages

## Other frontend components

### Google Pay

Integrate a Google Pay button on the merchant website or in the app. After the user clicks it, they can complete the payment using a credit/debit card in their Google account.

**Supported options**:

* **Web SDK integration**: Embed Google Pay on web pages via the Waffo Web SDK
* **Android SDK integration**: Integrate via the Google Pay Android SDK
* **Built into checkout**: Contact Waffo to enable the Google Pay button on the checkout page

For details, see [Google Pay frontend integration](/en/developer-docs/integration/elements/frontend-integration).

### Apple Pay

Complete the payment by passing the Apple Pay encrypted token via the `paymentTokenData` parameter.

### Checkout appearance customization

Pass JSON CSS variables via the `paymentInfo.cashierAppearance` parameter to customize the checkout theme color, fonts, and more.

Use the `paymentInfo.cashierLanguage` parameter to set the checkout language (IETF BCP 47 format, for example `en-HK`, `zh-Hant-HK`).