Docs/Integração do Widget

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.

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

O seu Merchant ID é mostrado na página do seu painel.Integração Format: fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

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

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

  • 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

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

Limites de Montante

Os montantes variáveis são validados entre 0,01 e 1.000.000. Montantes fora deste intervalo mostrarão uma mensagem de erro.

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

O seu Merchant ID (formato: fivo_live_UUID)

amountstringOptional

Montante de pagamento fixo (0,01 - 1.000.000). Omita para modo variável.

currencystringOptional

"USDC" ou "EURC". Predefinido: "USDC".

wallet-idstringOptional

UUID de wallet específica para comerciantes com múltiplas wallets. Omita para usar a sua wallet predefinida.

data-amount-fromstringOptional

Seletor CSS do elemento que contém o total do carrinho. O montante é lido no momento do clique.

data-referencestringOptional

A sua referência interna (ID de encomenda, número de fatura, etc.). Máx. 255 caracteres.

data-descriptionstringOptional

Descrição do pagamento mostrada no painel. Máx. 500 caracteres.

data-metadatastringOptional

String JSON com pares chave-valor personalizados. Máx. 10KB.

i

Atributos Dinâmicos

Os atributos são reativos. Pode atualizá-los com JavaScript (ex.: ) e a etiqueta do botão atualiza-se automaticamente.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-success

Data: txHash, amount, token, chainId

Pagamento confirmado na blockchain

fivo:payment-error

Data: error

Pagamento falhou ou foi rejeitado

fivo:payment-tracking

Data: paymentId, status, step

Atualização do progresso da transferência entre cadeias

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>

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

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

Não capta o total?

Clique com o botão direito no total do carrinho, clique em Inspecionar. O código destacado mostrará . Utilize em . Símbolos de dólar e vírgulas são removidos automaticamente.id="something"#somethingdata-amount-from

Avanç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:

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 com gestão de encomendas?

Para lojas que precisam de rastreio de encomendas do lado do servidor, consulte abaixo.Sessões de Pagamento

Múltiplos Produtos

Carregue o script uma vez, depois adicione quantos botões precisar. Cada um funciona independentemente.

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>

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.

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

Parâmetros do URL

merchantstringRequired

O seu Merchant ID

amountstringOptional

Montante fixo. Omita para modo variável.

currencystringOptional

"USDC" ou "EURC". Predefinido: "USDC".

walletIdstringOptional

UUID de wallet específica para comerciantes com múltiplas wallets.

referencestringOptional

A sua referência interna (ID de encomenda, etc.).

descriptionstringOptional

Descrição do pagamento.

metadatastringOptional

String JSON codificada no URL com dados 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>

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.

i

Integração do Lado do Servidor

As Sessões de Pagamento requerem uma API key. Crie uma no seu . Nunca exponha a sua API key em código do lado do cliente.painel

Como funciona

1

O seu servidor cria uma sessão

Chame POST /checkout/sessions com o montante, moeda e um URL de retorno.

2

Redirecione o cliente

Utilize o URL devolvido para redirecionar o seu cliente para a página de pagamento do Fivo.

3

O cliente paga

O cliente liga a sua wallet e completa o pagamento na página alojada.

4

O cliente regressa ao seu site

Após o pagamento, o cliente é redirecionado para o seu return_url com o ID da sessão.

5

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)

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. Redirecionar o 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 o pagamento no retorno

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

Montante do pagamento (0,01 - 1.000.000). Omita para montante variável.

currencystringOptional

"USDC" ou "EURC". Predefinido: "USDC".

return_urlstringRequired

URL para redirecionar o cliente após o pagamento. Deve ser HTTPS em produção.

cancel_urlstringOptional

URL para redirecionar se o cliente cancelar. Deve ser HTTPS em produção.

metadataobjectOptional

Até 5 pares chave-valor para a sua referência interna (ex.: ID de encomenda).

expires_innumberOptional

Tempo de vida da sessão em segundos (60 - 86400). Predefinido: 1800 (30 min).

Moedas e Cadeias Suportadas

MoedaCódigoCadeias
USD CoinUSDCTodas as 9 cadeias
Euro CoinEURCEthereum, Avalanche, Base
BlockchainTokens
EthereumUSDC, EURC
PolygonUSDC
AvalancheUSDC, EURC
ArbitrumUSDC
BaseUSDC, EURC
OptimismUSDC
LineaUSDC
UnichainUSDC
SonicUSDC

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

1

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.

2

O cliente liga a wallet

Suporta MetaMask, Coinbase Wallet, WalletConnect e outras wallets populares.

3

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.

4

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.

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

O seu ID de encomenda/fatura. Visível no painel e webhooks. Máx. 255 caracteres.

data-descriptionstringOptional

Descrição do pagamento. Visível no painel. Máx. 500 caracteres.

data-metadatastringOptional

String JSON com quaisquer dados personalizados. Incluída nos webhooks. Máx. 10KB.

i

Estes são opcionais

O email do cliente é sempre obrigatório (tratado automaticamente pelo widget). Referência, descrição e metadados são opcionais. Utilize-os quando precisar de ligar pagamentos ao seu sistema de encomendas.

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