Docs/API Integration

API Integration

Build custom checkout flows and backend integrations.

Overview

While the widget is the easiest way to accept payments, the Fivo API gives you full control for custom integrations. Use the API to:

Build custom checkout experiences
Query payment history programmatically
Integrate with your existing backend systems
Create payments from server-side code

Base URL

https://api.fivo.finance

Production API

This is the production API endpoint. All requests are processed on mainnet. We'll notify all merchants before any breaking changes.

Authentication

The Fivo API uses two authentication methods:

JWT Tokens

For dashboard and user sessions. Obtained after login. Expires after 15 minutes.

Authorization: Bearer <token>

API Keys

For server-to-server integrations. Created in dashboard. Don't expire but can be revoked.

X-API-Key: <api_key>

Creating an API Key

Log in to your Fivo Dashboard
Navigate to API Keys
Click Create New Key
Give your key a descriptive name (e.g., "Production Server")
Copy the key immediately - it won't be shown again!

Keep Your Keys Secret

Never expose API keys in client-side code. API keys should only be used in server-side applications where they can be kept secret.

Example: Check Payment Status

After a customer pays via the widget, you can check the payment status:

Check Payment Status

// Using fetch (Node.js/Browser)
const response = await fetch(
  'https://api.fivo.finance/payments/abc123-payment-id/status'
);

const data = await response.json();
console.log(data);

// Response:
{
  "success": true,
  "data": {
    "id": "abc123-payment-id",
    "status": "completed",
    "is_cross_chain": false,
    "amount": 49.99,
    "tx_hash": "0x123...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Example: List Your Payments

Query your payment history with filters. Requires authentication.

List Payments with Filters

// Using fetch with API Key authentication
const response = await fetch(
  'https://api.fivo.finance/payments?status=completed&limit=10',
  {
    headers: {
      'X-API-Key': 'your_api_key_here'
    }
  }
);

const data = await response.json();
console.log(data);

// Response:
{
  "success": true,
  "data": {
    "payments": [
      {
        "id": "payment-1",
        "amount": 49.99,
        "currency": "USDC",
        "status": "completed",
        "tx_hash": "0x123...",
        "source_chain": "MATIC-AMOY",
        "created_at": "2024-01-15T10:30:00Z"
      },
      // ... more payments
    ],
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

cURL Examples

For quick testing, you can use cURL from the command line:

Get Payment Status (cURL)

# Get payment status (public endpoint)
curl https://api.fivo.finance/payments/PAYMENT_ID/status

# List your payments (requires API key)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/payments?status=completed&limit=10"

# Get merchant wallet info (public endpoint)
curl https://api.fivo.finance/merchants/MERCHANT_ID/wallet

SDKs & Libraries

Official SDKs are coming soon. In the meantime, you can use standard HTTP libraries in any language to interact with the API.

Node.js SDK

Coming soon

Python SDK

Coming soon

PHP SDK

Coming soon

Rate Limits

The API has rate limits to ensure fair usage and system stability:

Endpoint	Limit	Window
General API	100 requests	per minute
Authentication	5 requests	per 5 minutes
Withdrawals	10 requests	per 10 minutes

When you exceed a rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Full API Reference

See the complete list of endpoints, parameters, and response formats.

View API Reference