Docs
Acessar painel

Pix

Expiração

Validade do QR Code, o que acontece quando ele expira e como gerar outro.

Toda cobrança Pix tem prazo. Você define a validade na criação com expires_in_seconds:

ValorValidade
Mínimo60 segundos
Padrão (campo omitido)3600 segundos (1 hora)
Máximo604800 segundos (7 dias)

A resposta traz o fim da validade em expires_at e em pix.expires_at.

Quando expira

Ao fim da validade sem pagamento, a cobrança vira expired e a Koku envia charge.expired:

Payload de charge.expired
{
  "id": "evt_3b9d5f1a7c2e4b6d8f0a2c4e6b8d1f37",
  "type": "charge.expired",
  "version": "v1",
  "created_at": "2026-10-07T16:00:05.000Z",
  "environment": "production",
  "data": {
    "charge_id": "b2e7c4d1-9a36-4f58-8c0e-1d5a7f3b6e92",
    "order_reference": "PEDIDO-1002",
    "status": "expired"
  }
}
200Resposta
{
  "id": "b2e7c4d1-9a36-4f58-8c0e-1d5a7f3b6e92",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "order_reference": "PEDIDO-1002",
  "amount_cents": "15990",
  "currency": "BRL",
  "description": "Pedido 1002 - Loja Exemplo",
  "status": "expired",
  "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-07T16:00:05.000Z",
  "pix": {
    "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/b2e7c4d19a364f588c0e1d5a7f3b6e925204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
    "txid": "b2e7c4d19a364f588c0e1d5a7f3b6e92",
    "expires_at": "2026-10-07T16:00:00.000Z"
  },
  "end_to_end_id": null,
  "payments_count": 0,
  "failure_message": null
}

Gerar outro QR

Uma cobrança expirada não é reaproveitada. Para o comprador tentar de novo, crie uma nova cobrança com outro order_reference (por exemplo, PEDIDO-1002-2) e outra Idempotency-Key.

Escolhendo a validade

  • Checkout com o comprador na tela: de 15 a 30 minutos costuma bastar.
  • Pedido enviado por e-mail ou mensagem: algumas horas ou 1 dia.
  • Mostre um contador com o tempo restante e avise quando faltar pouco.