Docs
Acessar painel

Pix

Consultar cobrança

Como consultar o estado de uma cobrança e confirmar um pagamento.

GET /v1/pix/charges/{id} devolve a cobrança com o estado atual. Escopo: charges:read. Referência: Consultar cobrança.

GET/v1/pix/charges/{id}
curl -X GET 'https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47' \
  -H "Authorization: Bearer $KOKU_API_KEY"
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
}

Confirmar um pagamento

O webhook avisa; a consulta confirma. Antes de liberar um pedido, consulte a cobrança e confira:

  • status é paid (ou partially_refunded/refunded, se já houve devolução);
  • amount_cents é o valor do pedido;
  • order_reference é o pedido que você vai liberar.
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": "paid",
  "fee_percent_bps": 200,
  "fee_fixed_cents": "0",
  "fee_cents": "320",
  "net_cents": "15670",
  "reserve_cents": "0",
  "refunded_cents": "0",
  "expires_at": "2026-10-07T16:00:00.000Z",
  "paid_at": "2026-10-07T15:32:10.000Z",
  "late_payment": false,
  "is_simulated": false,
  "created_at": "2026-10-07T15:30:00.000Z",
  "updated_at": "2026-10-07T15:32:11.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": "E12345678202610071532a1B2c3D4e5F",
  "payments_count": 1,
  "failure_message": null
}

Quando paga, a cobrança traz também paid_at, end_to_end_id (o identificador do Pix no Banco Central), fee_cents (tarifa da Koku) e net_cents (o que entra no seu saldo).

Quando consultar

  • Depois de receber um webhook, para confirmar.
  • Quando a criação respondeu status: "created" sem pix: consulte a cada poucos segundos até pending ou failed.
  • Quando o seu endpoint ficou fora do ar: recupere o estado das cobranças em aberto (ou use Listar eventos).

Evite consultar em laço apertado: um intervalo de alguns segundos basta, e o webhook chega antes na maioria dos casos. Veja Limites de requisição.

Cobrança inexistente

Uma cobrança de outra conta ou de outro ambiente responde 404, exatamente como uma que não existe:

404Resposta
{
  "error": {
    "code": "not_found",
    "message": "Cobrança não encontrada.",
    "details": {},
    "correlation_id": "2f7a9c41-0e8b-4d63-b5c2-9a1e6d3f8b07"
  }
}