Docs
Acessar painel

Começar

Produção

Checklist para abrir o Pix da Koku aos seus compradores com segurança.

Antes de liberar o Pix no seu checkout, confira cada item abaixo.

Conta e contrato

  • Contrato com a Koku assinado e tarifas conferidas em Configurações no painel.
  • Usuários da equipe com verificação em duas etapas ativa e só com os papéis necessários.
  • Dados bancários para o repasse confirmados com a Koku.

Chaves de API

  • Chave de produção (koku_live_...) guardada em variável de ambiente ou cofre do servidor.
  • Escopos mínimos por sistema (checkout, financeiro). Veja Chaves de API.
  • Nenhuma chave no front-end, no aplicativo, no repositório ou em logs.
  • Procedimento de troca de chave combinado com a equipe.

Cobranças

  • order_reference único por pedido e Idempotency-Key estável por tentativa de pedido.
  • Repetição automática com a mesma Idempotency-Key em erro de rede, 503 ou 429 (exceto 503 com details.reason = "account_not_enabled", que não se resolve repetindo).
  • Os quatro dados do pagador enviados: nome, CPF/CNPJ, e-mail e telefone.
  • Valores em centavos, sem conversão por ponto flutuante.
  • Tratamento de status: "created" sem pix (consultar de novo, não recriar).
  • Tratamento de failed (mostrar failure_message, que é um texto fixo da Koku, e permitir nova tentativa com outro order_reference).
  • Validade (expires_in_seconds) adequada ao seu checkout e contador visível para o comprador.

Webhooks

  • Endpoint HTTPS público, com certificado válido, respondendo 2xx em menos de 5 segundos.
  • Assinatura conferida em toda entrega, com o corpo bruto e tolerância de tempo. Veja Verificar assinatura.
  • Processamento idempotente pelo id do evento (x-koku-event-id).
  • Pedido liberado só depois de consultar a cobrança e ver status: "paid".
  • Rotina que consulta Listar eventos para recuperar eventos perdidos.
  • Alerta interno quando Listar entregas mostrar falhas seguidas.

Operação