Docs/Integración API

Integración API

Cree flujos de pago personalizados e integraciones backend.

Descripción general

Aunque el widget es la forma más sencilla de aceptar pagos, la API de Fivo le otorga control total para integraciones personalizadas. Use la API para:

Crear experiencias de pago personalizadas
Consultar el historial de pagos de forma programática
Integrar con sus sistemas backend existentes
Crear pagos desde código del lado del servidor

Sesiones de Pago

Las Sesiones de Pago son la forma recomendada de aceptar pagos desde una integración del lado del servidor. Su servidor crea una sesión, redirige al cliente a una página de pago alojada por Fivo y verifica el pago cuando el cliente regresa.

Cuándo usar cada método

Widget embebido

Productos fijos, donaciones, sitios estáticos

Backend: No

Widget + data-amount-from

Carritos de compra, totales dinámicos

Backend: No

Enlace directo

Correos electrónicos, redes sociales, códigos QR

Backend: No

Sesiones de Pago

E-commerce, SaaS, gestión de pedidos

Backend: Sí (API key)

Método	Ideal para	¿Requiere backend?
Widget embebido	Productos fijos, donaciones, sitios estáticos	No
Widget + `data-amount-from`	Carritos de compra, totales dinámicos	No
Enlace directo	Correos electrónicos, redes sociales, códigos QR	No
Sesiones de Pago	E-commerce, SaaS, gestión de pedidos	Sí (API key)

Ejemplo completo (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);

Ejemplo con cURL

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

Referencia completa

Consulte la para todos los parámetros, esquemas de respuesta y valores de estado de sesión.Referencia API

URL base

https://api.fivo.finance

API de Producción

Este es el endpoint de la API de producción. Todas las solicitudes se procesan en mainnet. Notificaremos a todos los comerciantes antes de cualquier cambio importante.

Autenticación

La API de Fivo utiliza dos métodos de autenticación:

Tokens JWT

Para sesiones del panel y de usuario. Se obtienen tras iniciar sesión. Expiran a los 15 minutos.

Authorization: Bearer <token>

API Keys

Para integraciones servidor a servidor. Se crean en el panel. No expiran, pero se pueden revocar.

X-API-Key: <api_key>

Crear una API Key

Inicie sesión en su Panel de Fivo
Navegue a API Keys
Haga clic en Crear nueva clave
Asigne un nombre descriptivo a su clave (por ejemplo, "Servidor de producción")
Copie la clave inmediatamente: ¡no se mostrará de nuevo!

Mantenga sus claves en secreto

Nunca exponga las API keys en código del lado del cliente. Las API keys solo deben usarse en aplicaciones del lado del servidor donde puedan mantenerse en secreto.

Ejemplo: Comprobar estado del pago

Después de que un cliente pague a través del widget, puede comprobar el estado del pago:

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

Ejemplo: Listar sus pagos

Consulte su historial de pagos con filtros. Requiere autenticación.

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

Ejemplos con cURL

Para pruebas rápidas, puede usar cURL desde la línea de comandos:

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 y librerías

Los SDKs oficiales estarán disponibles próximamente. Mientras tanto, puede usar librerías HTTP estándar en cualquier lenguaje para interactuar con la API.

Node.js SDK

Próximamente

Python SDK

Próximamente

PHP SDK

Próximamente

Límites de frecuencia

La API tiene límites de frecuencia para garantizar un uso justo y la estabilidad del sistema:

Endpoints de API Key

200 solicitudes por minuto

Per: API Key

API general

100 solicitudes por minuto

Per: IP

Creación de pago (widget)

20 solicitudes por minuto

Per: IP

Inicio de sesión

5 solicitudes por 5 minutos

Per: IP + email

Registro

3 solicitudes por 15 minutos

Per: IP

Restablecimiento de contraseña

3 solicitudes por 15 minutos

Per: IP + email

Verificación 2FA

5 solicitudes por 5 minutos

Per: IP

Retiros

10 solicitudes por 10 minutos

Per: IP

Formulario de contacto

3 solicitudes por 15 minutos

Per: IP

Endpoint	Límite	Ventana	Por
Endpoints de API Key	200 solicitudes	por minuto	API Key
API general	100 solicitudes	por minuto	IP
Creación de pago (widget)	20 solicitudes	por minuto	IP
Inicio de sesión	5 solicitudes	por 5 minutos	IP + email
Registro	3 solicitudes	por 15 minutos	IP
Restablecimiento de contraseña	3 solicitudes	por 15 minutos	IP + email
Verificación 2FA	5 solicitudes	por 5 minutos	IP
Retiros	10 solicitudes	por 10 minutos	IP
Formulario de contacto	3 solicitudes	por 15 minutos	IP

Cuando supere un límite de frecuencia, recibirá una respuesta con un encabezado que indica cuándo puede reintentar.429 Too Many RequestsRetry-After

Referencia API completa

Consulte la lista completa de endpoints, parámetros y formatos de respuesta.

Ver referencia API