Copy page

Conceitos-chave

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

Padrão de integração recomendado

1. Consulte GET /v1/pos/{posID}/payment-request/{paymentRequestID} ou assine webhooks em nível de conta 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

Criar uma solicitação de pagamento

Exemplo de solicitação básica

Code
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

Code
{
    "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

Code
{
  "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
  }
}

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

Code
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 no Point of Sale (config.payment_options). Para permitir que pagadores escolham o ativo preferido, use o fluxo de checkout hospedado:

Code
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.