Devoluções

Devoluções totais ou parciais de pagamentos.

Solicitar devolução

POST /v1/refunds

Solicita a devolução total ou parcial de um pagamento. A soma das devoluções não pode exceder o valor do pagamento. A taxa da plataforma é estornada proporcionalmente ao valor devolvido; pode incidir taxa de devolução conforme o contrato. A devolução é assíncrona: acompanhe pelo status ou pelos eventos refund.succeeded / refund.failed. Se o banco estiver momentaneamente indisponível, a devolução é registrada (201, processing) e enviada assim que ele responder — sem risco de devolução em dobro. Só uma devolução por pagamento pode estar em processamento por vez (409 refund-in-progress). Requer o escopo refunds:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

Campo	Tipo	Descrição
`payment_id` obrigatório	string
`amount` obrigatório	string (valor)	Valor em reais, duas casas decimais, separador ponto.
`reason`	string
`metadata`	Metadata	Até 20 pares chave/valor livres do integrador (chave ≤ 40, valor ≤ 500 caracteres). Não use para dados pessoais.

Respostas

201 Devolução registrada (enviada ao banco ou na fila de envio).
400 Requisição inválida (formato ou campos).
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,
422 Regra de negócio violada: `idempotency-key-reused`, `refund-exceeds-available`,
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.
503 O banco está temporariamente indisponível. Repita com a mesma `Idempotency-Key` após `Retry-After`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/refunds" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_id": "pay_01J9Z3K4M5N6P7Q8R9S0T1U2V3",
  "amount": "50.00",
  "reason": "Item fora de estoque"
}'

Identificador nos logs: api.refunds.create

Listar devoluções

GET /v1/refunds

Inclui devoluções iniciadas pelo lojista e devoluções por MED. Requer o escopo refunds:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`limit`	consulta	integer
`starting_after`	consulta	string	Cursor — ID do último objeto da página anterior.
`ending_before`	consulta	string	Cursor — ID do primeiro objeto da página seguinte.
`created_gte`	consulta	string (date-time)
`created_lte`	consulta	string (date-time)
`payment_id`	consulta	string
`status`	consulta	RefundStatus
`nature`	consulta	RefundNature

Respostas

200 Lista paginada de devoluções.
400 Requisição inválida (formato ou campos).
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/refunds?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.refunds.list

Consultar devolução

GET /v1/refunds/{refund_id}

Requer o escopo refunds:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`refund_id` obrigatório	caminho	string

Respostas

200 Devolução.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/refunds/rf_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.refunds.retrieve