Copy page

Tutoriais

Criar e monitorar solicitações de pagamento

O fluxo de pagamento

Entender o fluxo completo de pagamento ajuda a integrar a Fluxis de forma eficaz na sua aplicação:

Code
sequenceDiagram
    participant M as Your App
    participant F as Fluxis API
    participant C as Customer
    participant B as Blockchain

    M->>F: Create Payment Request
    F-->>M: Payment Details + NASPIP Token
    M->>C: Display Payment (QR/Link)
    C->>B: Send Payment
    B->>F: Transaction Detected
    F->>M: Webhook: Processing
    B->>F: Transaction Confirmed
    F->>M: Webhook: Completed
    M->>C: Order Confirmed

Detalhamento do fluxo

1. Sua app cria uma solicitação de pagamento via API Fluxis para um valor específico
2. A Fluxis retorna os detalhes da solicitação incluindo um token NASPIP
3. O cliente vê a solicitação como QR code ou link de pagamento
4. O cliente paga usando a carteira cripto
5. A Fluxis detecta o pagamento na blockchain e notifica você
6. A transação é confirmada e você atende o pedido

Criar uma solicitação de pagamento

Para criar uma solicitação de pagamento, você precisará de:

Você pode criar sua primeira solicitação no nosso API Playground - Payment Request.

Alternativamente, use hosted checkout (POST /v1/pos/{posID}/payment-request-checkout) para receber uma checkout_url e redirecionar clientes sem construir sua própria UI NASPIP.

O token NASPIP

O token NASPIP é uma string assinada criptograficamente que contém todas as instruções de pagamento:

Code
naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI1LTEwLTI...

Este token pode ser:

• Codificado como QR code para leitura em carteira móvel
• Compartilhado como link de pagamento para carteiras web/desktop
• Compartilhado por carteiras com NFC para pagamento por proximidade ou offline

Tokens NASPIP baseados em URL

Alguns tokens incorporam uma url em vez de instruções inline. Use POST /v1/naspip/read com o token — quando o payload contém URL sem payment_options, a Fluxis resolve as instruções buscando essa URL no servidor antes de retornar os dados decodificados.

Estados da solicitação de pagamento

As solicitações progridem por diferentes estados durante o ciclo de vida:

Diagrama de transição de estados

Code
stateDiagram-v2
    [*] --> created: Payment Request Created
    created --> expired: 8 minutes timeout
    created --> processing: Payment Detected
    processing --> completed: Correct Amount
    processing --> underpaid: Amount < Expected
    processing --> overpaid: Amount > Expected
    processing --> failed: Error Occurred

    completed --> [*]
    expired --> [*]
    underpaid --> [*]
    overpaid --> [*]
    failed --> [*]

Descrição dos estados

Estado	Significado	O que fazer
created	Aguardando pagamento (ativo por ~8 minutos)	Exibir ao cliente, monitorar mudanças
processing	Pagamento detectado, aguardando confirmação blockchain	Continuar monitorando, informar o cliente
completed	Pagamento recebido e confirmado	Atender pedido, encerrar solicitação
expired	Tempo esgotado sem pagamento	Oferecer criar nova solicitação
underpaid	Recebido menos que o valor esperado	Contatar suporte para resolução
overpaid	Recebido mais que o valor esperado	Contatar suporte para resolução
failed	Erro inesperado durante o processamento	Contatar suporte; pode ser necessária nova solicitação

Monitorar o status do pagamento

Após criar uma solicitação, você precisa monitorar o status para saber quando o pagamento é recebido. Há duas abordagens:

Opção 1: Polling

Consulte periodicamente o status chamando o endpoint de status.

Endpoint: GET /v1/pos/{posID}/payment-request/{paymentRequestID}

Teste no nosso API Playground - Get Payment Request.

Estratégia de polling

Vantagens:

• Simples de implementar
• Funciona com qualquer infraestrutura
• Sem configuração adicional

Desvantagens:

• Não é em tempo real
• Gera overhead na API
• Pode perder mudanças rápidas de status

Opção 2: Webhooks

Configure webhooks em nível de conta para receber notificações quando o status mudar. Esta é a abordagem recomendada para sistemas em produção.

Endpoint: POST /v1/account/{accountID}/webhook

Teste no API Playground — Create webhook.

Configuração de webhook

Registre uma URL HTTPS completa e defina event_type como payment_request:

Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}

A Fluxis gera o secret de assinatura e retorna uma vez na resposta de criação. Webhooks disparam para processing, completed, underpaid e overpaid — não para expired ou failed.

Consulte o guia de Webhooks e Verificação de assinatura de webhook. Após o registro, valide o handler com POST /v1/account/{accountID}/webhook/{webhookID}/test.

Vantagens:

• Notificações em tempo real
• Sem overhead de polling
• Eficiente e escalável
• Arquitetura orientada a eventos

Desvantagens:

• Exige endpoint público
• Precisa implementar handler de webhook
• Deve verificar assinaturas de webhook

::::tip Boa prática Use webhooks em produção e polling como fallback. Implemente ambos para nunca perder uma confirmação de pagamento. ::::

Tratar diferentes cenários

Cenário 1: Pagamento bem-sucedido

1. Cliente escaneia QR code ou clica no link de pagamento
2. Cliente confirma o pagamento na carteira
3. Pagamento aparece na blockchain
4. Status muda para processing
5. Transação recebe confirmações suficientes
6. Status muda para completed
7. Você atende o pedido

Sua ação: Atenda o pedido quando o status for completed.

Cenário 2: Solicitação expirada

1. Passam ~8 minutos sem pagamento
2. Status muda para expired
3. A solicitação não é mais válida

Sua ação: Ofereça ao cliente criar uma nova solicitação de pagamento.

Cenário 3: Transação lenta

1. Cliente inicia pagamento perto da expiração
2. Transação é transmitida mas não confirmada antes do timeout
3. Período de carência da Fluxis processa a transação tardia
4. Status atualiza para processing e depois completed

Sua ação: Continue monitorando mesmo após a expiração por mais 2-3 minutos.

Boas práticas

1. Sempre use Reference IDs

2. Exiba informações claras de pagamento

3. Trate expiração com elegância

4. Nunca confie apenas no status

5. Armazene dados da solicitação de pagamento

Padrões comuns de integração

Fluxo de checkout e-commerce

Code
sequenceDiagram
    participant C as Customer
    participant S as Your Store
    participant F as Fluxis

    C->>S: Place Order
    S->>S: Create Order Record
    S->>F: Create Payment Request
    F-->>S: Payment Details
    S->>C: Show Payment QR

    loop Monitor
        C->>F: Send Payment
        F-->>S: Webhook: Processing
        S->>C: Update UI: Processing
        F-->>S: Webhook: Completed
        S->>C: Update UI: Confirmed
    end

    S->>S: Fulfill Order
    S->>C: Send Confirmation Email

Terminal ponto de venda

Code
sequenceDiagram
    participant C as Customer
    participant T as Terminal
    participant F as Fluxis

    T->>T: Cashier Enters Amount
    T->>F: Create Payment Request
    F-->>T: Display QR Code
    C->>F: Customer Scans & Pays

    loop Poll
        T->>F: Check Status
        F-->>T: Status: Processing
        T->>T: Show "Processing"
    end

    F-->>T: Status: Completed
    T->>T: Print Receipt
    T->>C: Transaction Complete

Solução de problemas

Solicitação de pagamento não é criada

Sintomas: Erro ao criar solicitação de pagamento

Causas comuns:

• Token de acesso inválido ou expirado
• ID de Ponto de Venda inexistente ou fora da organização
• Formato UAI inválido
• Valor zero ou negativo

Solução: Verifique token de autenticação, ID de Ponto de Venda e parâmetros da requisição.

Status não atualiza

Sintomas: Status preso em created apesar do pagamento do cliente

Causas comuns:

• Pagamento enviado para endereço errado
• Pagamento com ativo/rede incorretos
• Confirmações de rede insuficientes
• Pagamento pendente na carteira do cliente

Solução: Peça ao cliente verificar o hash da transação. Consulte o explorador blockchain para confirmar o status.

Webhooks não recebidos

Sintomas: Notificações webhook não chegam

Causas comuns:

• URL de webhook não publicamente acessível
• Firewall bloqueando IPs da Fluxis
• Endpoint de webhook retornando erros
• Problemas de certificado SSL/TLS

Solução: Chame POST /v1/account/{accountID}/webhook/{webhookID}/test para entrega de amostra assinada. Verifique logs do servidor, SSL e confirme que verificação de assinatura passa antes de processar eventos.

Testar sua integração

Antes de ir para produção, teste a integração a fundo:

Checklist de testes

• Criar solicitação de pagamento com parâmetros válidos
• Exibir token NASPIP como QR code
• Monitorar mudanças de status via polling
• Tratar status completed corretamente
• Tratar status expired com elegância
• Testar entrega e parse de webhook
• Verificar assinatura de webhook com segredo da resposta de criação
• Testar webhook via POST /v1/account/{accountID}/webhook/{webhookID}/test
• Tratar erros de rede e retries
• Testar casos extremos (underpaid, overpaid)
• Verificar precisão de valores (decimais)