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...

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

Name	Type	Required	Description
`merchantId`	string	Required	UUID of the merchant receiving payment
`txHash`	string	Required	Blockchain transaction hash (0x...)
`amount`	number	Required	Payment amount (0.01 - 1,000,000)
`expectedAmount`	number	Optional	Expected amount for validation (anti-fraud)
`token`	string	Required	"USDC" or "EURC"
`chainId`	number	Required	Source blockchain chain ID
`fromAddress`	string	Required	Sender wallet address
`toAddress`	string	Required	Merchant wallet address
`isCrossChain`	boolean	Optional	Whether this is a CCTP cross-chain payment
`destinationChainId`	number	Optional	Destination chain (if cross-chain)
`cctpMessageHash`	string	Optional	CCTP message hash (if cross-chain)
`cctpNonce`	string	Optional	CCTP nonce (if cross-chain)

Example Request

const response = await fetch('https://api.fivo.finance/payments/create-public', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchantId: '969c4442-5741-4624-8305-427391683190',
    txHash: '0x1234567890abcdef...',
    amount: 49.99,
    expectedAmount: 49.99,
    token: 'USDC',
    chainId: 80002,
    fromAddress: '0xCustomerWallet...',
    toAddress: '0xMerchantWallet...',
    isCrossChain: false
  })
});

Response

{
  "success": true,
  "data": {
    "id": "payment-uuid-here",
    "merchant_id": "969c4442-5741-4624-8305-427391683190",
    "amount": 49.99,
    "currency": "USDC",
    "status": "completed",
    "tx_hash": "0x1234567890abcdef...",
    "source_chain": "MATIC-AMOY",
    "is_cross_chain": false,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

GET/payments/:id/status

Get payment status

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

Path Parameters

Name	Type	Required	Description
`id`	string	Required	Payment UUID

Response

{
  "success": true,
  "data": {
    "id": "payment-uuid-here",
    "status": "completed",
    "is_cross_chain": true,
    "cctp_attestation_status": "minted",
    "cctp_message_hash": "0xabc...",
    "tx_hash": "0x123...",
    "amount": 49.99,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

Payment Status Values

Status	Description
`completed`	Payment successful and funds received
`pending`	Cross-chain payment in progress (CCTP)
`failed`	Payment failed (check failure_reason)

GET/payments

Auth RequiredList merchant payments

Returns paginated list of payments for the authenticated merchant.

Query Parameters

Name	Type	Required	Description
`status`	string	Optional	Filter: "pending", "completed", "failed"
`currency`	string	Optional	Filter: "USDC" or "EURC"
`startDate`	string	Optional	Filter: ISO date string
`endDate`	string	Optional	Filter: ISO date string
`search`	string	Optional	Search in tx_hash, from_address (min 3 chars)
`limit`	number	Optional	Results per page (default: 50)
`offset`	number	Optional	Pagination offset (default: 0)
`sortBy`	string	Optional	Sort field (e.g., "created_at", "amount")
`sortDirection`	string	Optional	"asc" or "desc"

Example Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "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.

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-AMOY",
      "chainId": 80002
    }
  }
}

GET/merchants/:id/info

Get merchant public info

Returns public merchant information like name and accepted currencies.

Response

{
  "success": true,
  "data": {
    "id": "merchant-uuid",
    "name": "My Store",
    "blockchain": "MATIC-AMOY",
    "accepted_currencies": ["USDC", "EURC"]
  }
}

API Keys

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

Name	Type	Required	Description
`name`	string	Required	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",
      "key_preview": "...c123",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "key-uuid-2",
      "name": "Staging Server",
      "key_preview": "...f456",
      "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"
}

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 Codes Testing Guide