Guia de integração Neozentry QA

Bem-vindo. Este guia é tudo que você precisa para receber pagamentos pela Neozentry QA — da primeira chamada de API até os webhooks assinados chegando em produção.

#O que a Neozentry QA resolve

A Neozentry QA é um gateway de pagamentos Pix-first. Você cria uma Cobrança (charge) por uma única API canônica e nós roteamos para o PSP/adquirente certo por trás; a resposta já traz o BR Code e o QR Code prontos para renderizar no seu checkout. Cartão, MB WAY e Multibanco existem na mesma conta quando habilitados, mas o Pix é o ponto de partida de toda integração nova.

Sua aplicação nunca fala com o PSP direto, nunca guarda dado de cartão e nunca precisa mudar quando trocamos ou adicionamos um provedor — o campo provider e qualquer identificador de PSP são removidos pelo serializador antes da resposta chegar até você.

┌────────────┐               ┌──────────┐                ┌─────────────┐
│            │ POST /charges │          │  roteamento    │  PSP/       │
│  Seu app   ├──────────────▶│  Neozentry QA   ├───────────────▶│  adquirente │
│            │◀──────────────┤          │◀───────────────┤  (interno)  │
└──────┬─────┘  BR Code / QR └────┬─────┘   status       └─────────────┘
       │                          │
       │   webhook assinado       │
       │◀─────────────────────────┘
       │      charge.paid
       ▼
  Pedido liberado

#Meios de pagamento

O Pix é o trilho principal para lojista brasileiro e o fluxo por onde toda integração nova deve começar.

A disponibilidade é POR CONTA. Os meios acima são habilitados individualmente para a sua conta — um meio para o qual você não foi habilitado é recusado na criação da cobrança, não no checkout. Confirme com seu contato na Neozentry QA quais trilhos estão ativos antes de construir em cima de um deles.

#Leia nesta ordem

1. Primeiros passos — autenticação, ambientes, convenções e sua primeira chamada
2. Pix — o fluxo Pix de ponta a ponta, com código
3. Webhooks — registrar endpoints, verificar assinatura, lidar com retentativa
4. Erros — formato do erro, mapa de status e estratégia de retry
5. Referência da API — cada endpoint, cada campo, cada status

Com o Pix funcionando de ponta a ponta e com webhook, os outros meios são variações pequenas do mesmo fluxo:

• Cartão
• MB WAY
• Multibanco

Receber é metade do sistema. A outra metade é tirar o dinheiro:

• Saques — Pix out, TED (Saque)
• Falhas de saque — o contrato da recusa: INSUFFICIENT_BALANCE, códigos do provedor e a janela de 24h
• Disputas e MED — contestação Pix (MED do BACEN): retenção, painel de disputas, contestação e desfechos

Operando sua conta:

• Chaves de API — emitir, listar, girar e revogar chaves pelo painel ou pela API
• SDKs oficiais — Node.js, Python e .NET

#O contrato que você usa

Este guia documenta o contrato público v1 da Neozentry QA: o cabeçalho apikey com chaves qa_test_* / qa_live_*, POST /v1/charges devolvendo um id ch_…, e os cabeçalhos X-QA-* nos webhooks. É essa a superfície — não existe nada mais antigo que você precise conhecer.

Vale notar dois caminhos de recurso: saque fica em /v1/withdrawals e o saldo em /v1/wallets. Se um apelido canônico /v1/payouts entrar mais tarde, o caminho atual continua funcionando e passa a mandar cabeçalhos Deprecation / Sunset bem antes de qualquer remoção.

#Em breve

• Ambiente sandbox — ambiente de teste isolado, com resultado determinístico (forçar PAID / REFUSED / EXPIRED) e simulador de webhook. (Planejado — o documento descreve o escopo proposto, não algo que já dá para usar.)

#Precisa de ajuda?

Escreva para qa@liqfy.com.br com o seu request_id — todo erro da API traz um, e ele localiza a requisição exata no nosso log.