Docs/Integración del Widget

Integración del Widget

La forma más rápida de aceptar pagos. Sin necesidad de backend.

Inicio rápido

Añada dos líneas a su HTML. El widget gestiona la conexión del wallet, selección de cadena, firma de transacciones y transferencias entre cadenas automáticamente.

Minimal Setup
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  amount="29.99"
  currency="USDC">
</fivo-button>
i

Merchant ID

Su Merchant ID se muestra en la página de de su panel.Integración Format: fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Modos de pago

Monto fijo

Para productos, facturas, suscripciones. Establezca el atributo y el cliente solo podrá pagar ese precio exacto.amount

Monto variable

Para donaciones, propinas, pague lo que quiera. Omita el atributo y el cliente introduce cuánto desea pagar.amount

Monto fijo

Establezca el precio y el sistema verifica el monto exacto en blockchain. Los montos deben estar entre 0.01 y 1.000.000.

Product Checkout
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Product: $49.99 USDC -->
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  amount="49.99"
  currency="USDC">
</fivo-button>

Casos de uso

  • Pago de productos de e-commerce
  • Pagos de suscripciones SaaS
  • Facturas de servicios
  • Entradas para eventos

Monto variable

Omita el atributo . El widget muestra un campo de entrada donde el cliente escribe cuánto desea pagar.amount

Donation / Tip
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Donation: customer chooses amount -->
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  currency="USDC">
</fivo-button>
!

Límites de monto

Los montos variables se validan entre 0.01 y 1.000.000. Los montos fuera de este rango mostrarán un mensaje de error.

Casos de uso

  • Donaciones y recaudación de fondos
  • Propinas para creadores de contenido
  • Precios de pague lo que quiera
  • Contribuciones de crowdfunding

Atributos

El elemento acepta los siguientes atributos:<fivo-button>

fivo-button Attributes

merchant-idstringRequired

Su Merchant ID (formato: fivo_live_UUID)

amountstringOptional

Monto de pago fijo (0.01 - 1.000.000). Omítalo para modo variable.

currencystringOptional

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

wallet-idstringOptional

UUID de wallet específico para comerciantes con múltiples wallets. Omítalo para usar su wallet predeterminado.

data-amount-fromstringOptional

Selector CSS del elemento que contiene el total del carrito. El monto se lee al hacer clic.

data-referencestringOptional

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

data-descriptionstringOptional

Descripción del pago mostrada en el panel. Máximo 500 caracteres.

data-metadatastringOptional

Cadena JSON con pares clave-valor personalizados. Máximo 10KB.

i

Atributos dinámicos

Los atributos son reactivos. Puede actualizarlos con JavaScript (por ejemplo, ) y la etiqueta del botón se actualiza automáticamente.el.setAttribute('amount', '59.99')

Eventos

El botón emite eventos DOM personalizados que puede escuchar. Todos los datos del evento están disponibles en .e.detail

fivo:payment-success

Data: txHash, amount, token, chainId

Pago confirmado en blockchain

fivo:payment-error

Data: error

Pago fallido o rechazado

fivo:payment-tracking

Data: paymentId, status, step

Actualización del progreso de transferencia entre cadenas

Listening for Events
<fivo-button
  id="pay-btn"
  merchant-id="YOUR_MERCHANT_ID"
  amount="25.00"
  currency="USDC">
</fivo-button>

<script>
  const btn = document.getElementById('pay-btn');

  btn.addEventListener('fivo:payment-success', (e) => {
    console.log('TX hash:', e.detail.txHash);
    console.log('Amount:', e.detail.amount, e.detail.token);
    console.log('Chain ID:', e.detail.chainId);
    window.location.href = '/thank-you?tx=' + e.detail.txHash;
  });

  btn.addEventListener('fivo:payment-error', (e) => {
    console.error('Payment failed:', e.detail.error);
  });

  btn.addEventListener('fivo:payment-tracking', (e) => {
    // Only fires for cross-chain (CCTP) payments
    console.log('Step:', e.detail.step, 'Status:', e.detail.status);
  });
</script>

Carrito dinámico

Pegue este botón dentro de su carrito. Lee automáticamente el total de su página cuando el cliente hace clic. Si no detecta el total, cambie para que coincida con el ID del elemento del total de su carrito.#cartTotal

Cart Integration (Recommended)
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Replace #cartTotal with YOUR cart total element's ID -->
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  data-amount-from="#cartTotal"
  currency="USDC">
</fivo-button>
i

¿No detecta el total?

Haga clic derecho en el total del carrito, seleccione Inspeccionar. El código resaltado mostrará . Use en . Los signos de dólar y las comas se eliminan automáticamente.id="something"#somethingdata-amount-from

Avanzado: control manual

Si necesita control programático completo (por ejemplo, el total no es visible en la página), puede actualizar el atributo de monto directamente con JavaScript:

Manual setAttribute
<fivo-button
  id="checkout-btn"
  merchant-id="YOUR_MERCHANT_ID"
  currency="USDC">
</fivo-button>

<script>
  // Update when cart changes
  function updateCheckout(total) {
    document.getElementById('checkout-btn')
      .setAttribute('amount', total.toFixed(2));
  }

  // Redirect after payment
  document.getElementById('checkout-btn')
    .addEventListener('fivo:payment-success', (e) => {
      window.location.href = '/thank-you?tx=' + e.detail.txHash;
    });
</script>
!

¿E-commerce con gestión de pedidos?

Para tiendas que necesitan seguimiento de pedidos del lado del servidor, consulte a continuación.Sesiones de Pago

Múltiples productos

Cargue el script una vez y añada tantos botones como necesite. Cada uno funciona de forma independiente.

Multiple Buttons
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Product A -->
<fivo-button merchant-id="YOUR_MERCHANT_ID" amount="19.99" currency="USDC"></fivo-button>

<!-- Product B -->
<fivo-button merchant-id="YOUR_MERCHANT_ID" amount="49.99" currency="USDC"></fivo-button>

<!-- Donation (variable) -->
<fivo-button merchant-id="YOUR_MERCHANT_ID" currency="EURC"></fivo-button>

Enlace de pago directo

También puede enlazar directamente a la página de pago sin embeber el widget. Útil para facturas por correo electrónico, enlaces en redes sociales o códigos QR.

Checkout URL Format
https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=49.99&currency=USDC

Parámetros de URL

merchantstringRequired

Su Merchant ID

amountstringOptional

Monto fijo. Omítalo para modo variable.

currencystringOptional

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

walletIdstringOptional

UUID de wallet específico para comerciantes con múltiples wallets.

referencestringOptional

Su referencia interna (ID de pedido, etc.).

descriptionstringOptional

Descripción del pago.

metadatastringOptional

Cadena JSON codificada en URL con datos personalizados.

Example: Invoice Link
<a href="https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=150.00&currency=USDC">
  Pay Invoice #1234, $150.00 USDC
</a>

Sesiones de Pago (modo redirección)

Para integraciones del lado del servidor, puede crear una sesión de pago a través de la API y redirigir a su cliente a una página de pago alojada por Fivo. Después del pago, el cliente es redirigido de vuelta a su sitio. Esto es similar a Stripe Checkout.

i

Integración del lado del servidor

Las Sesiones de Pago requieren una API key. Cree una en su . Nunca exponga su API key en código del lado del cliente.panel de control

Cómo funciona

1

Su servidor crea una sesión

Llame a POST /checkout/sessions con el monto, la moneda y una URL de retorno.

2

Redirige al cliente

Use la URL devuelta para redirigir a su cliente a la página de pago de Fivo.

3

El cliente paga

El cliente conecta su wallet y completa el pago en la página alojada.

4

El cliente regresa a su sitio

Después del pago, el cliente es redirigido a su return_url con el ID de sesión.

5

Verifique el pago en su servidor

Llame a GET /checkout/sessions/:id para confirmar el estado del pago antes de completar el pedido.

1. Crear una sesión (lado del servidor)

Create Checkout Session
const response = await fetch(`https://api.fivo.finance/checkout/sessions`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.FIVO_API_KEY,
  },
  body: JSON.stringify({
    amount: '49.99',
    currency: 'USDC',
    return_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
    metadata: { order_id: 'order_123' },
    expires_in: 1800,   // 30 minutes (default)
  }),
});

const { data } = await response.json();
// data.id  → "cs_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
// data.url → "https://checkout.fivo.finance?session=cs_live_..."
// data.expires_at → "2026-02-18T11:00:00.000Z"
// After payment, the customer is redirected to:
// https://yoursite.com/success?session_id=cs_live_...

2. Redirigir al cliente

Redirect
// Express.js example
app.post('/create-checkout', async (req, res) => {
  const session = await createCheckoutSession(req.body);
  res.redirect(303, session.url);
});

3. Verificar el pago al regresar

Verify Session
// When the customer lands on your return_url
app.get('/success', async (req, res) => {
  const sessionId = req.query.session_id;

  const response = await fetch(
    `https://api.fivo.finance/checkout/sessions/${sessionId}`,
    { headers: { 'X-API-Key': process.env.FIVO_API_KEY } }
  );
  const { data } = await response.json();

  if (data.status === 'complete' && data.payment) {
    // Payment confirmed: fulfill the order
    console.log('Payment ID:', data.payment.id);
    console.log('TX Hash:', data.payment.tx_hash);
    console.log('Amount:', data.payment.amount, data.currency);
  } else {
    // Payment not yet confirmed: show a waiting state
    console.log('Session status:', data.status);
  }
});

POST /checkout/sessions: Parámetros

amountstring | numberOptional

Monto del pago (0.01 - 1.000.000). Omítalo para monto variable.

currencystringOptional

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

return_urlstringRequired

URL a la que redirigir al cliente después del pago. Debe ser HTTPS en producción.

cancel_urlstringOptional

URL a la que redirigir si el cliente cancela. Debe ser HTTPS en producción.

metadataobjectOptional

Hasta 5 pares clave-valor para su referencia interna (por ejemplo, ID de pedido).

expires_innumberOptional

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

Monedas y cadenas soportadas

MonedaCódigoCadenas
USD CoinUSDCLas 9 cadenas
Euro CoinEURCEthereum, Avalanche, Base
BlockchainTokens
EthereumUSDC, EURC
PolygonUSDC
AvalancheUSDC, EURC
ArbitrumUSDC
BaseUSDC, EURC
OptimismUSDC
LineaUSDC
UnichainUSDC
SonicUSDC

Los clientes pueden pagar desde cualquier cadena. Si su cadena difiere de la cadena de su wallet, los pagos en USDC se transfieren automáticamente a través de Circle CCTP (normalmente 1-2 minutos). EURC es solo en la misma cadena y no admite transferencias entre cadenas.

Cómo funciona

1

El cliente hace clic en el botón

Se abre una ventana de pago superpuesta sobre su página. Su sitio permanece cargado debajo.

2

El cliente conecta su wallet

Compatible con MetaMask, Coinbase Wallet, WalletConnect y otros wallets populares.

3

El cliente selecciona cadena y paga

El widget escanea las cadenas soportadas en busca de saldos de USDC (9 cadenas) o EURC (3 cadenas) y muestra las opciones disponibles.

4

Usted recibe los fondos

Los pagos en la misma cadena son instantáneos. Los pagos en USDC entre cadenas llegan en 1-2 minutos a través de CCTP. EURC es solo en la misma cadena.

Email del cliente y recibos

Cada pago requiere que el cliente introduzca su dirección de email antes de pagar. El widget gestiona esto automáticamente. Se muestra un campo de email obligatorio antes del paso de conexión del wallet.

Para clientes

Después del pago, el cliente recibe un recibo por email con su ID de pago, monto, nombre del comerciante y enlace a la transacción en blockchain.

Para comerciantes

Puede ver los emails de los clientes en su página de Transacciones y buscar reembolsos por email en lugar de por ID de pago.

Seguimiento de pedidos

Use atributos opcionales para vincular pagos a sus sistemas internos. Estos se pasan a los webhooks y son visibles en su panel.

E-commerce Integration
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  amount="49.99"
  currency="USDC"
  data-reference="ORD-2024-001"
  data-description="Pro Plan - Monthly"
  data-metadata='{"product_id": "plan_pro", "customer_name": "John"}'>
</fivo-button>

Order Tracking Attributes

data-referencestringOptional

Su ID de pedido/factura. Visible en el panel y en webhooks. Máximo 255 caracteres.

data-descriptionstringOptional

Descripción del pago. Visible en el panel. Máximo 500 caracteres.

data-metadatastringOptional

Cadena JSON con cualquier dato personalizado. Incluido en webhooks. Máximo 10KB.

i

Estos son opcionales

El email del cliente siempre es obligatorio (gestionado automáticamente por el widget). Referencia, descripción y metadatos son opcionales. Úselos cuando necesite vincular pagos a su sistema de pedidos.

Información útil

Ligero

Script de ~7KB, carga asíncrona. No ralentizará su sitio.

Estilos aislados

Usa Shadow DOM. Su CSS no lo afectará.

Protección contra fraude

Los montos fijos se verifican en blockchain.

9 blockchains

USDC en las 9 cadenas con transferencia automática vía CCTP. EURC en 3 cadenas (solo misma cadena).

¿Necesita más control?

Use para flujos de redirección del lado del servidor, o consulte la guía de integración API para webhooks y consultas de pagos programáticas.Sesiones de Pago