# Solicitações de pagamento ## O que são solicitações de pagamento? **Payment Requests** são instruções de pagamento geradas usando a API REST Fluxis, assinadas e convertidas em NASPIP Tokens. Representam uma forma padronizada para comerciantes solicitarem pagamentos de usuários em múltiplas redes blockchain e ativos. Cada Payment Request inclui todos os detalhes essenciais que um usuário precisa para concluir um pagamento, como: - rede blockchain - token - valor - endereço - pedido _opcional_ —e todas essas informações são assinadas criptograficamente para garantir autenticidade e verificação. ## Estados da solicitação de pagamento As solicitações de pagamento passam por vários estados durante seu ciclo de vida: ### Estados principais | State | Description | Duration | | ---------------- | -------------------------------------------------------------------- | --------- | | **`pending`** | Criada via fluxo de checkout; o pagador ainda não selecionou um UAI | Até a seleção do UAI | | **`created`** | Endereço vault atribuído; aguardando pagamento on-chain | 8 minutos | | **`expired`** | Solicitação de pagamento expirou sem pagamento | Permanente | | **`processing`** | Depósito on-chain detectado; aguardando finalidade | Variável | | **`completed`** | Pagamento recebido integralmente (ou pagamento de valor aberto aceito) | Permanente | | **`confirmed`** | Transação de ledger criada após pagamento bem-sucedido | Permanente | ### Estados de casos extremos Esses estados tratam cenários especiais e exigem coordenação entre Fluxis e o comerciante: | State | Description | Handling | | --------------- | ---------------------------------------------------- | ------------------------------ | | **`underpaid`** | Pagamento recebido, mas valor menor que o solicitado | Coordenação com o comerciante necessária | | **`overpaid`** | Pagamento recebido, mas valor excede o solicitado | Coordenação com o comerciante necessária | | **`failed`** | Erro inesperado ocorreu durante o processamento | Coordenação com o comerciante necessária | ::::note Estados de casos extremos são tratados pela Fluxis usando configuração específica do comerciante. ::::: ### Padrão de integração recomendado 1. Consulte `GET /v1/pos/{posID}/payment-request/{paymentRequestID}` ou assine [webhooks em nível de conta](/pt/docs/developers/webhooks) para mudanças de status. 2. Trate `processing` como pagamento detectado; aguarde `completed`, `underpaid` ou `overpaid`. 3. `confirmed` indica que a plataforma criou a transação de ledger. ## Temporização e expiração ::::info **Período de timeout**: Solicitações de pagamento expiram **8 minutos** após a atribuição de um endereço vault (status `created`). **Período de graça**: Transações transmitidas perto da expiração ainda podem ser detectadas enquanto o vault permanece em cache brevemente após a expiração. ::::: ## Criar uma solicitação de pagamento ### Exemplo de solicitação básica ```json POST /v1/pos/{posID}/payment-request { "reference_id": "order-12345-FLX25", "amount": "49.99", "unique_asset_id": "npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "order": { "total": "49.99", "coin_code": "USD", "description": "Premium Subscription", "items": [ { "description": "Premium Subscription", "quantity": 1, "unit_price": "49.99", "amount": "49.99", "coin_code": "USD" } ] } } ``` ### Exemplo de resposta ```json { "status": "success", "data": { "id": "180ede28-2968-4ac7-8e81-ca446f201949", "reference_id": "order-12345-FLX25", "status": "created", "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...more-token...EwLTAy", "expiration": 1759397652 } } ``` ### Exemplo de resposta de checkout hospedado ```json { "status": "success", "data": { "id": "180ede28-2968-4ac7-8e81-ca446f201949", "reference_id": "order-12345-FLX25", "status": "pending", "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...", "checkout_url": "https://checkout.fluxis.us/pos/{posID}/payment/{paymentRequestID}", "expiration": null } } ``` ::::note Use `POST /v1/pos/{posID}/payment-request` quando o UAI do pagador é conhecido antecipadamente. Use `POST /v1/pos/{posID}/payment-request-checkout` quando o pagador deve escolher entre as `payment_options` do PoS. Ambos os endpoints exigem um Point of Sale `online_fixed`. ::::: ## Monitorar status do pagamento Comerciantes devem consultar regularmente o status da solicitação de pagamento para detectar pagamentos bem-sucedidos: ### Exemplo de verificação de status ```json GET /v1/pos/{posID}/payment-request/{paymentRequestID} { "status": "success", "data": { "id": "180ede28-2968-4ac7-8e81-ca446f201949", "reference_id": "order-12345-FLX25", "status": "completed", "expiration": 1759397652, "amount": "49.99", "expected_amount": "49.99", "address": "0x1234567890123456789012345678901234567890", "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "reference_asset_id": "USD", "reference_amount": "49.99", "exchange_rate": "1", "point_of_sale_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:33:15Z" } } ``` ## Suporte multiativo Comerciantes configuram múltiplos [UAIs](/pt/docs/key-concepts/uai) no **Point of Sale** (`config.payment_options`). Para permitir que pagadores escolham o ativo preferido, use o fluxo de checkout hospedado: ```json POST /v1/pos/{posID}/payment-request-checkout { "reference_id": "order-12345-FLX25", "amount": "49.99", "coin_code": "USD", "order": { "total": "49.99", "coin_code": "USD", "description": "Premium Subscription" } } ``` A resposta inclui um `checkout_url` e um token NASPIP com as `payment_options` disponíveis. O pagador seleciona um UAI no checkout; a Fluxis atribui um vault e transiciona a solicitação de pagamento de `pending` para `created`.