> ## 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)

The merchant frontend passes plaintext card data to the SDK, which encrypts the data before transmission. With the frontend SDK binding flow, the merchant does not need PCI DSS certification as long as its backend neither retains nor transmits plaintext card data.

### Prerequisites

The merchant backend must first call the [Generate API](/docs/api-reference/waffo-tokenization-api/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/2028',        // 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
  }
}
```

If the Generate request includes `notifyUrl`, Waffo also sends `TOKENIZATION_NOTIFICATION` when card binding completes, the Token status changes, or Token data is updated. Use `result.tokenId` as the idempotency key when updating locally stored Token data.

For the complete flow, see [Card binding and token management](/docs/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

## Checkout appearance customization

The checkout appearance theme (`cashierAppearance`), language (`cashierLanguage`), and payment method filtering are configured through the order-creation `paymentInfo` parameter. For the full value ranges, format, and examples, see [Checkout customization](/docs/en/developer-docs/integration/checkout/customization).