Embedded Checkout

ZendFiEmbeddedCheckout renders a complete payment flow directly inside your page. It supports wallet connect (Phantom, Solflare, Backpack), QR code payments, and fiat bank transfers. No iframe, no redirect — it is a native DOM component.

Quick Start

import { ZendFiEmbeddedCheckout } from '@zendfi/sdk';

const checkout = new ZendFiEmbeddedCheckout({
  linkCode: 'abc123xyz',
  containerId: 'checkout-container',
  mode: 'test',
  onSuccess: (payment) => {
    console.log('Paid!', payment.transactionSignature);
  },
  onError: (error) => {
    console.error('Failed:', error.message);
  },
});

checkout.mount();

<div id="checkout-container"></div>

Configuration

EmbeddedCheckoutConfig

string

Payment link code. Either linkCode or paymentId is required.

string

Payment ID. Either linkCode or paymentId is required.

string

required

ID of the HTML element where the checkout will be mounted.

string

default:"test"

test (Devnet) or live (Mainnet).

string

default:"https://api.zendfi.tech"

Custom API URL. Defaults to localhost:8080 in development.

function

Called when the payment is confirmed on-chain.

onSuccess: (payment: PaymentSuccessData) => void

function

Called when any error occurs during checkout.

onError: (error: CheckoutError) => void

function

Called when the checkout UI is fully loaded.

CheckoutTheme

Custom theme overrides.

boolean

default:"false"

Enable “Pay What You Want” mode.

object

Show or hide specific payment methods.

paymentMethods: {
  walletConnect: true,   // Phantom, Solflare, etc.
  qrCode: true,          // Solana Pay QR code
  solanaWallet: true,     // Manual address entry
  bank: true,             // Fiat bank transfer (NGN)
}

Theming

Customize the look and feel:

const checkout = new ZendFiEmbeddedCheckout({
  linkCode: 'abc123xyz',
  containerId: 'checkout',
  theme: {
    primaryColor: '#667eea',
    backgroundColor: '#ffffff',
    borderRadius: '12px',
    fontFamily: 'Inter, sans-serif',
    textColor: '#1a1a1a',
    buttonStyle: 'solid', // 'solid' | 'outlined' | 'minimal'
  },
});

CheckoutTheme

Property	Type	Default
`primaryColor`	`string`	`#667eea`
`backgroundColor`	`string`	`#ffffff`
`borderRadius`	`string`	`12px`
`fontFamily`	`string`	System font stack
`textColor`	`string`	`#1a1a1a`
`buttonStyle`	`string`	`solid`

Callback Data

PaymentSuccessData

interface PaymentSuccessData {
  paymentId: string;
  transactionSignature: string;
  amount: number;
  token: string;
  merchantName: string;
}

CheckoutError

interface CheckoutError {
  code: string;
  message: string;
  details?: any;
}

Methods

mount()

Renders the checkout UI into the container element. Fetches payment data, renders the form, and starts polling for payment confirmation.

await checkout.mount();

unmount()

Removes the checkout UI and stops all polling.

checkout.unmount();

Payment Flow

Payment Methods

The checkout automatically detects available payment methods:

Wallet Connect

Auto-detects Phantom, Solflare, Backpack, Coinbase, and Trust wallet extensions.

QR Code

Displays a Solana Pay-compatible QR code for mobile wallets.

Manual Transfer

Shows the payment address for direct wallet transfers.

Bank Transfer

Fiat on-ramp via NGN bank transfer (when onramp is enabled on the payment link).

Browser Usage (CDN)

For non-bundled environments, import from a CDN:

<script type="module">
  import { ZendFiClient, ZendFiEmbeddedCheckout } from 'https://esm.sh/@zendfi/sdk';

  const client = new ZendFiClient({ apiKey: 'zfi_test_...' });

  const link = await client.createPaymentLink({
    amount: 10.00,
    description: 'Test Payment',
  });

  const checkout = new ZendFiEmbeddedCheckout({
    linkCode: link.link_code,
    containerId: 'checkout',
    onSuccess: (payment) => alert('Paid!'),
  });

  checkout.mount();
</script>

<div id="checkout"></div>

​Embedded Checkout

​Quick Start

​Configuration

​EmbeddedCheckoutConfig

​Theming

​CheckoutTheme

​Callback Data

​PaymentSuccessData

​CheckoutError

​Methods

​mount()

​unmount()

​Payment Flow

​Payment Methods

Wallet Connect

QR Code

Manual Transfer

Bank Transfer

​Browser Usage (CDN)

Embedded Checkout

Quick Start

Configuration

EmbeddedCheckoutConfig

Theming

CheckoutTheme

Callback Data

PaymentSuccessData

CheckoutError

Methods

mount()

unmount()

Payment Flow

Payment Methods

Browser Usage (CDN)