Copy page

Conceitos-chave

Liquidações e consolidação

Depois que os clientes pagam, a Fluxis processa os fundos por meio de dois pipelines automatizados no backend: consolidação (mover ativos dos vaults de pagamento) e liquidação (agrupar transações de ledger confirmadas e enviar o líquido para seus endereços configurados).

Fluxo de alto nível

Code
flowchart LR
    PR[Payment Request] --> V[Vault Address]
    V --> C[Consolidation]
    C --> LT[Ledger Transaction]
    LT --> S[Settlement Batch]
    S --> ADDR[Your Settlement Address]

1. Pagamento — o cliente envia cripto para um endereço vault por solicitação
2. Consolidação — jobs cron agregam pagamentos concluídos dos vaults
3. Confirmação — solicitações de pagamento atingem confirmed; transações de ledger são criadas
4. Liquidação — jobs cron agrupam transações e transferem valores líquidos para seu endereço de liquidação

O monitoramento on-chain roda hoje em Polygon, Base, Avalanche e Arbitrum.

Consolidação

A consolidação agrupa solicitações de pagamento concluídas por endereço vault e ativo, depois move fundos de wallets vault efêmeras para wallets de consolidação controladas pela Fluxis.

Agendamento cron

Job	Schedule	Purpose
CONSOLIDATION_AGGREGATION_JOB	Every 10 minutes	Agrupar solicitações de pagamento elegíveis por vault + token
CONSOLIDATION_EXECUTION_JOB	Every 30 minutes	Executar transferências de consolidação pendentes

Solicitações de pagamento vinculadas a uma consolidação recebem um consolidation_id no banco de dados. Este é um passo operacional interno — comerciantes normalmente observam o resultado pelo status da solicitação de pagamento e registros de transações, não diretamente pelos IDs de consolidação.

Liquidação

A liquidação agrupa transações de ledger confirmadas por conta, organização e token, depois envia o líquido para endereços de liquidação configurados.

Agendamento cron

Job	Schedule	Purpose
SETTLEMENT_AGGREGATION_JOB	Hourly at :00	Agrupar transações não liquidadas em registros de liquidação
SETTLEMENT_EXECUTION_JOB	Hourly at :05	Processar liquidações pendentes (transferências on-chain)
SETTLEMENT_CONFIRMATION_JOB	Hourly at :15	Confirmar transações de liquidação on-chain

Status de liquidação

Status	Meaning
created	Registro de liquidação criado
pending	Pronto para execução
processing	Transferência em andamento
completed	Fundos entregues
failed	Execução falhou
in_review	Revisão manual necessária

Se não houver endereço de liquidação configurado para a conta (ou sua organização pai) na rede necessária, a agregação registra um erro e ignora esse lote.

Endereços de liquidação

Endereços de liquidação informam à Fluxis para onde enviar seu líquido por rede blockchain. Ordem de resolução:

1. Endereço em nível de conta para a rede (se configurado)
2. Endereço em nível de organização para a rede (padrão de fallback)

REST API — escopo de organização

Chaves API de organização podem gerenciar endereços diretamente:

Method	Endpoint	Description
GET	/v1/organization/settlement-addresses	Listar endereços da organização
POST	/v1/organization/settlement-addresses	Criar endereço para uma rede
PUT	/v1/organization/settlement-addresses	Atualizar endereço para uma rede
DELETE	/v1/organization/settlement-addresses?network=polygon	Remover endereço para uma rede

Corpo da solicitação (POST/PUT):

Code
{
  "network": "polygon",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "address_tag": null
}

REST API — escopo de conta

Code
GET /v1/account/{accountId}/settlement-addresses

Retorna endereços de liquidação efetivos para a conta (incluindo fallbacks da organização). Endpoints de criar/atualizar/excluir em nível de conta existem no código, mas não estão expostos atualmente na API pública — configure substituições específicas de conta pelo Fluxis Dashboard ou entre em contato com o suporte.

Campos de resposta

Field	Description
owner	organization ou account
settlement_type	Categoria de taxa (ex.: payment_net_amount, payment_service_fee)
settlement_address	Endereço blockchain de destino
address_type	Identificador de rede (ex.: polygon, base)
address_tag	Memo/tag opcional para redes suportadas

Dashboard

Endereços de liquidação de conta também podem ser gerenciados no Fluxis Dashboard nas configurações da conta (seção de endereços de liquidação).

Itens de liquidação

Cada liquidação pode conter múltiplos items representando divisões de taxas:

• Valor líquido ao comerciante (payment_net_amount)
• Taxas de serviço (payment_service_fee)
• Taxas de desenvolvedor (payment_developer_fee)
• Taxas de revenue share (payment_revenue_shared_fee)

Cada item mapeia para um endereço de liquidação do tipo correspondente quando configurado.

O que comerciantes devem configurar

1. Endereços de liquidação da organização — no mínimo, um endereço por rede que você aceita (Polygon, Base, Avalanche, Arbitrum)
2. Substituições de conta (opcional) — destinos por conta quando subcomerciantes precisam de repasses separados
3. Webhook + reconciliação de transações — a liquidação é assíncrona; use Webhook Events e Transactions para rastrear confirmação de pagamento antes de esperar a liquidação

Relação com solicitações de pagamento

Payment request status	Consolidation	Settlement
completed / overpaid / underpaid	Elegível após processamento	Após confirmed + transação de ledger
confirmed	Pode já estar consolidado	Elegível para agregação de liquidação
expired / failed	Não elegível	Não elegível

Documentação relacionada

• Payment Requests — ciclo de vida de status até confirmed
• Transactions — registros de ledger que alimentam a liquidação
• API Integration Guide — Passo 4 configuração de liquidação
• About Fluxis — redes suportadas e escopo de liquidação