Copy page

Plataforma

Transações

A API de Transações retorna registros contábeis criados após a confirmação de pagamentos bem-sucedidos. Use-a para conciliar pagamentos, auditar saldos e respaldar integrações baseadas em webhooks.

Visão geral

Cada solicitação de pagamento confirmada produz um registro de transação. Transações incluem valores brutos e líquidos, metadados de ativo e rede, endereços de origem e destino e hashes de transação on-chain opcionais.

Transações estão no escopo da entidade autenticada:

• Chaves de API em nível de conta — transações apenas dessa conta
• Chaves de API em nível de organização — todas as transações da organização, ou uma conta específica quando accountID é informado

Autenticação

Todas as requisições exigem ambos os cabeçalhos:

• Authorization: Bearer <access_token>
• x-fluxis-api-key: <your_api_key>

Listar transações

Code
GET /v1/transactions?page=1&page_size=50

Parâmetros de consulta

Parâmetro	Obrigatório	Descrição
page	Sim	Número da página (mínimo 1)
page_size	Sim	Itens por página (5–100)
accountID	Não	Filtrar por conta específica (apenas chaves de organização). Deve pertencer à sua organização

Exemplo

Code
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"

Para chaves de organização limitadas a uma conta:

Code
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50&accountID=c87464d1-c54a-48c3-80c9-bee4fddf593d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"

Formato da resposta

Code
{
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "payment_in",
        "status": "completed",
        "gross_amount": "100.00",
        "net_amount": "97.50",
        "expected_amount": "100.00",
        "currency": "USDC",
        "network": "polygon",
        "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "from_type": "wallet",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "to_type": "vault",
        "financial_provider": "fluxis",
        "transaction_hash": "0xabcdef...",
        "created_at": "2026-05-21T12:00:00Z",
        "updated_at": "2026-05-21T12:05:00Z"
      }
    ],
    "total": 150,
    "page": 1,
    "page_size": 50,
    "total_pages": 3
  }
}

Tipos de transação

Tipo	Descrição
payment_in	Pagamento recebido do cliente
payment_out	Pagamento de saída
deposit	Depósito
withdraw	Saque
refund	Reembolso
adjustment	Ajuste manual
swap	Troca de ativos
dry_run	Registro de teste / pré-visualização

A maioria das integrações de comerciantes interage principalmente com registros payment_in criados quando solicitações de pagamento atingem confirmed.

Status de transação

Status	Descrição
preview	Estado de pré-visualização
pending	Aguardando processamento
created	Registro criado
processing	Em andamento
completed	Concluído com sucesso
failed	Falhou
error	Estado de erro
expired	Expirado

Relação com solicitações de pagamento

Code
sequenceDiagram
    participant PR as Payment Request
    participant WH as Webhook
    participant TX as Transaction

    PR->>PR: processing → completed / underpaid / overpaid
    PR->>WH: payment_request_status_update
    PR->>PR: confirmed (ledger step)
    PR->>TX: payment_in transaction created

1. Webhooks disparam em processing, completed, underpaid e overpaid — consulte Eventos de webhook.
2. Após a confirmação, uma transação contábil aparece em GET /v1/transactions.
3. Faça polling de transações como fallback se um webhook for perdido.

Padrão de conciliação

Fluxo recomendado:

1. Armazene IDs de solicitação de pagamento ao criar sessões de checkout
2. Atualize o status do pedido a partir de webhooks payment_request
3. Diariamente (ou sob demanda), percorra GET /v1/transactions e concilie lacunas

Documentação relacionada

• Solicitações de pagamento — ciclo de vida de status
• Eventos de webhook — atualizações de status em tempo real
• Verificação de assinatura de webhook — verificação HMAC para entregas de webhook
• Liquidações e consolidação — como os fundos se movem após a confirmação
• Guia de integração API — Etapa 7 conciliação