Docs/Referencia de API

Referencia de API

Referencia completa de todos los endpoints de la API de Fivo.

URL base

https://api.fivo.finance

Autenticación

Los endpoints protegidos requieren autenticación mediante API Key o token JWT.

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

Idempotencia

La API de Fivo incluye protecciones de idempotencia integradas para prevenir operaciones duplicadas:

Pagos

El de cada pago es único. Si envía un pago con un que ya existe, la API devuelve con los datos del pago existente en lugar de crear un duplicado.txHashtxHash200

Sesiones de pago

Cada sesión tiene un único. Una única sesión de pago solo puede producir un pago.payment_id

Notificaciones

Las entregas de webhooks y los correos electrónicos usan un sistema de idempotencia interno para prevenir notificaciones duplicadas del mismo evento.

Manejo de respuestas POST

Cuando un endpoint POST devuelve en lugar de , significa que el recurso ya existe. Su código debe manejar ambos códigos de estado como éxito.200201

Pagos

POST/payments/create-public

Crear pago desde el widget

Crea un registro de pago tras una transacción blockchain exitosa. Este endpoint es llamado automáticamente por el widget de Fivo.

Cuerpo de la solicitud

merchantIdstringRequired

Merchant ID con prefijo (fivo_live_UUID)

txHashstringRequired

Hash de transacción blockchain (0x...)

amountnumberRequired

Monto del pago (0.01 - 1.000.000)

expectedAmountnumberOptional

Monto esperado para validación on-chain. Requerido para pagos en la misma cadena, opcional para pagos entre cadenas.

tokenstringRequired

"USDC" o "EURC"

chainIdnumberRequired

Chain ID de la blockchain de origen

fromAddressstringRequired

Dirección de wallet del remitente

toAddressstringRequired

Dirección de wallet del comerciante

isCrossChainbooleanOptional

Si se trata de un pago entre cadenas CCTP

bridgeKitobjectOptional

Payload de Bridge Kit para pagos entre cadenas: { burnTxHash: string, mintTxHash?: string }. Requerido para el flujo entre cadenas con Bridge Kit.

feeQuoteobjectOptional

Cotización de comisión firmada para CCTP entre cadenas legado (obsoleto). Use bridgeKit en su lugar.

destinationChainIdnumberOptional

Cadena de destino (si es entre cadenas)

sessionIdstringOptional

ID de sesión de pago para vincular este pago (si usa sesiones de pago)

customerEmailstringRequired

Dirección de correo electrónico del cliente para envío de recibo. Máx. 255 caracteres.

referencestringOptional

Su referencia interna (ID de pedido, número de factura). Máx. 255 caracteres.

descriptionstringOptional

Descripción del pago. Máx. 500 caracteres.

metadataobjectOptional

Pares clave-valor personalizados para su uso interno. Máx. 10KB.

Name	Type	Required	Description
`merchantId`	string	Required	Merchant ID con prefijo (fivo_live_UUID)
`txHash`	string	Required	Hash de transacción blockchain (0x...)
`amount`	number	Required	Monto del pago (0.01 - 1.000.000)
`expectedAmount`	number	Optional	Monto esperado para validación on-chain. Requerido para pagos en la misma cadena, opcional para pagos entre cadenas.
`token`	string	Required	"USDC" o "EURC"
`chainId`	number	Required	Chain ID de la blockchain de origen
`fromAddress`	string	Required	Dirección de wallet del remitente
`toAddress`	string	Required	Dirección de wallet del comerciante
`isCrossChain`	boolean	Optional	Si se trata de un pago entre cadenas CCTP
`bridgeKit`	object	Optional	Payload de Bridge Kit para pagos entre cadenas: { burnTxHash: string, mintTxHash?: string }. Requerido para el flujo entre cadenas con Bridge Kit.
`feeQuote`	object	Optional	Cotización de comisión firmada para CCTP entre cadenas legado (obsoleto). Use bridgeKit en su lugar.
`destinationChainId`	number	Optional	Cadena de destino (si es entre cadenas)
`sessionId`	string	Optional	ID de sesión de pago para vincular este pago (si usa sesiones de pago)
`customerEmail`	string	Required	Dirección de correo electrónico del cliente para envío de recibo. Máx. 255 caracteres.
`reference`	string	Optional	Su referencia interna (ID de pedido, número de factura). Máx. 255 caracteres.
`description`	string	Optional	Descripción del pago. Máx. 500 caracteres.
`metadata`	object	Optional	Pares clave-valor personalizados para su uso interno. Máx. 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
  }
}

Respuesta mínima

Este endpoint solo devuelve los campos necesarios para el widget. Para obtener los detalles completos del pago (monto, tx_hash, etc.), use con autenticación.GET /payments/:id

GET/payments/:id/status

Obtener estado del pago

Devuelve el estado actual de un pago. Útil para consultar la finalización del pago.

Parámetros de ruta

idstringRequired

UUID del pago

Name	Type	Required	Description
`id`	string	Required	UUID del pago

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"
  }
}

Endpoint público mínimo

Este es un endpoint público que solo devuelve campos de estado. Los datos sensibles como montos, tx_hash y direcciones no se incluyen. Use con autenticación para obtener detalles completos. Nota: es para pagos con Bridge Kit (sistema actual). Solo tiene valores para pagos legados con relayer CCTP.GET /payments/:idcctp_attestation_statusnull

Valores de estado del pago

Estado	Descripción
`completed`	Pago exitoso y fondos recibidos
`pending`	Pago creado, en espera de procesamiento
`pending_attestation`	Entre cadenas: esperando atestación CCTP de Circle
`ready_to_mint`	Entre cadenas: atestación recibida, realizando mint en la cadena de destino
`minted_pending_transfer`	Entre cadenas: mint realizado, transfiriendo a la wallet del comerciante
`failed`	Pago fallido (consulte failure_reason)

GET/payments

Auth RequiredListar pagos del comerciante

Devuelve una lista paginada de pagos para el comerciante autenticado.

Parámetros de consulta

statusstringOptional

Filtro: "pending", "completed", "failed"

currencystringOptional

Filtro: "USDC" o "EURC"

startDatestringOptional

Filtro: cadena de fecha ISO

endDatestringOptional

Filtro: cadena de fecha ISO

searchstringOptional

Buscar en tx_hash, from_address, customer_email, reference (mín. 3 caracteres)

limitnumberOptional

Resultados por página (por defecto: 50)

offsetnumberOptional

Desplazamiento de paginación (por defecto: 0)

sortBystringOptional

Campo de ordenación (ej., "created_at", "amount")

sortDirectionstringOptional

"asc" o "desc"

sincestringOptional

Fecha ISO: solo devuelve pagos creados después de esta fecha. Útil para consultas en tiempo real.

Name	Type	Required	Description
`status`	string	Optional	Filtro: "pending", "completed", "failed"
`currency`	string	Optional	Filtro: "USDC" o "EURC"
`startDate`	string	Optional	Filtro: cadena de fecha ISO
`endDate`	string	Optional	Filtro: cadena de fecha ISO
`search`	string	Optional	Buscar en tx_hash, from_address, customer_email, reference (mín. 3 caracteres)
`limit`	number	Optional	Resultados por página (por defecto: 50)
`offset`	number	Optional	Desplazamiento de paginación (por defecto: 0)
`sortBy`	string	Optional	Campo de ordenación (ej., "created_at", "amount")
`sortDirection`	string	Optional	"asc" o "desc"
`since`	string	Optional	Fecha ISO: solo devuelve pagos creados después de esta fecha. Útil para consultas en tiempo real.

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 RequiredObtener detalles del pago

Devuelve los detalles completos de un pago específico incluyendo todos los campos CCTP.

GET/payments/api/list

Auth RequiredListar pagos (API Key)

Devuelve una lista paginada de pagos para el comerciante autenticado mediante API Key. Útil para la conciliación del lado del servidor y la verificación de datos de webhooks.

Parámetros de consulta

statusstringOptional

Filtro: "pending", "completed", "failed"

currencystringOptional

Filtro: "USDC" o "EURC"

startDatestringOptional

Filtro: cadena de fecha ISO

endDatestringOptional

Filtro: cadena de fecha ISO

searchstringOptional

Buscar en tx_hash, from_address, customer_email, reference (mín. 3 caracteres)

limitnumberOptional

Resultados por página (por defecto: 50, máx.: 200)

offsetnumberOptional

Desplazamiento de paginación (por defecto: 0)

sortBystringOptional

Campo de ordenación (ej., "created_at", "amount")

sortDirectionstringOptional

"asc" o "desc"

sincestringOptional

Fecha ISO: solo devuelve pagos creados después de esta fecha

Name	Type	Required	Description
`status`	string	Optional	Filtro: "pending", "completed", "failed"
`currency`	string	Optional	Filtro: "USDC" o "EURC"
`startDate`	string	Optional	Filtro: cadena de fecha ISO
`endDate`	string	Optional	Filtro: cadena de fecha ISO
`search`	string	Optional	Buscar en tx_hash, from_address, customer_email, reference (mín. 3 caracteres)
`limit`	number	Optional	Resultados por página (por defecto: 50, máx.: 200)
`offset`	number	Optional	Desplazamiento de paginación (por defecto: 0)
`sortBy`	string	Optional	Campo de ordenación (ej., "created_at", "amount")
`sortDirection`	string	Optional	"asc" o "desc"
`since`	string	Optional	Fecha ISO: solo devuelve pagos creados después de esta fecha

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 RequiredObtener detalles del pago (API Key)

Devuelve los detalles completos de un pago específico. Use esto para verificar un pago después de recibir una notificación de webhook.

Parámetros de ruta

idstringRequired

UUID del pago

Name	Type	Required	Description
`id`	string	Required	UUID del pago

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"
  }
}

Flujo típico

1. Recibir webhook → 2. Verificar con → 3. Completar el pedido.payment.completedGET /payments/api/:id

GET/payments/cctp-fee

Estimar comisión entre cadenas

Devuelve una cotización de comisión firmada para un pago entre cadenas (CCTP). El widget llama a este endpoint automáticamente, pero puede usarlo para integraciones personalizadas para mostrar el desglose de comisiones antes de que el usuario pague.

Parámetros de consulta

destinationChainstringRequired

Nombre de la blockchain de destino (ej., "ETH", "BASE", "ARB")

productPricestringRequired

Precio del producto en USD (ej., "49.99")

Name	Type	Required	Description
`destinationChain`	string	Required	Nombre de la blockchain de destino (ej., "ETH", "BASE", "ARB")
`productPrice`	string	Required	Precio del producto en USD (ej., "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..."
  }
}

Cotización firmada

La respuesta incluye una firma HMAC. Al crear un pago entre cadenas mediante , pase los campos de la cotización como el parámetro . El backend verifica la firma para prevenir manipulación de comisiones.POST /payments/create-publicfeeQuote

Comerciantes

GET/merchants/:id/wallet

Obtener dirección de wallet del comerciante

Devuelve la dirección de wallet y la blockchain del comerciante. Usado por el widget para saber dónde enviar los pagos.

Response

{
  "success": true,
  "data": {
    "wallet": {
      "id": "wallet-uuid",
      "address": "0x1234567890abcdef...",
      "blockchain": "MATIC",
      "chainId": 137
    }
  }
}

GET/merchants/:id/info

Obtener información pública del comerciante

Devuelve información pública del comerciante como nombre y monedas aceptadas.

Response

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

Sesiones de pago

Las sesiones de pago le permiten crear una página de pago alojada por Fivo y redirigir a su cliente hacia ella. Después del pago, el cliente es redirigido de vuelta a su sitio. Similar a Stripe Checkout.

Todos los endpoints de sesiones de pago (excepto ) requieren autenticación mediante API Key./public

POST/checkout/sessions

Auth RequiredCrear sesión de pago

Crea una nueva sesión de pago y devuelve una URL para redirigir a su cliente.

Cuerpo de la solicitud

amountstring | numberOptional

Monto del pago (0.01 - 1.000.000). Omita para monto variable.

currencystringOptional

"USDC" o "EURC". Por defecto "USDC".

return_urlstringRequired

URL de redirección después del pago. Debe ser HTTPS en producción.

cancel_urlstringOptional

URL de redirección al cancelar. Debe ser HTTPS en producción.

metadataobjectOptional

Hasta 5 pares clave-valor para su referencia (ej. order_id).

expires_innumberOptional

Duración de la sesión en segundos (60 - 86400). Por defecto: 1800 (30 min).

Name	Type	Required	Description
`amount`	string \| number	Optional	Monto del pago (0.01 - 1.000.000). Omita para monto variable.
`currency`	string	Optional	"USDC" o "EURC". Por defecto "USDC".
`return_url`	string	Required	URL de redirección después del pago. Debe ser HTTPS en producción.
`cancel_url`	string	Optional	URL de redirección al cancelar. Debe ser HTTPS en producción.
`metadata`	object	Optional	Hasta 5 pares clave-valor para su referencia (ej. order_id).
`expires_in`	number	Optional	Duración de la sesión en segundos (60 - 86400). Por defecto: 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 RequiredObtener detalles de la sesión

Devuelve el estado de la sesión y los datos del pago vinculado. Use esto para verificar la finalización del pago después de que el cliente regrese a su sitio.

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"
  }
}

Valores de estado de la sesión

Estado	Descripción
`open`	Sesión creada, esperando a que el cliente pague
`complete`	Pago confirmado y fondos recibidos
`expired`	La sesión expiró antes de que se realizara el pago

GET/checkout/sessions/:id/public

Obtener sesión (solo widget)

Endpoint público usado por el widget de pago para cargar los detalles de la sesión. Solo devuelve los campos necesarios para renderizar la interfaz de pago (sin metadata). No necesita llamar a este endpoint directamente.

API Keys

Todos los endpoints de API Keys requieren autenticación JWT (sesión de comerciante iniciada). Las API Keys no pueden usarse para gestionar otras API Keys.

POST/api-keys

Auth RequiredCrear nueva API Key

Cuerpo de la solicitud

namestringRequired

Nombre descriptivo para la clave (1-50 caracteres)

Name	Type	Required	Description
`name`	string	Required	Nombre descriptivo para la clave (1-50 caracteres)

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"
  }
}

Guarde su clave

La API Key completa solo se muestra una vez en el momento de la creación. Guárdela de forma segura. Si la pierde, deberá crear una nueva clave.

GET/api-keys

Auth RequiredListar API Keys

Devuelve todas las API Keys del comerciante autenticado. Las claves están enmascaradas por seguridad (solo se muestran los últimos 4 caracteres).

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 RequiredRevocar API Key

Revoca permanentemente una API Key. Cualquier solicitud que use esta clave fallará inmediatamente.

Response

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

Facturas

Las facturas se generan automáticamente cuando se completa un retiro. Cada factura incluye un desglose de comisiones y se almacena como PDF. Todos los endpoints requieren autenticación JWT.

GET/invoices

Auth RequiredListar facturas del comercio

Devuelve todas las facturas del comercio autenticado, ordenadas por fecha (más recientes primero).

Parámetros de consulta

yearnumberOptional

Filtrar por año (ej. 2026)

statusstringOptional

"issued" o "rectified"

Name	Type	Required	Description
`year`	number	Optional	Filtrar por año (ej. 2026)
`status`	string	Optional	"issued" o "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 RequiredDescargar factura PDF

Devuelve el archivo PDF de la factura directamente. Usa mode=view para mostrar en el navegador o mode=download para descargar.

Parámetros de ruta

idstringRequired

UUID de la factura

Name	Type	Required	Description
`id`	string	Required	UUID de la factura

Respuesta PDF directa

Este endpoint devuelve el archivo PDF directamente con Content-Type: application/pdf. No hay redireccion ni URL temporal.

Gestión de Webhooks (API Key)

Gestione sus endpoints de webhook de forma programática mediante API Key. Estos endpoints replican la configuración de webhooks del dashboard.

Todos los endpoints de gestión de webhooks requieren autenticación mediante API Key a través del header .X-API-Key

GET/merchant-webhooks/api/list

Auth RequiredListar todos los webhooks

Devuelve todos los endpoints de webhook configurados para su cuenta de comercio.

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 RequiredCrear un webhook

Cuerpo de la solicitud

urlstringRequired

URL de webhook HTTPS

eventsstring[]Required

Eventos a los que suscribirse (ver eventos disponibles abajo)

descriptionstringOptional

Descripción (máx. 200 caracteres)

Name	Type	Required	Description
`url`	string	Required	URL de webhook HTTPS
`events`	string[]	Required	Eventos a los que suscribirse (ver eventos disponibles abajo)
`description`	string	Optional	Descripción (máx. 200 caracteres)

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 RequiredObtener detalles del webhook

Parámetros de ruta

idstringRequired

UUID del webhook

Name	Type	Required	Description
`id`	string	Required	UUID del webhook

PUT/merchant-webhooks/api/:id

Auth RequiredActualizar un webhook

Cuerpo de la solicitud

urlstringOptional

Nueva URL del webhook

eventsstring[]Optional

Nueva lista de eventos

descriptionstringOptional

Nueva descripción

is_activebooleanOptional

Activar/desactivar el webhook

Name	Type	Required	Description
`url`	string	Optional	Nueva URL del webhook
`events`	string[]	Optional	Nueva lista de eventos
`description`	string	Optional	Nueva descripción
`is_active`	boolean	Optional	Activar/desactivar el webhook

DELETE/merchant-webhooks/api/:id

Auth RequiredEliminar un webhook

Parámetros de ruta

idstringRequired

UUID del webhook

Name	Type	Required	Description
`id`	string	Required	UUID del webhook

POST/merchant-webhooks/api/:id/regenerate-secret

Auth RequiredRegenerar secreto del webhook

Genera un nuevo secreto HMAC para verificación de firmas. El secreto anterior deja de funcionar inmediatamente.

POST/merchant-webhooks/api/:id/test

Auth RequiredEnviar webhook de prueba

Envía un evento de prueba a la URL del webhook. Útil para verificar su endpoint.payment.completed

GET/merchant-webhooks/api/:id/logs

Auth RequiredObtener registros de entrega del webhook

Parámetros de consulta

limitnumberOptional

Número de registros a devolver (por defecto: 20, máx: 100)

Name	Type	Required	Description
`limit`	number	Optional	Número de registros a devolver (por defecto: 20, máx: 100)

GET/merchant-webhooks/api/events

Auth RequiredListar eventos disponibles

Devuelve todos los eventos de webhook a los que puede suscribirse, con descripciones.

Saldo (API Key)

GET/wallets/api/balance

Auth RequiredObtener saldo de la billetera

Devuelve el saldo de USDC y EURC de su billetera principal. Útil para monitorear fondos disponibles antes de iniciar retiros.

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" }
    ]
  }
}

Sin caché

Este endpoint siempre devuelve datos actualizados. La respuesta incluye headers .Cache-Control: no-store

Facturas (API Key)

Acceda a sus facturas de forma programática mediante API Key. Las facturas se generan automáticamente cuando se completa un retiro.

GET/invoices/api/list

Auth RequiredListar facturas

Parámetros de consulta

yearnumberOptional

Filtrar por año (ej. 2026)

statusstringOptional

"issued" o "rectified"

Name	Type	Required	Description
`year`	number	Optional	Filtrar por año (ej. 2026)
`status`	string	Optional	"issued" o "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 RequiredDescargar factura PDF

Parámetros de ruta

idstringRequired

UUID de la factura

Name	Type	Required	Description
`id`	string	Required	UUID de la factura

Example Request

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

Respuesta PDF directa

Devuelve el archivo PDF directamente con Content-Type: application/pdf.

Reembolsos (API Key)

Emita reembolsos para pagos completados. Los reembolsos se envían on-chain a la dirección del remitente original. Todos los endpoints requieren autenticación mediante API Key a través del header .X-API-Key

POST/refunds/api/create

Auth RequiredCrear un reembolso

Crea un reembolso para un pago completado. Por defecto, reembolsa el importe total del pago. Se admiten reembolsos parciales especificando un .amount

Cuerpo de la solicitud

paymentIdstringRequired

UUID del pago a reembolsar

amountstringOptional

Importe a reembolsar (por defecto, el importe total del pago)

reasonstringRequired

"duplicate", "fraudulent", "requested_by_customer" u "other"

notestringOptional

Nota interna sobre el reembolso (máx. 500 caracteres)

Name	Type	Required	Description
`paymentId`	string	Required	UUID del pago a reembolsar
`amount`	string	Optional	Importe a reembolsar (por defecto, el importe total del pago)
`reason`	string	Required	"duplicate", "fraudulent", "requested_by_customer" u "other"
`note`	string	Optional	Nota interna sobre el reembolso (máx. 500 caracteres)

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"
  }
}

Plazo de reembolso

Los reembolsos pueden emitirse hasta 180 días después de que se completó el pago original.

GET/refunds/api/list

Auth RequiredListar reembolsos

Devuelve una lista paginada de reembolsos para el comercio autenticado.

Parámetros de consulta

statusstringOptional

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

currencystringOptional

Filtro: "USDC" o "EURC"

searchstringOptional

Buscar en ID de pago, dirección de destino, hash de transacción

limitnumberOptional

Resultados por página (por defecto: 50, máx.: 200)

offsetnumberOptional

Desplazamiento de paginación (por defecto: 0)

Name	Type	Required	Description
`status`	string	Optional	Filtrar: "pending", "processing", "completed", "failed", "cancelled"
`currency`	string	Optional	Filtro: "USDC" o "EURC"
`search`	string	Optional	Buscar en ID de pago, dirección de destino, hash de transacción
`limit`	number	Optional	Resultados por página (por defecto: 50, máx.: 200)
`offset`	number	Optional	Desplazamiento de paginación (por defecto: 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 RequiredObtener detalles del reembolso

Devuelve los detalles completos de un reembolso específico, incluyendo los datos del pago vinculado.

Parámetros de ruta

idstringRequired

UUID del reembolso

Name	Type	Required	Description
`id`	string	Required	UUID del reembolso

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 RequiredCancelar un reembolso pendiente

Cancela un reembolso que aún está en estado . Los reembolsos que ya están en proceso o completados no pueden cancelarse.pending

Parámetros de ruta

idstringRequired

UUID del reembolso

Name	Type	Required	Description
`id`	string	Required	UUID del reembolso

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

Los webhooks notifican a su servidor en tiempo real cuando ocurren eventos de pago. Configure webhooks en su o a través de la .panel de control API de gestión de webhooks

Eventos

Evento	Descripción
`payment.completed`	Pago exitoso y fondos recibidos por el comercio
`payment.failed`	Pago fallido
`refund.created`	Se ha creado un reembolso para un pago
`refund.completed`	Reembolso completado on-chain y enviado al cliente
`refund.failed`	Reembolso fallido (verifique 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

Header	Descripción
`X-Fivo-Signature`	Firma HMAC-SHA256 ()`sha256=hex`
`X-Fivo-Event`	Tipo de evento (ej. )`payment.completed`
`X-Fivo-Timestamp`	Marca de tiempo Unix (segundos) de cuando se envió el webhook
`X-Fivo-Test`	o , si es un webhook de prueba`truefalse`

Verificación de firmas

Verifique siempre el header para asegurar que el webhook proviene de 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');
});

Fiabilidad de Webhooks

Su endpoint debe responder con un código 2xx en 5 segundos. Después de 10 fallos consecutivos, el webhook se desactiva automáticamente. Se requiere HTTPS en producción.

Formato de respuesta

Todas las respuestas de la API siguen un formato consistente:

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Error Response

{
  "success": false,
  "error": "Error description",
  "details": [ ... ]
}

¿Necesita ayuda?

Consulte nuestra guía de manejo de errores o contacte con soporte.

Códigos de error Guía de pruebas