Reembolsos

Devolve o dinheiro de um pedido, no todo ou em parte, pelo gateway de pagamento.

Reembolso é devolver ao cliente o valor pago, no todo ou em parte. Ele é uma operação de pagamento, separada de mudar o status do pedido: o dinheiro sai pelo gateway (cartão, PIX, boleto) e a plataforma registra a devolução no pagamento do pedido. Nesta API, mudar o status (inclusive cancelar) nunca estorna: o reembolso é sempre uma chamada à parte, POST /orders/{id}/refund.

Esta página documenta o refund: o pedido ao gateway para devolver o valor de um pedido, no todo ou em parte.

POST/api/v1.0/orders/{id}/refundAdmin

Reembolsar um pedido

Pede ao gateway que devolva o valor do pedido. Sem amount, devolve o saldo ainda não reembolsado. O corpo é opcional.

Se o pedido não tem cobrança confirmada no gateway (por exemplo, pagamento na entrega, ou um pedido de teste), nenhum dinheiro se move: a plataforma grava um registro de reembolso manual, só para auditoria, e a resposta é 200 com refund_transaction vazio. Confira se refund_transaction veio preenchido para saber que o gateway devolveu de fato.

Chave de API de seller só consegue estornar pedidos da própria loja.

Parâmetros de caminho

idstringobrigatório

Id do pedido (UUID; decimal em string em /api/orders/{id}/refund).

Corpo da requisição (opcional)

amountinteger

Valor a devolver em centavos (número inteiro, 1000 = R$ 10,00), mesmo nesta API que usa string decimal nas respostas. Zero, negativo ou omitido devolve o saldo restante do pedido. Valor acima do saldo é limitado ao saldo.

Exemplo de requisição

bash

# Reembolso parcial de R$ 10,00
curl -X POST "$BASE_URL/api/v1.0/orders/$ORDER_ID/refund" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000}'

Resposta

200API 1.0: reembolso feito

json

{
  "order_id": "0932405c-a8c1-49b3-a7db-61aab4c4d666",
  "refund_transaction": "re_9Vq2kLxYzNwB41pD",
  "amount": "10.00"
}

Campos da resposta

order_idstring

Pedido reembolsado.

refund_transactionstring

Identificador do estorno no gateway. Vazio quando não houve cobrança a estornar (registro manual).

amountstring

Valor pedido, em string decimal. Se o saldo era menor, o valor efetivamente devolvido pode ser menor que o informado.

Erros

Status	Quando	Corpo
400	Valor ou estorno recusado pelo gateway; pedido já totalmente reembolsado	`{"message":"order ... has already been fully refunded (refunded: ..., total: ...)","status":400}`
401	Sem credenciais ou chave de API inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Pedido inexistente	`{"error":"internal server error"}`
501	A loja não tem serviço de pagamentos ligado	`{"message":"refund not implemented: payments service not wired","status":501}`

Veja também