Antes de ir para produção

Como não existe sandbox, a sua primeira cobrança real já é produção. Esta lista reúne o que costuma quebrar no primeiro dia. Revise item por item.

​

Chaves e segredos

• A API Key está em variável de ambiente ou num gerenciador de segredos, nunca no código nem em repositório.
• A chave nunca vai para frontend, app mobile, URL ou log.
• Cada serviço tem a sua chave, com só as permissões de que precisa (payments:write, transactions:read, balance:read, transfers:write).
• transfers:write está numa chave isolada, usada só pelo serviço de saques.
• Você sabe rotacionar sem derrubar a integração: criar a segunda chave, trocar, depois revogar a antiga.
• O segredo de assinatura do webhook também está no cofre.
• Uma chave usada só nos testes foi revogada.

​

Idempotência

• Toda criação de cobrança e transferência envia Idempotency-Key ou externalId.
• A chave vem do identificador do negócio mais a tentativa (PEDIDO-1042-t1), não de um UUID novo a cada requisição.
• A chave é gravada no seu banco antes de chamar a API.
• Em timeout, erro de rede ou 5xx, o retry usa exatamente a mesma chave e o mesmo corpo.
• Para refazer uma cobrança depois que ela terminou (expirada, falha), você usa uma chave nova.
• O tratamento de 409 idempotency_conflict consulta a operação original, em vez de trocar a chave.

​

Webhook

• A URL é HTTPS, na porta 443, sem redirecionamento e acessível publicamente.
• O receptor valida X-NyxPag-Signature com o segredo do webhook, em tempo constante.
• A validação usa o corpo bruto, sem parse e reserialização.
• O timestamp t é checado numa janela (por exemplo, 5 minutos).
• O evento é gravado de forma durável antes de responder 2xx.
• O processamento pesado roda depois, fora do request. A resposta sai em poucos segundos (o limite da NyxPag é 8).
• A deduplicação usa o id do evento em transaction.* e o X-NyxPag-Delivery em med.*.
• Há testes: assinatura inválida, corpo alterado, timestamp velho, evento repetido. Veja Ambientes.
• O receptor lida com eventos fora de ordem.

​

Estados e valores

• Um pedido só é liberado com status: "approved", nunca por 201 ou 202.
• 202 é tratado como “pendente”, e a decisão final vem do webhook ou da consulta.
• 200 e 201 são tratados como sucesso.
• Uma cobrança expirada (cancelled com expired: true) gera um novo Pix com chave nova, em vez de travar o pedido.
• O Pix mostra o valor que o pagador paga (amount da resposta), e o seu pedido guarda o valor original.
• O valor é lido como reais decimais, nunca como centavos.
• Só há um saque pending por vez na conta: o seu serviço de saques enfileira (WITHDRAWAL_IN_PROGRESS).
• O CPF do pagador é validado no seu lado antes de enviar.

​

Erros e limites

• A decisão usa error.code, não o texto de error.message.
• 400, 401, 403, 404 e 422 não são repetidos às cegas.
• No 429, o cliente espera o Retry-After e adiciona jitter.
• O número de tentativas tem teto (por exemplo, 5).
• O cliente lê RateLimit-Remaining e desacelera antes do limite.
• Nenhum fluxo usa refresh=true em polling. A cota é de 100 requisições por 60 segundos por chave.

​

Reconciliação

• Um job periódico percorre GET /transactions e compara com o seu sistema.
• Ele cobre webhook perdido, já que após 8 tentativas a NyxPag desiste.
• Ele cobre estados sem webhook, como refunded.
• Há um job para GET /meds?status=pending se você acompanha contestações.
• Divergências geram alerta, não correção silenciosa.

​

Observabilidade e dados pessoais

• Todo requestId é registrado, em sucesso e erro.
• A API Key e o segredo do webhook nunca aparecem em log, nem mascarados.
• CPF, e-mail e o Copia e Cola do pagador são removidos ou anonimizados antes de ir para log.
• Falha de webhook, timeout e 5xx geram alerta com contexto suficiente.

​

Quando pedir ajuda

Escreva para [email protected] com:

• o requestId da resposta;
• o horário exato, com fuso;
• o endpoint e o método;
• o que você esperava e o que aconteceu.

Quanto mais preciso, mais rápido o diagnóstico.