Copy page

Fluxos de pagamento

Fluxo de pagamento — Casos extremos

Nem todo pagamento segue o caminho feliz. Esta página cobre resultados não padrão — pagamento insuficiente, pagamento em excesso, expiração, transações on-chain falhas e reembolsos — incluindo o que a Fluxis faz internamente, quais webhooks você recebe e como tratar cada cenário na sua integração.

Visão geral

Code
flowchart TD
    PR[Payment Request] --> Exp{Expired before payment?}
    Exp -->|Yes| E[expired]
    Exp -->|No| Pay{Customer pays}
    Pay --> Proc[processing]
    Proc --> Final{After finality}
    Final -->|Amount matches| Comp[completed → confirmed]
    Final -->|Too little| Under[underpaid]
    Final -->|Too much| Over[overpaid → confirmed]
    Final -->|Tx failed on-chain| Fail[stuck in processing]

Scenario	Final status	Internal transaction	Webhook sent
Exact payment	completed → confirmed	Yes	processing, completed
Underpayment	underpaid	No	processing, underpaid
Overpayment	overpaid → confirmed	Yes (full received amount)	processing, overpaid
No payment in time	expired	No	No
On-chain tx reverts / fails	processing (stuck)	No	processing only

Matriz de entrega de webhooks

A Fluxis envia webhooks em nível de conta apenas para estas mudanças de status de solicitação de pagamento:

Status	Webhook delivered	Typical trigger
processing	Yes	Cron detectou transferência on-chain (salto 1)
completed	Yes	Confirmado após finalidade; valor corresponde (salto 2)
underpaid	Yes	Confirmado após finalidade; valor muito baixo (salto 2)
overpaid	Yes	Confirmado após finalidade; valor muito alto (salto 2)
confirmed	No	Transação interna de ledger criada (salto 3)
expired	No	Cron de expiração marca solicitação como expirada
failed	No	Não definido atualmente pelo worker
pending / created	No	Criação inicial — consulte ou use seu próprio estado de UI

---

Underpaid

Um pagamento underpaid ocorre quando o cliente envia menos que o valor esperado e a transação on-chain é confirmada após a finalidade.

O que a Fluxis faz

Code
sequenceDiagram
    participant W as Transaction Worker
    participant DB as Database
    participant WH as Webhook

    W->>W: Compare received vs expected
    Note over W: received < expected
    W->>DB: status → underpaid
    W->>WH: Webhook (underpaid)
    W->>W: Release vault
    Note over W: Hop 3 skipped — no internal transaction

1. O salto 2 compara ReceivedAmount (da detecção do cron) com ExpectedAmount
2. Status é definido como underpaid
3. Um webhook é enviado com status underpaid
4. O vault é liberado e removido do cache Redis
5. Salto 3 é ignorado — nenhum registro interno de Transaction é criado, status não atinge confirmed

Tratamento do comerciante

Action	Recommendation
Do not fulfill the order automatically	Trate underpaid como pagamento parcial que exige revisão manual
Contact the customer	Solicite o saldo restante ou acorde cumprimento parcial
Create a new payment request	Para a diferença pendente, se o cliente concordar em pagar mais
Request a refund	Use a Refunds API para devolver o valor parcial à wallet do cliente

Status elegíveis para reembolso incluem underpaid. Consulte Refunds API abaixo.

---

Overpaid

Um pagamento overpaid ocorre quando o cliente envia mais que o valor esperado.

O que a Fluxis faz

Code
sequenceDiagram
    participant W as Transaction Worker
    participant DB as Database
    participant WH as Webhook

    W->>W: Compare received vs expected
    Note over W: received > expected
    W->>DB: status → overpaid, save full received amount
    W->>WH: Webhook (overpaid)
    W->>W: Hop 3 — create internal transaction
    W->>DB: status → confirmed

1. O salto 2 define status como overpaid e registra o valor recebido integral
2. Um webhook é enviado com status overpaid
3. O salto 3 cria uma Transaction interna pelo valor recebido integral
4. Status transiciona para confirmed (sem webhook adicional)

Tratamento do comerciante

Action	Recommendation
Fulfill the order for the requested amount	O cliente pagou pelo menos o preço esperado
Refund the excess	Use POST /v1/refunds/payment-request/{paymentRequestID} com amount explícito para a porção overpaid
Contact support	Para casos complexos onde reembolso automático é insuficiente

Quando amount é omitido em solicitação de reembolso para pagamento overpaid, a Fluxis reembolsa por padrão a porção overpaid (recebido menos esperado).

---

Expired

Uma solicitação de pagamento expira quando nenhum pagamento on-chain é detectado antes do timestamp de expiração.

Temporização

Setting	Value	Scope
Payment request expiration	8 minutos	Desde atribuição de vault (status created)
Payment intention expiration	5 minutos	Apenas fluxo PoS caixa, antes de criar PR
Expiration check interval	Every 30 seconds	Job cron em segundo plano

O que a Fluxis faz

Code
stateDiagram-v2
    created --> expired: expiration < now (cron)
    expired --> [*]

1. O cron de expiração encontra solicitações com status = created e expiration < now
2. Atualiza status para expired
3. Nenhum webhook é enviado por expiração
4. O vault não é liberado imediatamente — é reciclado quando o pool de vaults o reatribui (lógica de sobrescrita de vault expirado)

Tratamento do comerciante

Action	Recommendation
Show expiration in UI	Exiba contagem regressiva baseada no campo expiration da resposta de criação
Create a new payment request	Recuperação padrão — cada solicitação é de uso único
Poll for late payments	Se o cliente afirma ter pago, verifique status antes de criar solicitação duplicada

Consulte Payment Requests — Timing para detalhes.

---

Transação falha presa em processing

Quando uma transação on-chain falha ou reverte após ser detectada, o worker registra a falha mas não atualiza o status da solicitação de pagamento.

O que a Fluxis faz

No salto 2 (transaction_check_update_payment_request), quando GetTransaction retorna status failed:

1. O worker registra "Blockchain Transaction Failed"
2. Retorna sem atualizar a solicitação de pagamento
3. A solicitação de pagamento permanece em processing indefinidamente
4. Nenhum webhook adicional é enviado além da notificação inicial processing

Code
flowchart LR
    A[processing] --> B{GetTransaction status}
    B -->|confirmed| C[completed / underpaid / overpaid]
    B -->|pending| D[Re-enqueue with finality delay]
    B -->|failed| E[Log only — stays processing]

Tratamento do comerciante

Action	Recommendation
Verify on-chain	Busque o hash da transação (se disponível) em um block explorer
Do not fulfill	Status processing preso não garante pagamento
Contact support	Forneça o ID da solicitação de pagamento e hash da transação
Create a new payment request	Se a transação original falhou definitivamente

---

Refunds API

A Fluxis fornece uma Refunds API para iniciar reembolsos de solicitações de pagamento elegíveis. Reembolsos são criados no nível da API e disparam notificação webhook — a execução on-chain do reembolso ainda não está automatizada.

Status elegíveis

Reembolsos podem ser criados quando a solicitação de pagamento está em um de:

• completed
• confirmed
• overpaid
• underpaid

Criar um reembolso

Code
POST /v1/refunds/payment-request/{paymentRequestID}
Authorization: Bearer <token>
x-fluxis-api-key: <api_key_id>

Code
{
  "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "amount": "5.00",
  "reason": "Customer overpaid — returning excess"
}

Field	Required	Description
refund_to_address	Yes	Endereço wallet do cliente para receber o reembolso
amount	No	Valor a reembolsar. Se omitido: valor integral para completed/confirmed, porção overpaid para overpaid
reason	No	Motivo em texto livre para auditoria

Exemplo de resposta:

Code
{
  "status": "success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "5.00",
    "status": "processing"
  }
}

Verificar status do reembolso

Code
GET /v1/refunds/{refundID}

Webhook de reembolso

Ao criar um reembolso, a Fluxis envia webhook com notification_type: refund_status_update:

Code
{
  "data": {
    "notification_type": "refund_status_update",
    "refund_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "status": "processing",
    "amount": "5.00"
  }
}

Cenários comuns de reembolso

Scenario	Suggested approach
Overpaid	Omita amount para reembolsar o excesso, ou especifique a porção overpaid exata
Underpaid — return partial payment	Especifique amount igual ao valor recebido (parcial)
Completed — full refund	Omita amount para reembolsar o pagamento integral
Customer provided wrong address	Entre em contato com suporte se o endereço de reembolso precisar correção após envio

---

Checklist de integração para casos extremos

Use este checklist ao construir integrações de produção:

Code
flowchart TD
    A[Receive webhook] --> B{Verify HMAC signature}
    B -->|Invalid| X[Reject — 401]
    B -->|Valid| C{status?}
    C -->|processing| D[Show confirming UI — do not fulfill]
    C -->|completed| E[Fulfill order]
    C -->|underpaid| F[Manual review / refund / new PR]
    C -->|overpaid| G[Fulfill order / refund excess]
    H[Poll GET payment-request] --> I{status?}
    I -->|expired| J[Offer new payment request]
    I -->|processing + tx failed on-chain| K[Contact support]

1. Trate os quatro status webhook — processing, completed, underpaid, overpaid
2. Nunca cumpra em processing — aguarde um resultado terminal de valor
3. Consulte expired e confirmed — estes não disparam webhooks
4. Exiba contagem regressiva de 8 minutos — reduza tickets de suporte por expiração
5. Verifique assinaturas webhook — consulte Webhook Signature Verification
6. Use a Refunds API para resolução overpaid/underpaid quando apropriado
7. Monitore processing preso — verifique block explorer se status não progride

Documentação relacionada

• Payment Flow — Happy Path — Fluxo padrão criar → detectar → confirmar
• Payment Requests — Definições de status e exemplos de API
• Creating Payment Requests — Guia de integração
• Webhooks — Registro e formato de payload
• Webhook Signature Verification — Verificação HMAC e fluxo de teste
• FAQ — Payment Monitoring — Perguntas frequentes
• API Reference — Refunds — Documentação interativa de endpoints