> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyxpag.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Perguntas frequentes

> Respostas rápidas sobre sandbox, idempotência, webhooks, limites, cobrança, transferência, split, MED e o ciclo de vida das transações na NyxPag API.

Cada resposta é independente: vá direto ao que precisa.

## Começando

<AccordionGroup>
  <Accordion title="Existe sandbox ou ambiente de teste?">
    Não. A NyxPag tem um único ambiente, o de produção, e toda API Key opera nele. Para testar, use valores baixos (a partir de R\$ 1,00) e pague pelo seu banco. Dá para testar o seu receptor de webhook sem gastar nada, assinando um evento localmente. Veja [Ambientes](/guides/comece-aqui/ambientes).
  </Accordion>

  <Accordion title="Onde crio a API Key?">
    Em [Dashboard → Chaves de API](https://nyxpag.com.br/dashboard/credentials). A conta precisa ter a verificação de identidade concluída para usar a API. A chave aparece uma única vez. Veja [Gestão de chaves](/guides/comece-aqui/api-key).
  </Accordion>

  <Accordion title="Posso chamar a API direto do frontend ou do app?">
    Não. A chave movimenta dinheiro e não pode sair do servidor. Faça o seu frontend chamar o **seu** backend, e o backend chamar a NyxPag. A única exceção é `GET /transparency`, que é público.
  </Accordion>

  <Accordion title="Existe SDK?">
    Não existe SDK oficial. A API é REST sobre JSON, e qualquer linguagem com cliente HTTP integra. A documentação traz exemplos em cURL, JavaScript, Python e PHP, e a especificação OpenAPI 3.1 em `https://api.nyxpag.com.br/v1/openapi.json` permite gerar um cliente.
  </Accordion>

  <Accordion title="Qual moeda a API usa?">
    Somente **BRL**. Os valores são reais decimais: `10.50` é R\$ 10,50.
  </Accordion>
</AccordionGroup>

## Cobranças

<AccordionGroup>
  <Accordion title="Por quanto tempo vale o QR Code?">
    **15 minutos** a partir da criação. O prazo está em `expiresAt`. Se ninguém pagar, a cobrança vira `cancelled` com `expired: true` e o webhook `transaction.cancelled` é enviado.
  </Accordion>

  <Accordion title="Posso cobrar de uma empresa (CNPJ)?">
    O campo `payer.document` valida **CPF**. Para uma venda a uma empresa, informe o CPF do responsável pelo pagamento.
  </Accordion>

  <Accordion title="Como cancelo uma cobrança pendente?">
    Não há endpoint de cancelamento. A cobrança expira sozinha em 15 minutos. Enquanto isso, ela continua válida: se o cliente pagar, o valor entra.
  </Accordion>

  <Accordion title="Dá para reembolsar um pagamento pela API?">
    Não. A API pública não tem endpoint de reembolso. O estado `refunded` existe, mas não é acionado por uma chamada sua e não dispara webhook.
  </Accordion>

  <Accordion title="A API aceita cartão, boleto ou parcelamento?">
    Não. A API pública da NyxPag cobre **Pix**: cobrança, transferência, consulta, saldo e MED.
  </Accordion>

  <Accordion title="O que significa o valor amount da resposta?">
    Numa cobrança, é o valor que o **pagador paga**. Com `coverFee: false` é igual ao que você enviou. Com `coverFee: true` é maior, porque inclui a tarifa. Veja [Receber por Pix](/guides/pix/receber).
  </Accordion>

  <Accordion title="Qual é a tarifa?">
    Depende da configuração da sua conta e vem sempre no campo `fee` da resposta. Os valores que aparecem na documentação são exemplos.
  </Accordion>

  <Accordion title="Como divido o valor entre contas?">
    Com o campo `split` na criação da cobrança, por valor fixo ou por percentual, para até 10 contas NyxPag. Veja [Split](/guides/pix/split).
  </Accordion>
</AccordionGroup>

## Idempotência e respostas

<AccordionGroup>
  <Accordion title="Qual a diferença entre Idempotency-Key e externalId?">
    Nenhuma na prática: são duas formas de mandar a mesma chave, e o valor vira o `externalId` da transação. Use o cabeçalho ou o campo. Se mandar os dois, os valores precisam ser iguais, senão é `409`. Veja [Idempotência](/guides/idempotencia).
  </Accordion>

  <Accordion title="O que faço quando recebo 202?">
    Trate como **pendente**. A operação foi recebida e está em reconciliação automática. Aguarde o webhook com o resultado, ou consulte `GET /transactions/{id}`. Nunca libere o pedido por causa de um `202`.
  </Accordion>

  <Accordion title="Como diferencio 200 de 201?">
    `201` criou agora. `200` é uma repetição idempotente: a operação já existia. Os dois trazem os dados da operação, e `idempotent: true` indica a repetição.
  </Accordion>

  <Accordion title="Reenviei a mesma chave depois que a cobrança expirou e veio a antiga. Por quê?">
    A chave não expira e continua apontando para a operação original. Para gerar um novo Pix para o mesmo pedido, use uma chave nova, como `PEDIDO-1042-t2`. Veja [Idempotência](/guides/idempotencia).
  </Accordion>
</AccordionGroup>

## Transferências

<AccordionGroup>
  <Accordion title="Qual o valor mínimo de uma transferência?">
    R\$ 3,00, conforme a especificação OpenAPI atual.
  </Accordion>

  <Accordion title="Posso enviar várias transferências ao mesmo tempo?">
    Não. Só pode haver **uma** transferência `pending` por conta. A seguinte recebe `409` (`WITHDRAWAL_IN_PROGRESS`) até a anterior terminar. Enfileire do seu lado. Veja [Transferir por Pix](/guides/pix/transferir).
  </Accordion>

  <Accordion title="Preciso enviar amount ao transferir por Copia e Cola?">
    Só se o código for **estático e sem valor**. Se o código já define o valor, omita `amount`: o valor do código prevalece.
  </Accordion>

  <Accordion title="Posso escolher a processadora?">
    Não. A NyxPag escolhe a rota de processamento da conta. O cliente da API não escolhe nem troca.
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="Como testo um webhook localmente?">
    `localhost` é recusado, então use um túnel HTTPS (ngrok, cloudflared) e cadastre a URL gerada. Para testar sem pagar nada, assine um evento com um segredo seu e envie para o seu servidor. Veja [Ambientes](/guides/comece-aqui/ambientes).
  </Accordion>

  <Accordion title="Qual é a chave da assinatura?">
    O **segredo de assinatura do webhook**, mostrado uma única vez ao criar o endpoint em [Dashboard → Webhooks](https://nyxpag.com.br/dashboard/webhooks). Veja [Validando a assinatura](/webhooks/assinatura).
  </Accordion>

  <Accordion title="Quantas vezes a NyxPag tenta entregar?">
    Até **8 tentativas**, com espera crescente a partir de cerca de 30 segundos e teto de 1 hora. Depois disso a entrega é marcada como falha e não é repetida. Concilie por `GET /transactions`. Veja [Webhooks](/guides/webhooks).
  </Accordion>

  <Accordion title="Recebi o mesmo evento duas vezes. É um erro?">
    Não: a entrega é **ao menos uma vez**. Deduplique pelo `id` do evento (`transaction.*`) ou pelo cabeçalho `X-NyxPag-Delivery` (`med.*`).
  </Accordion>
</AccordionGroup>

## Limites e MED

<AccordionGroup>
  <Accordion title="Qual o limite de requisições?">
    100 por janela de 60 segundos, por API Key, somando todas as rotas e o MCP. Os cabeçalhos `RateLimit-*` mostram o estado, e `Retry-After` diz quanto esperar no `429`. Veja [Limites](/guides/confiabilidade/limites).
  </Accordion>

  <Accordion title="O que é o MED?">
    É a contestação de um Pix pelo pagador. Enquanto ela é analisada, o valor fica retido. Na API é somente leitura. Veja [Contestações (MED)](/guides/disputas/med).
  </Accordion>

  <Accordion title="Posso consultar meus dados por um assistente de IA?">
    Sim, pelo [servidor MCP](/guides/mcp), que é somente leitura: saldo e transações, sem CPF, e-mail ou Copia e Cola.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/guides/ajuda/troubleshooting">
    Sintomas comuns e como resolver.
  </Card>

  <Card title="Glossário" icon="book-open" href="/guides/ajuda/glossario">
    Os termos da API explicados.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.