Devoluções e contestações da cobrança

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

Lista os casos ligados a uma cobrança: devoluções pedidas por você, contestações Pix (MED) e pagamentos retidos para devolução (duplicados ou tardios).

GET/v1/pix/charges/{id}/cases

curl -X GET 'https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47/cases' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47/cases', {
  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/cases",
    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/cases');
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);

200Resposta

{
  "items": [
    {
      "id": "3c7e1b95-6d2a-4f80-9e4b-a1d5c8f20e63",
      "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
      "environment": "production",
      "case_type": "refund",
      "status": "resolved",
      "med_stage": null,
      "charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
      "amount_cents": "5000",
      "held_cents": "0",
      "shortfall_cents": "0",
      "origin": "gateway",
      "reason": "Cliente devolveu um item",
      "liability": "gateway",
      "execution_status": "completed",
      "resolution": "refunded",
      "resolution_note": null,
      "resolved_amount_cents": "5000",
      "opened_at": "2026-10-08T12:00:00.000Z",
      "due_at": null,
      "resolved_at": "2026-10-08T12:00:04.000Z"
    }
  ]
}

Autenticação

Authorization: Bearer <sua chave de API>

Escopos exigidos: charges:read e statement:read. Veja Chaves de API.

Parâmetros de caminho

idstring (uuid)obrigatório

Identificador da cobrança.

Resposta 200

itemslista de objetos

Itens da página.

items[].idstring (uuid)

Identificador do caso.

items[].gateway_idstring (uuid)

Identificador da sua conta na Koku.

items[].environmentstring

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

Valores: sandbox, production

items[].case_typestring

Tipo: refund (devolução), med (contestação Pix pelo Mecanismo Especial de Devolução), precautionary_block (bloqueio preventivo) ou outro tipo operacional (contractual_retention, compensation, dispute, accounting_adjustment).

items[].statusstring

Situação do caso: open, in_review, awaiting_partner (aguardando a rede de processamento), resolved ou cancelled.

items[].med_stagestring ou null

Etapa da contestação MED (notified, confirmed, returned, net_loss, dismissed); null nos demais tipos.

items[].charge_idstring (uuid) ou null

Cobrança a que o caso se refere.

items[].amount_centsstring (centavos)

Valor do caso, em centavos.

items[].held_centsstring (centavos)

Quanto do seu saldo está bloqueado por este caso, em centavos.

items[].shortfall_centsstring (centavos)

Parte que não pôde ser bloqueada por falta de saldo, em centavos.

items[].originstring

Quem originou o caso: gateway (você), payer (pagador, via MED), koku, partner (rede de processamento) ou regulator.

items[].reasonstring

Motivo informado na abertura.

items[].liabilitystring

Quem responde pelo valor do caso: gateway, koku, partner ou undetermined (ainda não definido).

items[].execution_statusstring

Andamento da devolução: none, queued, submitted, unknown, completed, failed.

items[].resolutionstring ou null

Resultado quando resolvido (ex.: refunded).

items[].resolution_notestring ou null

Observação da resolução: texto escrito pela equipe Koku ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. null quando não há observação.

items[].resolved_amount_centsstring (centavos) ou null

Valor efetivamente devolvido, em centavos.

items[].opened_atstring (data e hora)

Abertura do caso.

items[].due_atstring (data e hora) ou null

Prazo do caso, quando houver.

items[].resolved_atstring (data e hora) ou null

Resolução do caso.

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