Skip to main content

​
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

​
linkCode
string
Payment link code. Either linkCode or paymentId is required.
​
paymentId
string
Payment ID. Either linkCode or paymentId is required.
​
containerId
string
required
ID of the HTML element where the checkout will be mounted.
​
mode
string
default:"test"
test (Devnet) or live (Mainnet).
​
apiUrl
string
default:"https://api.zendfi.tech"
Custom API URL. Defaults to localhost:8080 in development.
​
onSuccess
function
Called when the payment is confirmed on-chain.
onSuccess: (payment: PaymentSuccessData) => void
​
onError
function
Called when any error occurs during checkout.
onError: (error: CheckoutError) => void
​
onLoad
function
Called when the checkout UI is fully loaded.
​
theme
CheckoutTheme
Custom theme overrides.
​
allowCustomAmount
boolean
default:"false"
Enable “Pay What You Want” mode.
​
paymentMethods
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

PropertyTypeDefault
primaryColorstring#667eea
backgroundColorstring#ffffff
borderRadiusstring12px
fontFamilystringSystem font stack
textColorstring#1a1a1a
buttonStylestringsolid

​
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>