Docs/Integração API

Integração API

Crie fluxos de pagamento personalizados e integrações de backend.

Visão Geral

Embora o widget seja a forma mais fácil de aceitar pagamentos, a API do Fivo dá-lhe controlo total para integrações personalizadas. Utilize a API para:

Criar experiências de pagamento personalizadas
Consultar o histórico de pagamentos programaticamente
Integrar com os seus sistemas de backend existentes
Criar pagamentos a partir de código do lado do servidor

Sessões de Pagamento

As Sessões de Pagamento são a forma recomendada de aceitar pagamentos a partir de uma integração do lado do servidor. O seu servidor cria uma sessão, redireciona o cliente para uma página de pagamento alojada pelo Fivo e verifica o pagamento quando o cliente regressa.

Quando utilizar cada método

Widget Embed

Produtos fixos, donativos, sites estáticos

Backend: Não

Widget + data-amount-from

Carrinhos de compras, totais dinâmicos

Backend: Não

Ligação Direta

Emails, redes sociais, códigos QR

Backend: Não

Sessões de Pagamento

E-commerce, SaaS, processamento de encomendas

Backend: Sim (API key)

Método	Ideal para	Backend necessário?
Widget Embed	Produtos fixos, donativos, sites estáticos	Não
Widget + `data-amount-from`	Carrinhos de compras, totais dinâmicos	Não
Ligação Direta	Emails, redes sociais, códigos QR	Não
Sessões de Pagamento	E-commerce, SaaS, processamento de encomendas	Sim (API key)

Exemplo 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);

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

Referência completa

Consulte a para todos os parâmetros, esquemas de resposta e valores de estado da sessão.Referência da API

URL Base

https://api.fivo.finance

API de Produção

Este é o endpoint da API de produção. Todos os pedidos são processados na mainnet. Notificaremos todos os comerciantes antes de qualquer alteração incompatível.

Autenticação

A API do Fivo utiliza dois métodos de autenticação:

Tokens JWT

Para sessões do painel e do utilizador. Obtidos após o início de sessão. Expiram após 15 minutos.

Authorization: Bearer <token>

API Keys

Para integrações servidor-a-servidor. Criadas no painel. Não expiram mas podem ser revogadas.

X-API-Key: <api_key>

Criar uma API Key

Inicie sessão no seu Painel Fivo
Navegue até API Keys
Clique em Criar Nova Chave
Dê à sua chave um nome descritivo (ex.: "Servidor de Produção")
Copie a chave imediatamente. Não será mostrada novamente!

Mantenha as Suas Chaves em Segredo

Nunca exponha API keys em código do lado do cliente. As API keys devem ser utilizadas apenas em aplicações do lado do servidor onde possam ser mantidas em segredo.

Exemplo: Verificar Estado do Pagamento

Depois de um cliente pagar através do widget, pode verificar o estado do pagamento:

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

Exemplo: Listar os Seus Pagamentos

Consulte o seu histórico de pagamentos com filtros. Requer autenticação.

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

Exemplos cURL

Para testes rápidos, pode utilizar cURL a partir da linha 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 e Bibliotecas

Os SDKs oficiais estarão disponíveis em breve. Entretanto, pode utilizar bibliotecas HTTP padrão em qualquer linguagem para interagir com a API.

Node.js SDK

Em breve

Python SDK

Em breve

PHP SDK

Em breve

Limites de Taxa

A API tem limites de taxa para garantir utilização justa e estabilidade do sistema:

Endpoints de API Key

200 pedidos por minuto

Per: API Key

API Geral

100 pedidos por minuto

Per: IP

Criação de pagamento (widget)

20 pedidos por minuto

Per: IP

Início de sessão

5 pedidos por 5 minutos

Per: IP + email

Registo

3 pedidos por 15 minutos

Per: IP

Recuperação de Palavra-passe

3 pedidos por 15 minutos

Per: IP + email

Verificação 2FA

5 pedidos por 5 minutos

Per: IP

Levantamentos

10 pedidos por 10 minutos

Per: IP

Formulário de contacto

3 pedidos por 15 minutos

Per: IP

Endpoint	Limite	Janela	Por
Endpoints de API Key	200 pedidos	por minuto	API Key
API Geral	100 pedidos	por minuto	IP
Criação de pagamento (widget)	20 pedidos	por minuto	IP
Início de sessão	5 pedidos	por 5 minutos	IP + email
Registo	3 pedidos	por 15 minutos	IP
Recuperação de Palavra-passe	3 pedidos	por 15 minutos	IP + email
Verificação 2FA	5 pedidos	por 5 minutos	IP
Levantamentos	10 pedidos	por 10 minutos	IP
Formulário de contacto	3 pedidos	por 15 minutos	IP

Quando excede um limite de taxa, recebe uma resposta com um cabeçalho indicando quando pode tentar novamente.429 Too Many RequestsRetry-After

Referência Completa da API

Consulte a lista completa de endpoints, parâmetros e formatos de resposta.

Ver Referência da API