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

Checkout Sessions

Checkout Sessions are the recommended way to accept payments from a server-side integration. Your server creates a session, redirects the customer to a Fivo-hosted checkout page, and verifies the payment when the customer returns.

When to use what

Widget Embed

Fixed products, donations, static sites

Backend: No

Widget + data-amount-from

Shopping carts, dynamic totals

Backend: No

Direct Link

Emails, social media, QR codes

Backend: No

Checkout Sessions

E-commerce, SaaS, order fulfillment

Backend: Yes (API key)

Method	Best for	Backend needed?
Widget Embed	Fixed products, donations, static sites	No
Widget + `data-amount-from`	Shopping carts, dynamic totals	No
Direct Link	Emails, social media, QR codes	No
Checkout Sessions	E-commerce, SaaS, order fulfillment	Yes (API key)

Full example (Node.js / Express)

server.js

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

const FIVO_API = 'https://api.fivo.finance';
const FIVO_API_KEY = process.env.FIVO_API_KEY;

// 1. Customer clicks "Pay": create a session and redirect
app.post('/checkout', async (req, res) => {
  const response = await fetch(FIVO_API + '/checkout/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': FIVO_API_KEY,
    },
    body: JSON.stringify({
      amount: req.body.amount,
      currency: 'USDC',
      // Fivo appends ?session_id=cs_live_... automatically
      return_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cancel',
      metadata: { order_id: req.body.orderId },
    }),
  });

  const { data } = await response.json();
  res.redirect(303, data.url);
});

// 2. Customer returns after payment: verify and fulfill
app.get('/success', async (req, res) => {
  const response = await fetch(
    FIVO_API + '/checkout/sessions/' + req.query.session_id,
    { headers: { 'X-API-Key': FIVO_API_KEY } }
  );
  const { data } = await response.json();

  if (data.status === 'complete' && data.payment) {
    // Fulfill the order
    res.send('Payment confirmed! TX: ' + data.payment.tx_hash);
  } else {
    res.send('Payment pending. Status: ' + data.status);
  }
});

app.listen(3000);

cURL example

Create a Checkout Session

curl -X POST https://api.fivo.finance/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fivo_live_abc123..." \
  -d '{
    "amount": "49.99",
    "currency": "USDC",
    "return_url": "https://yoursite.com/success",
    "metadata": { "order_id": "order_123" }
  }'

Full reference

See the for all parameters, response schemas, and session status values.API Reference

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): public endpoint, no auth required
const response = await fetch(
  `https://api.fivo.finance/payments/abc123-payment-id/status`
);

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

// Response (minimal data for security):
{
  "success": true,
  "data": {
    "id": "abc123-payment-id",
    "status": "completed",
    "is_cross_chain": false,
    "cctp_attestation_status": null,
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Example: List Your Payments

Query your payment history with filters. Requires authentication.

List Payments with Filters

// Using fetch with JWT authentication (from dashboard login)
const response = await fetch(
  `https://api.fivo.finance/payments?status=completed&limit=10`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    }
  }
);

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

// Response:
{
  "success": true,
  "data": {
    "payments": [
      {
        "id": "payment-1",
        "amount": "49.99",
        "currency": "USDC",
        "status": "completed",
        "txHash": "0x123...",
        "sourceChain": "MATIC",
        "customerEmail": "customer@example.com",
        "reference": "ORD-2024-001",
        "createdAt": "2025-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 JWT from login)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.fivo.finance/payments?status=completed&limit=10"

# Get merchant wallet info (public endpoint)
# MERCHANT_ID format: fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
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:

API Key endpoints

200 requests per minute

Per: API Key

General API

100 requests per minute

Per: IP

Payment creation (widget)

20 requests per minute

Per: IP

5 requests per 5 minutes

Per: IP + email

Registration

3 requests per 15 minutes

Per: IP

Password Reset

3 requests per 15 minutes

Per: IP + email

2FA verification

5 requests per 5 minutes

Per: IP

Withdrawals

10 requests per 10 minutes

Per: IP

Contact form

3 requests per 15 minutes

Per: IP

Endpoint	Limit	Window	Per
API Key endpoints	200 requests	per minute	API Key
General API	100 requests	per minute	IP
Payment creation (widget)	20 requests	per minute	IP
Login	5 requests	per 5 minutes	IP + email
Registration	3 requests	per 15 minutes	IP
Password Reset	3 requests	per 15 minutes	IP + email
2FA verification	5 requests	per 5 minutes	IP
Withdrawals	10 requests	per 10 minutes	IP
Contact form	3 requests	per 15 minutes	IP

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

Full API Reference

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

View API Reference