Docs
Acessar painel

Começar

Como funciona

O caminho de uma venda Pix, do checkout ao repasse, e o papel de cada parte.

A Koku processa o Pix das suas vendas. O seu checkout fala só com a API da Koku; a Koku emite o Pix na rede de processamento, confirma o pagamento, registra cada centavo no seu saldo e faz o repasse para a sua conta conforme o contrato.

O fluxo de uma venda

  1. CheckoutO comprador fecha o pedido no seu site ou aplicativo.
  2. API KokuSeu servidor cria a cobrança com POST /v1/pix/charges.
  3. PixA Koku devolve o QR Code e o copia e cola; você mostra ao comprador.
  4. ConfirmaçãoO comprador paga; a Koku confirma o pagamento na rede de processamento.
  5. WebhookA Koku envia charge.paid ao seu endpoint; você libera o pedido.
  6. Saldo e repasseO líquido entra no seu saldo e a Koku faz o repasse conforme o contrato.

Passo a passo

  1. Seu servidor cria a cobrança. Envie valor, identificador do pedido (order_reference) e os dados do pagador. A chamada sai do seu servidor, nunca do navegador. Veja Criar cobrança.
  2. Você mostra o Pix. A resposta traz pix.qr_code_payload (o copia e cola) e a validade. Gere a imagem do QR Code a partir dele. Veja QR Code e copia e cola.
  3. O comprador paga. Enquanto o QR está válido, a cobrança fica pending. Se a validade acabar sem pagamento, ela vira expired. Veja Expiração.
  4. A Koku confirma e avisa. Com o pagamento confirmado, a cobrança vira paid e a Koku envia o evento charge.paid, com bruto, tarifa e líquido. Veja Webhooks.
  5. Você confirma e libera o pedido. Confira a assinatura do webhook e, por segurança, consulte a cobrança antes de liberar. Veja Consultar cobrança.
  6. O valor entra no saldo. O líquido aparece como pendente e, depois de liquidado e conciliado, como disponível. Veja Saldo e extrato.
  7. A Koku repassa. Os repasses para a sua conta são feitos pela Koku conforme o contrato; cada repasse aparece na API. Veja Saldo e extrato.

Quem faz o quê

ParteResponsabilidade
Seu checkout (front-end)Mostra o QR Code e o copia e cola; acompanha o estado pelo seu servidor. Nunca chama a API da Koku diretamente.
Seu servidor (back-end)Guarda a chave de API, cria cobranças, recebe webhooks, consulta a cobrança antes de liberar o pedido.
KokuEmite o Pix, confirma o pagamento, calcula tarifa e líquido, mantém o saldo e o extrato, envia os webhooks e faz os repasses.
CompradorPaga pelo aplicativo do banco, lendo o QR Code ou colando o código.

Dinheiro em centavos

Todos os valores da API são inteiros em centavos. Na entrada você pode mandar número ou string (15990 ou "15990"); na saída a Koku devolve sempre string decimal ("15990" = R$ 159,90), para não haver perda de precisão em nenhuma linguagem.

Pago, liquidado e disponível

Uma venda paga não fica disponível no mesmo instante. A Koku separa:

  • Pago (paid): o comprador pagou e a Koku confirmou.
  • Pendente (pending_cents no saldo): o líquido da venda paga, ainda não liquidado e conciliado.
  • Disponível (available_cents): valor liquidado e conciliado, pronto para o repasse.

O evento balance.available avisa quando um valor fica disponível. Os prazos dependem do seu contrato.