FivoDocs
Docs/API Reference

API Reference

Complete reference for all Fivo API endpoints.

Base URL

https://api.fivo.finance

Authentication

Protected endpoints require authentication via API Key or JWT token.

Authentication Headers
# Option 1: API Key (recommended for server-side)
X-API-Key: your_api_key_here

# Option 2: JWT Token (for user sessions)
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Idempotency

The Fivo API has built-in idempotency protections to prevent duplicate operations:

Payments

Each payment's is unique. If you submit a payment with a that already exists, the API returns with the existing payment data instead of creating a duplicate.txHashtxHash200

Checkout Sessions

Each session has a unique . A single checkout session can only produce one payment.payment_id

Notifications

Webhook deliveries and emails use an internal idempotency system to prevent duplicate notifications for the same event.

i

Handling POST responses

When a POST endpoint returns instead of , it means the resource already exists. Your code should handle both status codes as success.200201

Payments

POST/payments/create-public
Create payment from widget

Creates a payment record after a successful blockchain transaction. This endpoint is called automatically by the Fivo widget.

Request Body

merchantIdstringRequired

Merchant ID with prefix (fivo_live_UUID)

txHashstringRequired

Blockchain transaction hash (0x...)

amountnumberRequired

Payment amount (0.01 - 1,000,000)

expectedAmountnumberOptional

Expected amount for on-chain validation. Required for same-chain payments, optional for cross-chain.

tokenstringRequired

"USDC" or "EURC"

chainIdnumberRequired

Source blockchain chain ID

fromAddressstringRequired

Sender wallet address

toAddressstringRequired

Merchant wallet address

isCrossChainbooleanOptional

Whether this is a CCTP cross-chain payment

bridgeKitobjectOptional

Bridge Kit payload for cross-chain payments: { burnTxHash: string, mintTxHash?: string }. Required for Bridge Kit cross-chain flow.

feeQuoteobjectOptional

Signed fee quote for legacy CCTP cross-chain (deprecated). Use bridgeKit instead.

destinationChainIdnumberOptional

Destination chain (if cross-chain)

sessionIdstringOptional

Checkout session ID to link this payment to (if using checkout sessions)

customerEmailstringRequired

Customer email address for receipt delivery. Max 255 chars.

referencestringOptional

Your internal reference (order ID, invoice number). Max 255 chars.

descriptionstringOptional

Payment description. Max 500 chars.

metadataobjectOptional

Custom key-value pairs for your internal use. Max 10KB.

Example Request
const response = await fetch(`https://api.fivo.finance/payments/create-public`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchantId: 'fivo_live_969c4442-5741-4624-8305-427391683190',
    txHash: '0x1234567890abcdef...',
    amount: 49.99,
    expectedAmount: 49.99,
    token: 'USDC',
    chainId: 137,
    fromAddress: '0xCustomerWallet...',
    toAddress: '0xMerchantWallet...',
    isCrossChain: false,
    customerEmail: 'customer@example.com',
    reference: 'ORD-2024-001',
    metadata: { product_id: 'plan_pro' }
  })
});
Response (201)
{
  "success": true,
  "data": {
    "paymentId": "payment-uuid-here",
    "status": "completed",
    "isCrossChain": false
  }
}
i

Minimal response

This endpoint returns only the fields needed by the widget. To get full payment details (amount, tx_hash, etc.), use with authentication.GET /payments/:id
GET/payments/:id/status
Get payment status

Returns the current status of a payment. Useful for polling payment completion.

Path Parameters

idstringRequired

Payment UUID

Response
{
  "success": true,
  "data": {
    "id": "payment-uuid-here",
    "status": "completed",
    "is_cross_chain": true,
    "cctp_attestation_status": null,
    "updated_at": "2026-03-04T10:32:00.000Z"
  }
}
i

Minimal public endpoint

This is a public endpoint that returns only status fields. Sensitive data like amounts, tx_hash, and addresses are not included. Use with authentication for full details. Note: is for Bridge Kit payments (current system). It only has values for legacy CCTP relayer payments.GET /payments/:idcctp_attestation_statusnull

Payment Status Values

StatusDescription
completedPayment successful and funds received
pendingPayment created, awaiting processing
pending_attestationCross-chain: waiting for CCTP attestation from Circle
ready_to_mintCross-chain: attestation received, minting on destination chain
minted_pending_transferCross-chain: minted, transferring to merchant wallet
failedPayment failed (check failure_reason)
GET/payments
Auth RequiredList merchant payments

Returns paginated list of payments for the authenticated merchant.

Query Parameters

statusstringOptional

Filter: "pending", "completed", "failed"

currencystringOptional

Filter: "USDC" or "EURC"

startDatestringOptional

Filter: ISO date string

endDatestringOptional

Filter: ISO date string

searchstringOptional

Search in tx_hash, from_address, customer_email, reference (min 3 chars)

limitnumberOptional

Results per page (default: 50)

offsetnumberOptional

Pagination offset (default: 0)

sortBystringOptional

Sort field (e.g., "created_at", "amount")

sortDirectionstringOptional

"asc" or "desc"

sincestringOptional

ISO datetime: only return payments created after this date. Useful for real-time polling.

Example Request
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.fivo.finance/payments?status=completed&limit=10&sortBy=created_at&sortDirection=desc"
GET/payments/:id
Auth RequiredGet payment details

Returns full details of a specific payment including all CCTP fields.

GET/payments/api/list
Auth RequiredList payments (API Key)

Returns paginated list of payments for the merchant authenticated via API Key. Useful for server-side reconciliation and verifying webhook data.

Query Parameters

statusstringOptional

Filter: "pending", "completed", "failed"

currencystringOptional

Filter: "USDC" or "EURC"

startDatestringOptional

Filter: ISO date string

endDatestringOptional

Filter: ISO date string

searchstringOptional

Search in tx_hash, from_address, customer_email, reference (min 3 chars)

limitnumberOptional

Results per page (default: 50, max: 200)

offsetnumberOptional

Pagination offset (default: 0)

sortBystringOptional

Sort field (e.g., "created_at", "amount")

sortDirectionstringOptional

"asc" or "desc"

sincestringOptional

ISO datetime: only return payments created after this date

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/payments/api/list?status=completed&limit=10"
Response
{
  "success": true,
  "data": {
    "payments": [
      {
        "id": "payment-uuid",
        "amount": "49.990000",
        "currency": "USDC",
        "status": "completed",
        "tx_hash": "0x1234567890abcdef...",
        "from_address": "0xCustomer...",
        "to_address": "0xMerchant...",
        "source_chain": "BASE",
        "is_cross_chain": false,
        "customer_email": "customer@example.com",
        "reference": "ORD-2024-001",
        "metadata": { "product_id": "plan_pro" },
        "created_at": "2026-02-28T10:30:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}
GET/payments/api/:id
Auth RequiredGet payment details (API Key)

Returns full details of a specific payment. Use this to verify a payment after receiving a webhook notification.

Path Parameters

idstringRequired

Payment UUID

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/payments/api/abc123-payment-uuid"
Response
{
  "success": true,
  "data": {
    "id": "abc123-payment-uuid",
    "amount": "49.990000",
    "expected_amount": "49.990000",
    "currency": "USDC",
    "status": "completed",
    "tx_hash": "0x1234567890abcdef...",
    "from_address": "0xCustomer...",
    "to_address": "0xMerchant...",
    "source_chain": "BASE",
    "destination_chain": null,
    "is_cross_chain": false,
    "bridge_provider": null,
    "customer_email": "customer@example.com",
    "reference": "ORD-2024-001",
    "metadata": { "product_id": "plan_pro" },
    "created_at": "2026-02-28T10:30:00.000Z",
    "updated_at": "2026-02-28T10:30:00.000Z"
  }
}
i

Typical flow

1. Receive webhook → 2. Verify with → 3. Fulfill the order.payment.completedGET /payments/api/:id
GET/payments/cctp-fee
Estimate cross-chain fee

Returns a signed fee quote for a cross-chain (CCTP) payment. The widget calls this automatically, but you can use it for custom integrations to show fee breakdowns before the user pays.

Query Parameters

destinationChainstringRequired

Destination blockchain name (e.g., "ETH", "BASE", "ARB")

productPricestringRequired

Product price in USD (e.g., "49.99")

Example Request
curl "https://api.fivo.finance/payments/cctp-fee?destinationChain=BASE&productPrice=49.99"
Response
{
  "success": true,
  "data": {
    "productPrice": 49.99,
    "amountToBurn": 50.74,
    "feeGas": 0.5,
    "feeCircle": 0.25,
    "feeTotal": 0.75,
    "totalUserPays": 50.74,
    "merchantReceives": 49.99,
    "destinationChain": "BASE",
    "validUntil": 1739871300,
    "validForSeconds": 300,
    "breakdown": {
      "gasEstimateUSD": 0.35,
      "gasWithBuffer": 0.5,
      "minGasFee": 0.5,
      "bufferPercent": 40
    },
    "signature": "hmac-sha256-hex..."
  }
}
i

Signed quote

The response includes an HMAC signature. When creating a cross-chain payment via , pass the quote fields back as the parameter. The backend verifies the signature to prevent fee manipulation.POST /payments/create-publicfeeQuote

Merchants

GET/merchants/:id/wallet
Get merchant wallet address

Returns the merchant's wallet address and blockchain. Used by the widget to know where to send payments.

Response
{
  "success": true,
  "data": {
    "wallet": {
      "id": "wallet-uuid",
      "address": "0x1234567890abcdef...",
      "blockchain": "MATIC",
      "chainId": 137
    }
  }
}
GET/merchants/:id/info
Get merchant public info

Returns public merchant information like name and accepted currencies.

Response
{
  "success": true,
  "data": {
    "name": "My Store",
    "blockchain": "MATIC",
    "accepted_currencies": "USDC,EURC"
  }
}

Checkout Sessions

Checkout Sessions let you create a Fivo-hosted payment page and redirect your customer to it. After payment, the customer is redirected back to your site. Similar to Stripe Checkout.

i
All Checkout Session endpoints (except ) require API Key authentication./public
POST/checkout/sessions
Auth RequiredCreate checkout session

Creates a new checkout session and returns a URL to redirect your customer to.

Request Body

amountstring | numberOptional

Payment amount (0.01 - 1,000,000). Omit for variable amount.

currencystringOptional

"USDC" or "EURC". Defaults to "USDC".

return_urlstringRequired

URL to redirect after payment. Must be HTTPS in production.

cancel_urlstringOptional

URL to redirect on cancel. Must be HTTPS in production.

metadataobjectOptional

Up to 5 key-value pairs for your reference (e.g. order_id).

expires_innumberOptional

Session lifetime in seconds (60 - 86400). Default: 1800 (30 min).

Example Request
curl -X POST https://api.fivo.finance/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": "49.99",
    "currency": "USDC",
    "return_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "metadata": { "order_id": "order_123" }
  }'
Response (201)
{
  "success": true,
  "data": {
    "id": "cs_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://checkout.fivo.finance?session=cs_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "expires_at": "2026-02-18T11:00:00.000Z"
  }
}
GET/checkout/sessions/:id
Auth RequiredGet session details

Returns the session status and linked payment data. Use this to verify payment completion after the customer returns to your site.

Response
{
  "success": true,
  "data": {
    "id": "cs_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "complete",
    "amount": "49.99",
    "currency": "USDC",
    "metadata": { "order_id": "order_123" },
    "return_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "payment": {
      "id": "payment-uuid",
      "status": "completed",
      "tx_hash": "0x1234567890abcdef...",
      "amount": "49.99",
      "is_cross_chain": false
    },
    "created_at": "2026-02-18T10:30:00.000Z",
    "expires_at": "2026-02-18T11:00:00.000Z"
  }
}

Session Status Values

StatusDescription
openSession created, waiting for customer to pay
completePayment confirmed and funds received
expiredSession expired before payment was made
GET/checkout/sessions/:id/public
Get session (widget-only)

Public endpoint used by the checkout widget to load session details. Returns only the fields needed to render the payment UI (no metadata). You do not need to call this endpoint directly.

API Keys

i
All API Key endpoints require JWT authentication (logged-in merchant session). API Keys themselves cannot be used to manage other API Keys.
POST/api-keys
Auth RequiredCreate new API key

Request Body

namestringRequired

Descriptive name for the key (1-50 chars)

Response
{
  "success": true,
  "message": "API key created successfully",
  "data": {
    "id": "key-uuid",
    "name": "Production Server",
    "key": "fivo_live_abc123...",
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}
!

Save Your Key

The full API key is only shown once at creation time. Store it securely. If lost, you'll need to create a new key.
GET/api-keys
Auth RequiredList API keys

Returns all API keys for the authenticated merchant. Keys are masked for security (only last 4 characters shown).

Response
{
  "success": true,
  "data": [
    {
      "id": "key-uuid-1",
      "name": "Production Server",
      "last4": "••••",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "key-uuid-2",
      "name": "Staging Server",
      "last4": "••••",
      "created_at": "2024-01-10T08:00:00.000Z"
    }
  ]
}
DELETE/api-keys/:id
Auth RequiredRevoke API key

Permanently revokes an API key. Any requests using this key will fail immediately.

Response
{
  "success": true,
  "message": "API key deleted successfully"
}

Invoices

Invoices are generated automatically when a withdrawal completes. Each invoice includes a fee breakdown and is stored as a PDF. All endpoints require JWT authentication.

GET/invoices
Auth RequiredList merchant invoices

Returns all invoices for the authenticated merchant, sorted by date (newest first).

Query Parameters

yearnumberOptional

Filter by year (e.g. 2026)

statusstringOptional

"issued" or "rectified"

Example Request
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.fivo.finance/invoices?year=2026"
Response
{
  "success": true,
  "data": [
    {
      "id": "invoice-uuid",
      "invoice_number": "FIV-2026-0001",
      "issued_at": "2026-02-25T14:30:00.000Z",
      "gross_amount": "1000.000000",
      "fivo_fee": "5.0000",
      "fivo_fee_eur": "4.6500",
      "tax_amount": "0.0000",
      "net_amount": "994.500000",
      "currency": "USDC",
      "status": "issued",
      "pdf_url": "invoices/2026/merchant-id/FIV-2026-0001.pdf",
      "blockchain": "BASE"
    }
  ]
}
GET/invoices/:id/pdf
Auth RequiredDownload invoice PDF

Returns the invoice PDF file directly. Use mode=view to display inline or mode=download to trigger a save dialog.

Path Parameters

idstringRequired

Invoice UUID

i

Direct PDF response

This endpoint streams the PDF file directly with Content-Type: application/pdf. No redirect or temporary URL is involved.

Webhook Management (API Key)

Manage your webhook endpoints programmatically via API Key. These endpoints mirror the dashboard webhook configuration.

i
All webhook management endpoints require API Key authentication via header.X-API-Key
GET/merchant-webhooks/api/list
Auth RequiredList all webhooks

Returns all webhook endpoints configured for your merchant account.

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/merchant-webhooks/api/list"
Response
{
  "success": true,
  "data": [
    {
      "id": "webhook-uuid",
      "url": "https://yoursite.com/webhooks/fivo",
      "events": ["payment.completed", "payment.failed"],
      "description": "Production webhook",
      "is_active": true,
      "failure_count": 0,
      "created_at": "2026-02-20T10:00:00.000Z"
    }
  ]
}
POST/merchant-webhooks/api/create
Auth RequiredCreate a webhook

Request Body

urlstringRequired

HTTPS webhook URL

eventsstring[]Required

Events to subscribe to (see available events below)

descriptionstringOptional

Description (max 200 chars)

Example Request
curl -X POST https://api.fivo.finance/merchant-webhooks/api/create \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/fivo",
    "events": ["payment.completed", "payment.failed"],
    "description": "Production webhook"
  }'
GET/merchant-webhooks/api/:id
Auth RequiredGet webhook details

Path Parameters

idstringRequired

Webhook UUID

PUT/merchant-webhooks/api/:id
Auth RequiredUpdate a webhook

Request Body

urlstringOptional

New webhook URL

eventsstring[]Optional

New events list

descriptionstringOptional

New description

is_activebooleanOptional

Enable/disable the webhook

DELETE/merchant-webhooks/api/:id
Auth RequiredDelete a webhook

Path Parameters

idstringRequired

Webhook UUID

POST/merchant-webhooks/api/:id/regenerate-secret
Auth RequiredRegenerate webhook secret

Generates a new HMAC secret for signature verification. The old secret stops working immediately.

POST/merchant-webhooks/api/:id/test
Auth RequiredSend test webhook

Sends a test event to the webhook URL. Useful for verifying your endpoint.payment.completed

GET/merchant-webhooks/api/:id/logs
Auth RequiredGet webhook delivery logs

Query Parameters

limitnumberOptional

Number of logs to return (default: 20, max: 100)

GET/merchant-webhooks/api/events
Auth RequiredList available events

Returns all webhook events you can subscribe to, with descriptions.

Balance (API Key)

GET/wallets/api/balance
Auth RequiredGet wallet balance

Returns the USDC and EURC balance of your primary wallet. Useful for monitoring available funds before triggering withdrawals.

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/wallets/api/balance"
Response
{
  "success": true,
  "data": {
    "wallet_id": "wallet-uuid",
    "address": "0x1234567890abcdef...",
    "blockchain": "MATIC",
    "balances": [
      { "token": "USDC", "amount": "1250.50" },
      { "token": "EURC", "amount": "340.00" }
    ]
  }
}
i

No cache

This endpoint always returns fresh data. Response includes headers.Cache-Control: no-store

Invoices (API Key)

Access your invoices programmatically via API Key. Invoices are generated automatically when a withdrawal completes.

GET/invoices/api/list
Auth RequiredList invoices

Query Parameters

yearnumberOptional

Filter by year (e.g. 2026)

statusstringOptional

"issued" or "rectified"

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/invoices/api/list?year=2026"
GET/invoices/api/:id/pdf
Auth RequiredDownload invoice PDF

Path Parameters

idstringRequired

Invoice UUID

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/invoices/api/INVOICE_UUID/pdf?mode=download"
i

Direct PDF response

Returns the PDF file directly with Content-Type: application/pdf.

Refunds (API Key)

Issue refunds for completed payments. Refunds are sent on-chain to the original sender address. All endpoints require API Key authentication via header.X-API-Key

POST/refunds/api/create
Auth RequiredCreate a refund

Creates a refund for a completed payment. By default, refunds the full payment amount. Partial refunds are supported by specifying an .amount

Request Body

paymentIdstringRequired

UUID of the payment to refund

amountstringOptional

Amount to refund (defaults to full payment amount)

reasonstringRequired

"duplicate", "fraudulent", "requested_by_customer", or "other"

notestringOptional

Internal note about the refund (max 500 chars)

Example Request
curl -X POST https://api.fivo.finance/refunds/api/create \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "payment-uuid-here",
    "amount": "49.99",
    "reason": "requested_by_customer",
    "note": "Customer requested refund"
  }'
Response (201)
{
  "success": true,
  "data": {
    "id": "refund-uuid",
    "payment_id": "payment-uuid-here",
    "amount": "49.990000",
    "currency": "USDC",
    "status": "pending",
    "destination_address": "0xCustomer...",
    "blockchain": "BASE",
    "reason": "requested_by_customer"
  }
}
i

Refund window

Refunds can be issued up to 180 days after the original payment was completed.
GET/refunds/api/list
Auth RequiredList refunds

Returns a paginated list of refunds for the authenticated merchant.

Query Parameters

statusstringOptional

Filter: "pending", "processing", "completed", "failed", "cancelled"

currencystringOptional

Filter: "USDC" or "EURC"

searchstringOptional

Search in payment ID, destination address, tx hash

limitnumberOptional

Results per page (default: 50, max: 200)

offsetnumberOptional

Pagination offset (default: 0)

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/refunds/api/list?status=completed&limit=10"
Response
{
  "success": true,
  "data": {
    "refunds": [
      {
        "id": "refund-uuid",
        "payment_id": "payment-uuid",
        "amount": "49.990000",
        "currency": "USDC",
        "status": "completed",
        "destination_address": "0xCustomer...",
        "blockchain": "BASE",
        "reason": "requested_by_customer",
        "tx_hash": "0xabc123...",
        "created_at": "2026-03-01T10:30:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}
GET/refunds/api/:id
Auth RequiredGet refund details

Returns full details of a specific refund, including the linked payment data.

Path Parameters

idstringRequired

Refund UUID

Example Request
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.fivo.finance/refunds/api/REFUND_UUID"
Response
{
  "success": true,
  "data": {
    "id": "refund-uuid",
    "payment_id": "payment-uuid",
    "amount": "49.990000",
    "currency": "USDC",
    "status": "completed",
    "destination_address": "0xCustomer...",
    "blockchain": "BASE",
    "reason": "requested_by_customer",
    "note": "Customer requested refund",
    "tx_hash": "0xabc123...",
    "failure_reason": null,
    "created_at": "2026-03-01T10:30:00.000Z",
    "completed_at": "2026-03-01T10:31:00.000Z",
    "payment": {
      "id": "payment-uuid",
      "amount": "49.990000",
      "currency": "USDC",
      "status": "completed",
      "tx_hash": "0xoriginal...",
      "from_address": "0xCustomer...",
      "created_at": "2026-02-28T10:30:00.000Z"
    }
  }
}
POST/refunds/api/:id/cancel
Auth RequiredCancel a pending refund

Cancels a refund that is still in status. Refunds that are already processing or completed cannot be cancelled.pending

Path Parameters

idstringRequired

Refund UUID

Example Request
curl -X POST https://api.fivo.finance/refunds/api/REFUND_UUID/cancel \
  -H "X-API-Key: YOUR_API_KEY"
Response
{
  "success": true
}

Webhooks

Webhooks notify your server in real-time when payment events occur. Configure webhooks in your or via the .dashboardWebhook Management API

Events

EventDescription
payment.completedPayment successful and funds received by merchant
payment.failedPayment failed
refund.createdA refund has been created for a payment
refund.completedRefund completed on-chain and sent to customer
refund.failedRefund failed (check failure_reason)

Payload

Webhook Payload
{
  "event": "payment.completed",
  "timestamp": "2026-02-18T10:30:45.123Z",
  "data": {
    "payment_id": "abc123-uuid",
    "amount": "49.99",
    "currency": "USDC",
    "tx_hash": "0x1234567890abcdef...",
    "from_address": "0xCustomerWallet...",
    "to_address": "0xMerchantWallet...",
    "source_chain": "ETH",
    "destination_chain": null,
    "is_cross_chain": false,
    "status": "completed"
  }
}

Headers

HeaderDescription
X-Fivo-SignatureHMAC-SHA256 signature ()sha256=hex
X-Fivo-EventEvent type (e.g. )payment.completed
X-Fivo-TimestampUnix timestamp (seconds) when webhook was sent
X-Fivo-Test or , whether this is a test webhooktruefalse

Verifying Signatures

Always verify the header to ensure the webhook came from Fivo.X-Fivo-Signature

Signature Verification (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const signaturePayload = timestamp + '.' + JSON.stringify(payload);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-fivo-signature'];
  const timestamp = req.headers['x-fivo-timestamp'];

  if (!verifyWebhookSignature(req.body, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { event, data } = req.body;
  console.log(event, data.payment_id, data.amount);
  res.status(200).send('OK');
});
!

Webhook Reliability

Your endpoint must respond with a 2xx status within 5 seconds. After 10 consecutive failures, the webhook is automatically deactivated. HTTPS is required in production.

Response Format

All API responses follow a consistent format:

Success Response
{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}
Error Response
{
  "success": false,
  "error": "Error description",
  "details": [ ... ]
}

Need help?

Check out our error handling guide or contact support.

Error CodesTesting Guide