Skip to main content
Não existe sandbox na WyzeCash: a chave que você testa é a mesma que vai para produção, e todo Pix é real. Por isso vale conferir esta lista antes de abrir para os seus clientes.

​
Chave de API

  • A chave está num cofre de segredos ou variável de ambiente do servidor, nunca no código, no front-end ou num app.
  • Só os escopos que o sistema usa. Chave que só cria cobrança não precisa de withdrawals:write; quem só cobra no Pix não precisa de card:write nem de crypto:write.
  • IPs liberados preenchidos (obrigatório para sacar e enviar Pix; recomendado para todas).
  • Uma chave por sistema, para revogar uma sem parar as outras.

​
Cobranças

  • Idempotency-Key com o número do seu pedido (ou um UUID guardado junto dele). Repetir a chamada depois de um timeout não pode criar outra cobrança.
  • Valores em centavos inteiros. Nunca float.
  • O copyPaste é mostrado como QR Code e como texto com botão “Copiar”.
  • A tela de “aguardando pagamento” consulta GET /v1/payments/{id} a cada 2 segundos ou mais, ou espera o webhook.
  • Cobrança paga depois de expirar é tratada como paga (payment.paid depois de payment.expired).

​
Webhooks

  • O servidor lê o corpo cru e valida o X-Bukio-Signature antes de qualquer coisa.
  • Guarda o id do evento (evt_...) e ignora repetidos (o mesmo evento vai para todas as URLs e volta em todo reenvio).
  • Responde 2xx em menos de 10 segundos e faz o trabalho pesado depois.
  • Trata pelo type e pelo data.id, nunca pela ordem de chegada.
  • O relógio do servidor está sincronizado (NTP): a assinatura recusa diferença maior que 5 minutos.
  • A URL é https:// num domínio público; o segredo da conta está no servidor.
  • O envio de teste pelo painel chegou e foi validado.

​
Erros e limites

  • O código trata pelo error.code, não pelo texto da message.
  • 429 RATE_LIMITED e 5xx têm nova tentativa com espera crescente; 4xx não repete sem mudar algo.
  • O requestId da resposta fica no seu log, para citar ao suporte.

​
Saques

  • O 2FA da conta está ligado e o sistema manda a chave de destino em destination (confira a chave antes: o Pix não volta).
  • Com subcontas, o seu sistema sabe que o saldo delas não sai no seu saque (free em GET /v1/balance).
  • O sistema espera withdrawal.completed (ou pix.sent) antes de considerar o dinheiro entregue: a resposta da criação é processing.
  • O valor mínimo do saque está previsto (withdrawal.minPerTransaction em GET /v1/balance).

​
Primeiro teste real

Uma cobrança de valor pequeno paga com o seu próprio banco, o webhook payment.paid recebido e validado, a cobrança consultada em GET /v1/payments/{id} e, se for usar, um saque pequeno concluído. Só depois abra para os clientes.