Quickstart

Accept your first payment in under five minutes. No blockchain experience required.

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:

npx @zendfi/cli init

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

npx create-zendfi-app my-store --template nextjs-ecommerce
cd my-store

Step 2: Configure Your API Key

Add your test API key to the .env file:

.env

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)

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: '[e-mail]',
});

console.log('Payment ID:', payment.id);
console.log('Checkout URL:', payment.payment_url);

cURL

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": "[e-mail]"
  }'

CLI

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)

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);
    },
  },
});

Express

src/routes/webhooks.ts

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:

1. Set up webhook security to verify signatures in production.
2. Switch to live mode by using a zfi_live_ API key.
3. 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.