Perguntas frequentes

#Integração

#Posso chamar a API direto do navegador ou do aplicativo?

Não. A chave de API é um segredo do seu servidor. O seu checkout conversa com o seu servidor, e o seu servidor conversa com a Koku. Veja Chaves de API.

#Quais métodos de pagamento a API aceita?

Hoje, só Pix.

#Existe ambiente de testes?

Está em preparação, sem data definida. Veja Ambientes.

#Preciso de biblioteca (SDK)?

Não. A API é HTTP com JSON; os exemplos em cURL, Node.js, Python e PHP mostram as chamadas completas. A especificação OpenAPI está em /openapi.json.

#Por que os valores vêm como texto?

Para não haver perda de precisão em nenhuma linguagem. Todos os valores são centavos inteiros: "15990" = R$ 159,90.

#Cobranças

#Por que preciso mandar e-mail e telefone do pagador?

A emissão do Pix exige nome, CPF ou CNPJ, e-mail e telefone do comprador. Sem eles a cobrança pode ser recusada. A Koku usa e-mail e telefone só para emitir o Pix e não os grava.

#A criação respondeu created sem QR. E agora?

A emissão ainda está em andamento. Consulte a cobrança em alguns segundos ou aguarde charge.pending. Não crie outra cobrança para o mesmo pedido.

#Minha chamada deu tempo esgotado. Criou ou não?

Repita a mesma chamada com a mesma Idempotency-Key: se a cobrança já existia, você recebe a mesma (200 com Idempotent-Replayed: true). Veja Idempotência.

#O QR expirou. Posso reativar?

Não. Crie uma nova cobrança com outro order_reference. Veja Expiração.

#O comprador pagou duas vezes. O que acontece?

O segundo pagamento fica retido e é devolvido ao pagador. Você recebe charge.duplicate_payment. Veja Estados da cobrança.

#Webhooks

#Recebi o mesmo evento duas vezes.

É esperado em reenvios. Use o id do evento para processar uma vez só. Veja Reenvios e boas práticas.

#Meu servidor ficou fora do ar. Perdi eventos?

Não. A Koku tenta de novo e todos os eventos ficam em Listar eventos.

#Posso confiar só no webhook para liberar o pedido?

Confira a assinatura e confirme consultando a cobrança antes de liberar. Veja Consultar cobrança.

#Saldo e repasses

#Quando o dinheiro fica disponível?

Depois que a venda é liquidada e conciliada, conforme o seu contrato. O evento balance.available avisa. Veja Saldo e extrato.

#Como peço um saque?

Não é preciso: os repasses são feitos pela Koku conforme o contrato, e cada um aparece em Listar repasses.

#Quanto é a tarifa?

A do seu contrato. Cada venda mostra bruto, tarifa e líquido. Veja Tarifas.