Consultar cobrança · Documentação Koku

GEThttps://api.kokupay.com/v1/pix/charges/{id}

Devolve a cobrança com o estado atual, o QR vigente e, quando paga, a tarifa e o valor líquido. Use esta consulta para confirmar um pagamento recebido por webhook.

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"

const response = await fetch('https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
    headers={
        "Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

Respostas

200 · Consultar cobrança

{
  "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
}

200 · Cobrança paga

{
  "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
}

200 · Cobrança expirada

{
  "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
}

404 · Cobrança inexistente

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

Autenticação

Authorization: Bearer <sua chave de API>

Escopo exigido: charges:read. Veja Chaves de API.

Parâmetros de caminho

idstring (uuid)obrigatório

Identificador da cobrança.

Resposta 200

idstring (uuid)

Identificador da cobrança na Koku.

gateway_idstring (uuid)

Identificador da sua conta na Koku.

environmentstring

Ambiente da cobrança: production (sandbox está reservado para o ambiente de testes, em preparação).

Valores: sandbox, production

order_referencestring

Identificador do pedido enviado por você.

amount_centsstring (centavos)

Valor bruto da cobrança, em centavos (string decimal: "15990" = R$ 159,90).

currencystring

Moeda (BRL).

Valores: BRL

descriptionstring ou null

Descrição enviada na criação.

statusstring

Estado da cobrança. Veja Estados da cobrança.

Valores: created, pending, paid, partially_refunded, refunded, expired, cancelled, failed

fee_percent_bpsinteiro

Parte percentual da tarifa vigente na criação, em pontos-base (200 = 2,00%).

fee_fixed_centsstring (centavos)

Parte fixa da tarifa por transação, em centavos.

fee_centsstring (centavos) ou null

Tarifa da Koku sobre a venda, em centavos. null até o pagamento.

net_centsstring (centavos) ou null

Valor líquido da venda (bruto − tarifa), em centavos. null até o pagamento.

reserve_centsstring (centavos) ou null

Parte do líquido retida como reserva contratual, em centavos. null até o pagamento.

refunded_centsstring (centavos)

Total já devolvido ao pagador, em centavos.

expires_atstring (data e hora) ou null

Fim da validade do QR.

paid_atstring (data e hora) ou null

Momento do pagamento confirmado.

late_paymentbooleano

true quando o pagamento chegou depois da expiração (pagamento tardio).

is_simulatedbooleano

false em produção. true fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real.

created_atstring (data e hora)

Criação da cobrança.

updated_atstring (data e hora)

Última alteração.

pixobjeto ou null

QR vigente. null enquanto a emissão não terminou ou quando a cobrança foi recusada.

pix.qr_code_payloadstring ou null

Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele.

pix.txidstring ou null

Identificador da transação Pix.

pix.expires_atstring (data e hora) ou null

Fim da validade deste QR.

end_to_end_idstring ou null

Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga.

payments_countinteiro

Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados).

failure_messagestring ou null

Quando status é failed: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: Emissão recusada pela análise de risco.). Os textos possíveis estão em Estados da cobrança. null nos demais estados.

Erros

Status	Código	Quando
401	`unauthorized`	Chave ausente, inválida, revogada ou expirada.
403	`forbidden`	A chave não tem o escopo exigido (`details.reason = "missing_scope"`).
404	`not_found`	Cobrança inexistente ou de outra conta.
429	`rate_limited`	Limite de requisições excedido. Aguarde o tempo de `Retry-After`.
500	`internal_error`	Falha inesperada. Repita com a mesma `Idempotency-Key`; persistindo, envie o `correlation_id` à Koku (veja Suporte).

Formato do corpo de erro em Erros.

#Autenticação

#Parâmetros de caminho

#Resposta 200

#Erros

Autenticação

Parâmetros de caminho

Resposta 200

Erros