Docs
Acessar painel

Cobranças Pix

Solicitar devolução

POSThttps://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.

POST/v1/pix/charges/{id}/refunds
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"
}'
201Resposta
{
  "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ório

Chave ú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ório

Identificador 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ório

Valor a devolver em centavos. Pode ser parcial; a soma das devoluções não passa do valor pago.

reasonstringobrigatório

Motivo 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.

environmentstring

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

Valores: sandbox, production

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).

statusstring

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

med_stagestring ou null

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

charge_idstring (uuid) ou null

Cobranç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.

originstring

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

reasonstring

Motivo informado na abertura.

liabilitystring

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

execution_statusstring

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

resolutionstring ou null

Resultado quando resolvido (ex.: refunded).

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.

resolved_amount_centsstring (centavos) ou null

Valor efetivamente devolvido, em centavos.

opened_atstring (data e hora)

Abertura do caso.

due_atstring (data e hora) ou null

Prazo do caso, quando houver.

resolved_atstring (data e hora) ou null

Resolução do caso.

Erros

StatusCódigoQuando
401unauthorizedChave ausente, inválida, revogada ou expirada.
403forbiddenA chave não tem o escopo exigido (details.reason = "missing_scope").
404not_foundCobrança inexistente ou de outra conta.
409conflictA 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).
409insufficient_fundsSaldo insuficiente para a devolução (details.reason = "refund_insufficient_funds").
409idempotency_conflictA mesma Idempotency-Key foi usada com outro corpo (outra cobrança, outro valor ou outro motivo).
422validation_errorValor acima do que ainda pode ser devolvido, motivo ausente ou com mais de 300 caracteres, ou Idempotency-Key ausente.
429rate_limitedLimite de requisições excedido. Aguarde o tempo de Retry-After.
500internal_errorFalha inesperada. Repita com a mesma Idempotency-Key; persistindo, envie o correlation_id à Koku (veja Suporte).

Formato do corpo de erro em Erros.