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

# Overview

> Customize the PayNext SDK appearance and behavior to match your brand and optimize your checkout flow.

Customize the PayNext SDK to align with your brand identity and optimize checkout completion. The SDK provides two customization layers:

| Layer          | What you control                                         |
| :------------- | :------------------------------------------------------- |
| **Visual**     | Styling, colors, typography, text content, translations  |
| **Functional** | Payment methods, validation rules, callbacks, form logic |

## Visual Customization

Control the appearance and text content of the checkout form to match your brand identity.

### Style the Form

Style elements to integrate seamlessly with your website design:

* **CSS-in-JS styling**: Apply React CSS properties directly to components
* **CSS class names**: Use custom classes for advanced styling and responsive design
* **Component-specific controls**: Separate styling for inputs, buttons, and wallet options

### Customize Text & Translations

Adapt text content and support multiple languages:

* **Custom labels and messages**: Override default text
* **30+ built-in languages**: Automatic browser detection with manual override
* **RTL support**: Layout adjusts for right-to-left languages
* **Partial overrides**: Change specific text while keeping defaults

<Tip>
  Use font sizes of at least 16px on mobile to prevent zoom and ensure sufficient color contrast for accessibility.
</Tip>

## Functional Configuration

Define how the checkout processes payments and integrates with your app.

### Manage Payment Methods

Control which options are available and how they're displayed:

* **Card network filtering**: Accept specific card types
* **Layout modes**: `default` (all options) or `compact` (wallets prioritized)
* **Environment management**: Switch between sandbox and production

### Prefetch the CDN Bundle

The PayNext SDK uses a **CDN-based architecture** with a small initial JavaScript bundle. The SDK loads dynamically from the PayNext CDN when you mount the checkout form, minimizing your application's initial bundle size.

**Preload optimization:** Use `PayNextSDK.preload()` to prefetch the SDK bundle before mounting the checkout form. This reduces the first render time when you can anticipate user navigation (e.g., on pricing pages, when hovering over subscribe buttons, or during checkout page navigation).

```ts theme={"system"}
if (typeof window !== 'undefined') {
  PayNextSDK.preload('production').catch(console.error)
}
```

<Tip>
  Preloading is optional but recommended when you can anticipate checkout usage. Always guard the call with a browser check (`typeof window !== 'undefined'`) to keep SSR harmless.
</Tip>

**Coordinate post-load work:** Use the `onCheckoutLoaded` callback with the `LoadedResult` type to detect when the checkout form finishes loading. Once `success` is `true`, hide skeletons or trigger follow-up requests; if `success` is `false`, surface the embedded `CheckoutError`.

```tsx theme={"system"}
import { PayNextCheckout, type LoadedResult } from '@paynext/sdk'

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  // ... other config
  onCheckoutLoaded: (result: LoadedResult) => {
    if (!result.success) {
      console.error('Checkout failed to load:', result.error)
      return
    }

    // Checkout form is ready—hide loading skeletons or kick off follow-up work
    console.info('Checkout ready')
  },
})
```

### Handle Integration Patterns

Respond to events and integrate with your workflow:

* **Success and error callbacks**: Custom logic for completion and failure
* **Initial load callback**: Run onboarding UI once `onCheckoutLoaded` signals the checkout is ready (or display a retry on failure)
* **Environment-specific config**: Adapt per environment (dev, staging, prod)

<Info>
  Appearance and behavior layers can be applied independently or combined. Start with defaults, then add only what your use case needs.
</Info>

<Info>
  Digital wallet availability (Apple Pay, Google Pay, PayPal, Venmo, Cash App Pay) depends on both your dashboard configuration and the user's device/browser capabilities.
</Info>