Getting Started with ZendFi - Accept Crypto in Minutes!

Endpoint

POST /api/v1/merchants

Request

No authentication required for this endpoint - everyone's welcome!

Headers

Content-Type: application/json

Body Parameters

{
  "name": "My Online Store", 
  "email": "payments@mystore.com",
  "business_address": "123 Main Street, San Francisco, CA 94102",
  "webhook_url": "https://mystore.com/webhooks/zendfi",
  "wallet_generation_method": "mnemonic"
}

{
  "name": "My Online Store",
  "email": "payments@mystore.com",
  "business_address": "123 Main Street, San Francisco, CA 94102",
  "webhook_url": "https://mystore.com/webhooks/zendfi",
  "wallet_generation_method": "simple"
}

{
  "name": "My Online Store",
  "email": "payments@mystore.com",
  "business_address": "123 Main Street, San Francisco, CA 94102",
  "webhook_url": "https://mystore.com/webhooks/zendfi",
  "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
}

Status: 200 OK

{
  "merchant": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Online Store",
    "wallet_address": "",
    "wallet_type": "mpc",
    "settlement_preference": "auto_usdc",
    "wallet_generation_method": "mpc_passkey"
  },
  "api_key": "zendfi_live_abc123def456...",
  "message": "Merchant created with non-custodial MPC wallet! Complete passkey setup to activate auto-settlements.",
  "security_note": "Non-custodial MPC wallet secured by your device biometrics (Face ID/Touch ID). We never hold your keys!",
  "next_steps": {
    "passkey_setup_url": "https://api.zendfi.tech/merchants/550e8400-e29b-41d4-a716-446655440000/setup-passkey",
    "setup_required": true,
    "estimated_time": "5 seconds with Face ID/Touch ID",
    "api_endpoints": {
      "register_start": "/api/v1/webauthn/register/start",
      "register_finish": "/api/v1/webauthn/register/finish"
    }
  },
  "warning": "Store this API key securely. It will not be shown again."
}

Status: 200 OK

{
  "merchant": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Online Store",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "wallet_type": "custodial",
    "settlement_preference": "auto_usdc",
    "wallet_generation_method": "mnemonic"
  },
  "api_key": "zendfi_live_abc123def456...",
  "message": "Merchant created with BIP39 mnemonic-derived wallet! Store your master mnemonic securely.",
  "security_note": "Your wallet can be recovered using the master mnemonic phrase. Keep it secure!",
  "next_steps": {
    "setup_required": false
  },
  "warning": "Store this API key securely. It will not be shown again."
}

Option A: Browser Setup (Easiest Way!)

1. Open the passkey_setup_url from your merchant creation response
2. Click "Setup Passkey"
3. Authenticate with Face ID/Touch ID/Windows Hello
4. Done! Your wallet is now active and ready to rock!

Option B: API Setup (For the Tech-Savvy!)

Prefer to do it programmatically? We've got you covered! Check out our Passkey Setup Guide for the API approach.

Create a Test Payment

curl -X POST https://api.zendfi.tech/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 1.00,
    "currency": "USD",
    "description": "Test Payment",
    "token": "USDC"
  }'

Response

{
  "id": "payment_abc123",
  "amount": 1.00,
  "currency": "USD",
  "status": "Pending",
  "qr_code": "solana:6qWDyySDsrWbUqXCzwaxVYc47xTaZVUEdeC9apdo6Ewa?amount=...",
  "payment_url": "https://api.zendfi.tech/pay/payment_abc123",
  "expires_at": "2025-10-26T12:30:00Z"
}

Test the Payment Flow

1. Open the payment_url in your browser
2. Connect a Solana wallet (Phantom, Solflare, etc.)
3. Approve the transaction
4. Check payment status (see below)

Endpoint

GET /api/v1/payments/:id/status

Request

curl -X GET https://api.zendfi.tech/api/v1/payments/payment_abc123/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "payment_abc123",
  "status": "Confirmed",
  "amount": 1.00,
  "transaction_signature": "5j7s6JP28XvC1...",
  "confirmed_at": "2025-10-26T12:15:30Z",
  "settlement_status": "pending"
}

Webhook Payload

{
  "event": "payment.confirmed",
  "payment": {
    "id": "payment_abc123",
    "amount": 1.00,
    "currency": "USD",
    "status": "Confirmed",
    "transaction_signature": "5j7s6JP28XvC1...",
    "customer_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "confirmed_at": "2025-10-26T12:15:30Z"
  },
  "timestamp": "2025-10-26T12:15:31Z"
}

Verify Webhook Signatures (Security First!)

Always verify webhook signatures to ensure they're really from ZendFi! See Webhook Security for the complete guide.

direct_token (For Crypto Enthusiasts!)

Why it's cool: Hold crypto directly, ride the wave, be a HODLer!

Node.js/Express

const express = require('express');
const axios = require('axios');

const app = express();
const ZENDFI_API_KEY = process.env.ZENDFI_API_KEY;

// Create payment
app.post('/api/checkout', async (req, res) => {
  try {
    const response = await axios.post(
      'https://api.zendfi.tech/api/v1/payments',
      {
        amount: req.body.amount,
        currency: 'USD',
        description: req.body.description,
        token: 'USDC'
      },
      {
        headers: {
          'Authorization': `Bearer ${ZENDFI_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    res.json(response.data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Webhook handler
app.post('/webhooks/zendfi', express.json(), (req, res) => {
  const { event, payment } = req.body;
  
  if (event === 'payment.confirmed') {
    console.log('Payment confirmed:', payment.id);
    // Fulfill order, grant access, etc.
  }
  
  res.status(200).send('OK');
});

app.listen(3000);

Python/Flask

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
ZENDFI_API_KEY = os.getenv('ZENDFI_API_KEY')

# Create payment
@app.route('/api/checkout', methods=['POST'])
def create_checkout():
    data = request.json
    
    response = requests.post(
        'https://api.zendfi.tech/api/v1/payments',
        json={
            'amount': data['amount'],
            'currency': 'USD',
            'description': data['description'],
            'token': 'USDC'
        },
        headers={
            'Authorization': f'Bearer {ZENDFI_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    
    return jsonify(response.json())

# Webhook handler
@app.route('/webhooks/zendfi', methods=['POST'])
def handle_webhook():
    data = request.json
    
    if data['event'] == 'payment.confirmed':
        print(f"Payment confirmed: {data['payment']['id']}")
        # Fulfill order, grant access, etc.
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)