Documentation Index Fetch the complete documentation index at: https://docs.zendfi.tech/llms.txt
Use this file to discover all available pages before exploring further.
Quickstart This guide takes you from zero to a working payment integration. By the end, you will have created a test payment and received a webhook confirmation.
Prerequisites
Node.js 18 or later
A ZendFi account (sign up here )
Your test API key (starts with zfi_test_)
Option A: Add to an Existing Project If you already have a Next.js or Express project, the fastest path is the CLI:
This auto-detects your framework, installs the SDK, and scaffolds the necessary files. Skip to Step 3 if you go this route.
Option B: Start from Scratch Step 1: Create a New Project Next.js E-commerce
Next.js SaaS
Express API
npx create-zendfi-app my-store --template nextjs-ecommerce cd my-store
Add your test API key to the .env file:
ZENDFI_API_KEY = zfi_test_your_key_here ZENDFI_WEBHOOK_SECRET = your_webhook_secret_here
Test keys route all transactions to Solana devnet. No real money is involved. You can generate a test key from your dashboard . Step 3: Create a Payment TypeScript (SDK)
cURL
CLI
import { ZendFiClient } from '@zendfi/sdk' ; const zendfi = new ZendFiClient ({ apiKey: process . env . ZENDFI_API_KEY , }); const payment = await zendfi . createPayment ({ amount: 25.00 , description: 'Quickstart test payment' , customer_email: 'test@example.com' , }); console . log ( 'Payment ID:' , payment . id ); console . log ( 'Checkout URL:' , payment . payment_url );
curl -X POST https://api.zendfi.tech/api/v1/payments \ -H "Authorization: Bearer zfi_test_your_key" \ -H "Content-Type: application/json" \ -d '{ "amount": 25.00, "currency": "USD", "description": "Quickstart test payment", "customer_email": "test@example.com" }'
export ZENDFI_API_KEY = zfi_test_your_key npx @zendfi/cli payment create --amount 25 --description "Quickstart test"
The response includes a payment_url — open it in your browser to see the hosted checkout page.
Step 4: Complete the Payment Open the checkout URL in your browser. You will see ZendFi’s hosted checkout page with:
The payment amount and description
A QR code for Solana wallet apps
A wallet address for direct transfers
A countdown timer showing when the payment expires
Connect a devnet-funded wallet (like Phantom set to devnet) and complete the payment.
Need devnet SOL or USDC? Use the Solana faucet for SOL, then swap for devnet USDC. Step 5: Handle Webhooks When the payment confirms on-chain, ZendFi sends a webhook to your configured endpoint.
Next.js (App Router)
Express
app/api/webhooks/zendfi/route.ts
import { createNextWebhookHandler } from '@zendfi/sdk/nextjs' ; export const POST = createNextWebhookHandler ({ secret: process . env . ZENDFI_WEBHOOK_SECRET ! , handlers: { 'payment.confirmed' : async ( payment ) => { console . log ( 'Payment confirmed:' , payment . id ); // Fulfill the order, send confirmation email, etc. }, 'payment.failed' : async ( payment ) => { console . log ( 'Payment failed:' , payment . id ); }, }, });
import express from 'express' ; import { createExpressWebhookHandler } from '@zendfi/sdk/express' ; const router = express . Router (); router . post ( '/zendfi' , express . raw ({ type: 'application/json' }), createExpressWebhookHandler ({ secret: process . env . ZENDFI_WEBHOOK_SECRET ! , handlers: { 'payment.confirmed' : async ( payment ) => { console . log ( 'Payment confirmed:' , payment . id ); }, 'payment.failed' : async ( payment ) => { console . log ( 'Payment failed:' , payment . id ); }, }, }) ); export default router ;
Step 6: Test Webhooks Locally Use the CLI to create a tunnel and forward webhooks to your local server:
npx @zendfi/cli webhooks --port 3000
This starts a local server, creates a public tunnel (via ngrok or Cloudflare), and gives you a URL to configure as your webhook endpoint in the dashboard.
What Happens Next Once you are comfortable with test mode:
Set up webhook security to verify signatures in production.Switch to live mode by using a zfi_live_ API key.Explore subscriptions , invoices , and payment links for more advanced flows.
Explore Further
Full API Reference Every endpoint, parameter, and response field documented.
SDK Reference Type-safe client with auto-retries, interceptors, and embedded checkout.
Next.js Guide Complete integration walkthrough for Next.js App Router.
Express Guide Build a payment API with Express and the ZendFi SDK.
