# 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: ```mermaid 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:

📋 Informações obrigatórias

Você pode criar sua primeira solicitação no nosso [API Playground - Payment Request](/api/point-of-sale#create-point-of-sale-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: ``` 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 ::::tip **Opções de exibição** A maioria dos comerciantes exibe o token NASPIP como QR code para leitura móvel fácil. Codifique o campo `token` da resposta create-payment-request como imagem QR na sua app. :::: ### 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 ```mermaid 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 | ::::info **Casos extremos** Os estados `underpaid`, `overpaid` e `failed` são casos extremos que exigem coordenação com o suporte Fluxis conforme suas necessidades de negócio. Mais informações: [Fluxos de pagamento - Casos extremos](/pt/docs/payment-flows/edge-cases). :::: ## 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](/api/point-of-sale#get-payment-request). #### Estratégia de polling

Intervalo de polling recomendado:

**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](/api/webhooks#create-webhook). #### Configuração de webhook Registre uma URL HTTPS completa e defina `event_type` como `payment_request`: ```json { "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](/pt/docs/developers/webhooks) e [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification). 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

Inclua seu ID interno de pedido ou transação no campo{" "} reference_id. Isso facilita muito conciliação e depuração.

### 2. Exiba informações claras de pagamento

Mostre aos clientes:

### 3. Trate expiração com elegância

Não abandone o cliente se um pagamento expirar. Ofereça opção clara para criar nova solicitação com um clique.

### 4. Nunca confie apenas no status

Sempre verifique se o campo amount corresponde ao valor esperado. Não atenda pedidos com pagamentos underpaid ou failed{" "} sem coordenação.

### 5. Armazene dados da solicitação de pagamento

Mantenha registro no banco vinculando:

## Padrões comuns de integração ### Fluxo de checkout e-commerce ```mermaid 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 ```mermaid 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](/pt/docs/developers/webhook-signature-verification) 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) ::::tip **Ambiente de testes** Entre em contato com o suporte Fluxis para obter credenciais de API de teste e ativos de rede de teste antes de ir para produção. ::::