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.
<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>Merchant ID
fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxModos 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.
<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
<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
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-idstringRequiredSu Merchant ID (formato: fivo_live_UUID)
amountstringOptionalMonto de pago fijo (0.01 - 1.000.000). Omítalo para modo variable.
currencystringOptional"USDC" o "EURC". Por defecto "USDC".
wallet-idstringOptionalUUID de wallet específico para comerciantes con múltiples wallets. Omítalo para usar su wallet predeterminado.
data-amount-fromstringOptionalSelector CSS del elemento que contiene el total del carrito. El monto se lee al hacer clic.
data-referencestringOptionalSu referencia interna (ID de pedido, número de factura, etc.). Máximo 255 caracteres.
data-descriptionstringOptionalDescripción del pago mostrada en el panel. Máximo 500 caracteres.
data-metadatastringOptionalCadena JSON con pares clave-valor personalizados. Máximo 10KB.
| Name | Type | Required | Description |
|---|---|---|---|
merchant-id | string | Required | Su Merchant ID (formato: fivo_live_UUID) |
amount | string | Optional | Monto de pago fijo (0.01 - 1.000.000). Omítalo para modo variable. |
currency | string | Optional | "USDC" o "EURC". Por defecto "USDC". |
wallet-id | string | Optional | UUID de wallet específico para comerciantes con múltiples wallets. Omítalo para usar su wallet predeterminado. |
data-amount-from | string | Optional | Selector CSS del elemento que contiene el total del carrito. El monto se lee al hacer clic. |
data-reference | string | Optional | Su referencia interna (ID de pedido, número de factura, etc.). Máximo 255 caracteres. |
data-description | string | Optional | Descripción del pago mostrada en el panel. Máximo 500 caracteres. |
data-metadata | string | Optional | Cadena JSON con pares clave-valor personalizados. Máximo 10KB. |
Atributos dinámicos
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-successData: txHash, amount, token, chainId
Pago confirmado en blockchain
fivo:payment-errorData: error
Pago fallido o rechazado
fivo:payment-trackingData: paymentId, status, step
Actualización del progreso de transferencia entre cadenas
| Evento | Datos | Cuándo |
|---|---|---|
fivo:payment-success | txHash, amount, token, chainId | Pago confirmado en blockchain |
fivo:payment-error | error | Pago fallido o rechazado |
fivo:payment-tracking | paymentId, status, step | Actualización del progreso de transferencia entre cadenas |
<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
<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>¿No detecta el total?
id="something"#somethingdata-amount-fromAvanzado: 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:
<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?
Múltiples productos
Cargue el script una vez y añada tantos botones como necesite. Cada uno funciona de forma independiente.
<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.
https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=49.99¤cy=USDCParámetros de URL
merchantstringRequiredSu Merchant ID
amountstringOptionalMonto fijo. Omítalo para modo variable.
currencystringOptional"USDC" o "EURC". Por defecto "USDC".
walletIdstringOptionalUUID de wallet específico para comerciantes con múltiples wallets.
referencestringOptionalSu referencia interna (ID de pedido, etc.).
descriptionstringOptionalDescripción del pago.
metadatastringOptionalCadena JSON codificada en URL con datos personalizados.
| Name | Type | Required | Description |
|---|---|---|---|
merchant | string | Required | Su Merchant ID |
amount | string | Optional | Monto fijo. Omítalo para modo variable. |
currency | string | Optional | "USDC" o "EURC". Por defecto "USDC". |
walletId | string | Optional | UUID de wallet específico para comerciantes con múltiples wallets. |
reference | string | Optional | Su referencia interna (ID de pedido, etc.). |
description | string | Optional | Descripción del pago. |
metadata | string | Optional | Cadena JSON codificada en URL con datos personalizados. |
<a href="https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=150.00¤cy=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.
Integración del lado del servidor
Cómo funciona
Su servidor crea una sesión
Llame a POST /checkout/sessions con el monto, la moneda y una URL de retorno.
Redirige al cliente
Use la URL devuelta para redirigir a su cliente a la página de pago de Fivo.
El cliente paga
El cliente conecta su wallet y completa el pago en la página alojada.
El cliente regresa a su sitio
Después del pago, el cliente es redirigido a su return_url con el ID de sesión.
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)
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
// 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
// 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 | numberOptionalMonto del pago (0.01 - 1.000.000). Omítalo para monto variable.
currencystringOptional"USDC" o "EURC". Por defecto "USDC".
return_urlstringRequiredURL a la que redirigir al cliente después del pago. Debe ser HTTPS en producción.
cancel_urlstringOptionalURL a la que redirigir si el cliente cancela. Debe ser HTTPS en producción.
metadataobjectOptionalHasta 5 pares clave-valor para su referencia interna (por ejemplo, ID de pedido).
expires_innumberOptionalDuració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). Omítalo para monto variable. |
currency | string | Optional | "USDC" o "EURC". Por defecto "USDC". |
return_url | string | Required | URL a la que redirigir al cliente después del pago. Debe ser HTTPS en producción. |
cancel_url | string | Optional | URL a la que redirigir si el cliente cancela. Debe ser HTTPS en producción. |
metadata | object | Optional | Hasta 5 pares clave-valor para su referencia interna (por ejemplo, ID de pedido). |
expires_in | number | Optional | Duración de la sesión en segundos (60 - 86400). Por defecto 1800 (30 min). |
Monedas y cadenas soportadas
| Moneda | Código | Cadenas |
|---|---|---|
| USD Coin | USDC | Las 9 cadenas |
| Euro Coin | EURC | Ethereum, Avalanche, Base |
| Blockchain | Tokens |
|---|---|
| Ethereum | USDC, EURC |
| Polygon | USDC |
| Avalanche | USDC, EURC |
| Arbitrum | USDC |
| Base | USDC, EURC |
| Optimism | USDC |
| Linea | USDC |
| Unichain | USDC |
| Sonic | USDC |
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
El cliente hace clic en el botón
Se abre una ventana de pago superpuesta sobre su página. Su sitio permanece cargado debajo.
El cliente conecta su wallet
Compatible con MetaMask, Coinbase Wallet, WalletConnect y otros wallets populares.
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.
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.
<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-referencestringOptionalSu ID de pedido/factura. Visible en el panel y en webhooks. Máximo 255 caracteres.
data-descriptionstringOptionalDescripción del pago. Visible en el panel. Máximo 500 caracteres.
data-metadatastringOptionalCadena JSON con cualquier dato personalizado. Incluido en webhooks. Máximo 10KB.
| Name | Type | Required | Description |
|---|---|---|---|
data-reference | string | Optional | Su ID de pedido/factura. Visible en el panel y en webhooks. Máximo 255 caracteres. |
data-description | string | Optional | Descripción del pago. Visible en el panel. Máximo 500 caracteres. |
data-metadata | string | Optional | Cadena JSON con cualquier dato personalizado. Incluido en webhooks. Máximo 10KB. |
Estos son opcionales
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