Integração do Widget
A forma mais rápida de aceitar pagamentos. Sem backend necessário.
Início Rápido
Adicione duas linhas ao seu HTML. O widget trata da ligação à wallet, seleção de cadeia, assinatura de transação e bridging entre cadeias automaticamente.
<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 Pagamento
Montante Fixo
Para produtos, faturas, subscrições. Defina o atributo e o cliente só pode pagar esse preço exato.amount
Montante Variável
Para donativos, gorjetas, pague-o-que-quiser. Omita o atributo e o cliente introduz quanto quer pagar.amount
Montante Fixo
Defina o preço e o sistema verifica o montante exato na blockchain. Os montantes devem estar entre 0,01 e 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
- Pagamento de produtos e-commerce
- Pagamentos de subscrição SaaS
- Faturas de serviços
- Bilhetes para eventos
Montante Variável
Omita o atributo . O widget mostra um campo de entrada onde o cliente digita quanto quer 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>Limites de Montante
Casos de Uso
- Donativos e angariação de fundos
- Gorjetas para criadores de conteúdo
- Preço pague-o-que-quiser
- Contribuições para crowdfunding
Atributos
O elemento aceita os seguintes atributos:<fivo-button>
fivo-button Attributes
merchant-idstringRequiredO seu Merchant ID (formato: fivo_live_UUID)
amountstringOptionalMontante de pagamento fixo (0,01 - 1.000.000). Omita para modo variável.
currencystringOptional"USDC" ou "EURC". Predefinido: "USDC".
wallet-idstringOptionalUUID de wallet específica para comerciantes com múltiplas wallets. Omita para usar a sua wallet predefinida.
data-amount-fromstringOptionalSeletor CSS do elemento que contém o total do carrinho. O montante é lido no momento do clique.
data-referencestringOptionalA sua referência interna (ID de encomenda, número de fatura, etc.). Máx. 255 caracteres.
data-descriptionstringOptionalDescrição do pagamento mostrada no painel. Máx. 500 caracteres.
data-metadatastringOptionalString JSON com pares chave-valor personalizados. Máx. 10KB.
| Name | Type | Required | Description |
|---|---|---|---|
merchant-id | string | Required | O seu Merchant ID (formato: fivo_live_UUID) |
amount | string | Optional | Montante de pagamento fixo (0,01 - 1.000.000). Omita para modo variável. |
currency | string | Optional | "USDC" ou "EURC". Predefinido: "USDC". |
wallet-id | string | Optional | UUID de wallet específica para comerciantes com múltiplas wallets. Omita para usar a sua wallet predefinida. |
data-amount-from | string | Optional | Seletor CSS do elemento que contém o total do carrinho. O montante é lido no momento do clique. |
data-reference | string | Optional | A sua referência interna (ID de encomenda, número de fatura, etc.). Máx. 255 caracteres. |
data-description | string | Optional | Descrição do pagamento mostrada no painel. Máx. 500 caracteres. |
data-metadata | string | Optional | String JSON com pares chave-valor personalizados. Máx. 10KB. |
Atributos Dinâmicos
el.setAttribute('amount', '59.99')Eventos
O botão emite eventos DOM personalizados que pode escutar. Todos os dados do evento estão disponíveis em .e.detail
fivo:payment-successData: txHash, amount, token, chainId
Pagamento confirmado na blockchain
fivo:payment-errorData: error
Pagamento falhou ou foi rejeitado
fivo:payment-trackingData: paymentId, status, step
Atualização do progresso da transferência entre cadeias
| Evento | Dados | Quando |
|---|---|---|
fivo:payment-success | txHash, amount, token, chainId | Pagamento confirmado na blockchain |
fivo:payment-error | error | Pagamento falhou ou foi rejeitado |
fivo:payment-tracking | paymentId, status, step | Atualização do progresso da transferência entre cadeias |
<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>Carrinho Dinâmico
Cole este botão dentro do seu carrinho. Ele lê automaticamente o total da sua página quando o cliente clica. Se não captar o total, altere para corresponder ao ID do elemento do total do carrinho.#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>Não capta o total?
id="something"#somethingdata-amount-fromAvançado: controlo manual
Se precisar de controlo programático total (ex.: o total não está visível na página), pode atualizar o atributo amount diretamente com 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 com gestão de encomendas?
Múltiplos Produtos
Carregue o script uma vez, depois adicione quantos botões precisar. Cada um funciona independentemente.
<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>Ligação Direta para Pagamento
Também pode criar uma ligação direta para a página de pagamento sem incorporar o widget. Útil para faturas por email, ligações em redes sociais ou códigos QR.
https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=49.99¤cy=USDCParâmetros do URL
merchantstringRequiredO seu Merchant ID
amountstringOptionalMontante fixo. Omita para modo variável.
currencystringOptional"USDC" ou "EURC". Predefinido: "USDC".
walletIdstringOptionalUUID de wallet específica para comerciantes com múltiplas wallets.
referencestringOptionalA sua referência interna (ID de encomenda, etc.).
descriptionstringOptionalDescrição do pagamento.
metadatastringOptionalString JSON codificada no URL com dados personalizados.
| Name | Type | Required | Description |
|---|---|---|---|
merchant | string | Required | O seu Merchant ID |
amount | string | Optional | Montante fixo. Omita para modo variável. |
currency | string | Optional | "USDC" ou "EURC". Predefinido: "USDC". |
walletId | string | Optional | UUID de wallet específica para comerciantes com múltiplas wallets. |
reference | string | Optional | A sua referência interna (ID de encomenda, etc.). |
description | string | Optional | Descrição do pagamento. |
metadata | string | Optional | String JSON codificada no URL com dados personalizados. |
<a href="https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=150.00¤cy=USDC">
Pay Invoice #1234, $150.00 USDC
</a>Sessões de Pagamento (Modo Redirecionamento)
Para integrações do lado do servidor, pode criar uma sessão de pagamento através da API e redirecionar o seu cliente para uma página de pagamento alojada pelo Fivo. Após o pagamento, o cliente é redirecionado de volta ao seu site. Isto é semelhante ao Stripe Checkout.
Integração do Lado do Servidor
Como funciona
O seu servidor cria uma sessão
Chame POST /checkout/sessions com o montante, moeda e um URL de retorno.
Redirecione o cliente
Utilize o URL devolvido para redirecionar o seu cliente para a página de pagamento do Fivo.
O cliente paga
O cliente liga a sua wallet e completa o pagamento na página alojada.
O cliente regressa ao seu site
Após o pagamento, o cliente é redirecionado para o seu return_url com o ID da sessão.
Verifique o pagamento no seu servidor
Chame GET /checkout/sessions/:id para confirmar o estado do pagamento antes de processar a encomenda.
1. Criar uma sessão (lado do 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. Redirecionar o cliente
// Express.js example
app.post('/create-checkout', async (req, res) => {
const session = await createCheckoutSession(req.body);
res.redirect(303, session.url);
});3. Verificar o pagamento no retorno
// 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 | numberOptionalMontante do pagamento (0,01 - 1.000.000). Omita para montante variável.
currencystringOptional"USDC" ou "EURC". Predefinido: "USDC".
return_urlstringRequiredURL para redirecionar o cliente após o pagamento. Deve ser HTTPS em produção.
cancel_urlstringOptionalURL para redirecionar se o cliente cancelar. Deve ser HTTPS em produção.
metadataobjectOptionalAté 5 pares chave-valor para a sua referência interna (ex.: ID de encomenda).
expires_innumberOptionalTempo de vida da sessão em segundos (60 - 86400). Predefinido: 1800 (30 min).
| Name | Type | Required | Description |
|---|---|---|---|
amount | string | number | Optional | Montante do pagamento (0,01 - 1.000.000). Omita para montante variável. |
currency | string | Optional | "USDC" ou "EURC". Predefinido: "USDC". |
return_url | string | Required | URL para redirecionar o cliente após o pagamento. Deve ser HTTPS em produção. |
cancel_url | string | Optional | URL para redirecionar se o cliente cancelar. Deve ser HTTPS em produção. |
metadata | object | Optional | Até 5 pares chave-valor para a sua referência interna (ex.: ID de encomenda). |
expires_in | number | Optional | Tempo de vida da sessão em segundos (60 - 86400). Predefinido: 1800 (30 min). |
Moedas e Cadeias Suportadas
| Moeda | Código | Cadeias |
|---|---|---|
| USD Coin | USDC | Todas as 9 cadeias |
| 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 |
Os clientes podem pagar a partir de qualquer cadeia. Se a cadeia deles for diferente da cadeia da sua wallet, os pagamentos em USDC são automaticamente transferidos via Circle CCTP (normalmente 1-2 minutos). EURC é apenas na mesma cadeia e não suporta transferências entre cadeias.
Como Funciona
O cliente clica no botão
Uma sobreposição de pagamento abre por cima da sua página. O seu site permanece carregado por baixo.
O cliente liga a wallet
Suporta MetaMask, Coinbase Wallet, WalletConnect e outras wallets populares.
O cliente seleciona a cadeia e paga
O widget verifica as cadeias suportadas à procura de saldos USDC (9 cadeias) ou EURC (3 cadeias) e mostra as opções disponíveis.
Recebe os fundos
Pagamentos na mesma cadeia são instantâneos. Pagamentos USDC entre cadeias chegam em 1-2 minutos via CCTP. EURC é apenas na mesma cadeia.
Email do Cliente e Recibos
Cada pagamento requer que o cliente introduza o seu endereço de email antes de pagar. O widget trata disto automaticamente. Um campo de email obrigatório é mostrado antes do passo de ligação à wallet.
Para clientes
Após o pagamento, o cliente recebe um email de recibo com o seu ID de Pagamento, montante, nome do comerciante e ligação para a transação na blockchain.
Para comerciantes
Pode ver os emails dos clientes na sua página de Transações e pesquisar reembolsos por email em vez de ID de Pagamento.
Rastreio de Encomendas
Utilize atributos opcionais para ligar pagamentos aos seus sistemas internos. Estes são passados para webhooks e visíveis no seu painel.
<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-referencestringOptionalO seu ID de encomenda/fatura. Visível no painel e webhooks. Máx. 255 caracteres.
data-descriptionstringOptionalDescrição do pagamento. Visível no painel. Máx. 500 caracteres.
data-metadatastringOptionalString JSON com quaisquer dados personalizados. Incluída nos webhooks. Máx. 10KB.
| Name | Type | Required | Description |
|---|---|---|---|
data-reference | string | Optional | O seu ID de encomenda/fatura. Visível no painel e webhooks. Máx. 255 caracteres. |
data-description | string | Optional | Descrição do pagamento. Visível no painel. Máx. 500 caracteres. |
data-metadata | string | Optional | String JSON com quaisquer dados personalizados. Incluída nos webhooks. Máx. 10KB. |
Estes são opcionais
Bom Saber
Leve
Script de ~7KB, carrega de forma assíncrona. Não atrasa o seu site.
Estilos isolados
Utiliza Shadow DOM. O seu CSS não o afeta.
Proteção contra fraude
Montantes fixos são verificados na blockchain.
9 blockchains
USDC em todas as 9 cadeias com bridging automático via CCTP. EURC em 3 cadeias (apenas na mesma cadeia).
Precisa de mais controlo?
Utilize para fluxos de redirecionamento do lado do servidor, ou consulte o guia de integração API para webhooks e consultas de pagamento programáticas.Sessões de Pagamento