Cobranças Pix
Solicitar devolução
https://api.kokupay.com/v1/pix/charges/{id}/refunds Devolve ao pagador todo ou parte do valor de uma cobrança paga. O valor é bloqueado do seu saldo na hora e a devolução é processada em seguida; acompanhe pelo caso devolvido (status, execution_status) ou pelos eventos case.resolved e charge.refunded.
curl -X POST 'https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47/refunds' \
-H "Authorization: Bearer $KOKU_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: devolucao-pedido-1001-1" \
-d '{
"amount_cents": 5000,
"reason": "Cliente devolveu um item"
}'const response = await fetch('https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47/refunds', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'devolucao-pedido-1001-1',
},
body: JSON.stringify({
amount_cents: 5000,
reason: 'Cliente devolveu um item',
}),
});
const data = await response.json();
console.log(response.status, data);import os
import requests
response = requests.request(
"POST",
"https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47/refunds",
headers={
"Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
"Idempotency-Key": "devolucao-pedido-1001-1",
},
json={
"amount_cents": 5000,
"reason": "Cliente devolveu um item",
},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init('https://api.kokupay.com/v1/pix/charges/8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47/refunds');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: devolucao-pedido-1001-1',
],
CURLOPT_POSTFIELDS => json_encode([
'amount_cents' => 5000,
'reason' => 'Cliente devolveu um item',
]),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);{
"id": "3c7e1b95-6d2a-4f80-9e4b-a1d5c8f20e63",
"gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
"environment": "production",
"case_type": "refund",
"status": "in_review",
"med_stage": null,
"charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
"amount_cents": "5000",
"held_cents": "5000",
"shortfall_cents": "0",
"origin": "gateway",
"reason": "Cliente devolveu um item",
"liability": "gateway",
"execution_status": "queued",
"resolution": null,
"resolution_note": null,
"resolved_amount_cents": null,
"opened_at": "2026-10-08T12:00:00.000Z",
"due_at": null,
"resolved_at": null
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: refunds:write. Veja Chaves de API.
Cabeçalhos
Idempotency-KeystringobrigatórioChave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado.
8 a 200 caracteres
Veja Idempotência.
Parâmetros de caminho
idstring (uuid)obrigatórioIdentificador da cobrança paga.
Corpo da requisição
JSON (Content-Type: application/json). Campos não listados são recusados com 422.
amount_centsinteiro ou stringobrigatórioValor a devolver em centavos. Pode ser parcial; a soma das devoluções não passa do valor pago.
reasonstringobrigatórioMotivo da devolução (3 a 300 caracteres).
3 a 300 caracteres
Resposta 201
201 na criação; 200 com o mesmo recurso quando a requisição é repetida com a mesma Idempotency-Key e o mesmo corpo (cabeçalho Idempotent-Replayed: true).
idstring (uuid)Identificador do caso.
gateway_idstring (uuid)Identificador da sua conta na Koku.
environmentstringAmbiente: production (sandbox está reservado para o ambiente de testes, em preparação).
Valores: sandbox, production
case_typestringTipo: 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).
statusstringSituação do caso: open, in_review, awaiting_partner (aguardando a rede de processamento), resolved ou cancelled.
med_stagestring ou nullEtapa da contestação MED (notified, confirmed, returned, net_loss, dismissed); null nos demais tipos.
charge_idstring (uuid) ou nullCobrança a que o caso se refere.
amount_centsstring (centavos)Valor do caso, em centavos.
held_centsstring (centavos)Quanto do seu saldo está bloqueado por este caso, em centavos.
shortfall_centsstring (centavos)Parte que não pôde ser bloqueada por falta de saldo, em centavos.
originstringQuem originou o caso: gateway (você), payer (pagador, via MED), koku, partner (rede de processamento) ou regulator.
reasonstringMotivo informado na abertura.
liabilitystringQuem responde pelo valor do caso: gateway, koku, partner ou undetermined (ainda não definido).
execution_statusstringAndamento da devolução: none, queued, submitted, unknown, completed, failed.
resolutionstring ou nullResultado quando resolvido (ex.: refunded).
resolution_notestring ou nullObservaçã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.
resolved_amount_centsstring (centavos) ou nullValor efetivamente devolvido, em centavos.
opened_atstring (data e hora)Abertura do caso.
due_atstring (data e hora) ou nullPrazo do caso, quando houver.
resolved_atstring (data e hora) ou nullResoluçã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. |
| 409 | conflict | A cobrança não está paga, ou a devolução precisa ser feita com a Koku (details.reason = "manual_refund_required": fale com a Koku informando o correlation_id). |
| 409 | insufficient_funds | Saldo insuficiente para a devolução (details.reason = "refund_insufficient_funds"). |
| 409 | idempotency_conflict | A mesma Idempotency-Key foi usada com outro corpo (outra cobrança, outro valor ou outro motivo). |
| 422 | validation_error | Valor acima do que ainda pode ser devolvido, motivo ausente ou com mais de 300 caracteres, ou Idempotency-Key ausente. |
| 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.