Docs
Acessar painel

Pix

QR Code e copia e cola

Como exibir o Pix ao comprador a partir do código devolvido pela API.

A cobrança devolve o Pix pronto para exibição em pix:

CampoUso
pix.qr_code_payloadCódigo Pix copia e cola (BR Code). É o texto que vira o QR Code e que o comprador cola no aplicativo do banco.
pix.txidIdentificador da transação Pix. Útil no atendimento.
pix.expires_atFim da validade deste QR.
200Resposta
{
  "id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "order_reference": "PEDIDO-1001",
  "amount_cents": "15990",
  "currency": "BRL",
  "description": "Pedido 1001 - Loja Exemplo",
  "status": "pending",
  "fee_percent_bps": 200,
  "fee_fixed_cents": "0",
  "fee_cents": null,
  "net_cents": null,
  "reserve_cents": null,
  "refunded_cents": "0",
  "expires_at": "2026-10-07T16:00:00.000Z",
  "paid_at": null,
  "late_payment": false,
  "is_simulated": false,
  "created_at": "2026-10-07T15:30:00.000Z",
  "updated_at": "2026-10-07T15:30:01.000Z",
  "pix": {
    "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/8d3f6a124b9e4c71a2d56e0f1b3c9a475204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
    "txid": "8d3f6a124b9e4c71a2d56e0f1b3c9a47",
    "expires_at": "2026-10-07T16:00:00.000Z"
  },
  "end_to_end_id": null,
  "payments_count": 0,
  "failure_message": null
}

Exibindo no checkout

  • QR Code: gere a imagem a partir de pix.qr_code_payload com uma biblioteca de QR Code do seu front-end (por exemplo, qrcode no JavaScript). A API não devolve imagem: assim você controla tamanho, cor e cache.
  • Copia e cola: mostre o mesmo texto com um botão "Copiar código Pix". No celular, é o caminho mais usado.
  • Validade: mostre um contador até pix.expires_at.
  • Estado: atualize a tela pelo seu servidor (que recebe o webhook), não consultando a Koku a partir do navegador.

Quando pix vem null

EstadoMotivoO que fazer
createdA emissão ainda não terminou.Consulte a cobrança em alguns segundos; o evento charge.pending também avisa quando o QR estiver pronto.
failedA emissão foi recusada.Mostre failure_message (texto fixo da Koku) e tente de novo com outro order_reference.