Reembolsos

Lista os reembolsos feitos, acompanha os estornos pendentes e resolve os que travaram.

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. Mover um pedido pago para cancelled ou refunded (ou cancelá-lo) estorna automaticamente no gateway, antes de gravar o novo status. Para estornar um valor parcial ou a um pagamento específico, use as rotas de pagamentos (POST /api/v1/admin/payments/{id}/refund).

Esta página documenta as três rotas para acompanhar reembolsos: a lista de reembolsos feitos, a fila de estornos pendentes e a resolução de um estorno que travou.

GET/api/v1/admin/orders/refundsAdmin

Lista os reembolsos

Lista os reembolsos registrados nos pedidos da loja, do mais recente para o mais antigo, com o pedido e o cliente de cada um. Exige view_orders ou manage_orders.

Query parameters

statusstring

pendingsuccessfailed

Situação do reembolso.

searchstring

Texto livre: número do pedido, nome ou e-mail do cliente.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página. Valores muito altos voltam ao padrão.

GET/api/v1/admin/orders/pending-refundsAdmin

Pedidos com reembolso pendente

Lista os pedidos presos em um estorno pendente: o cancelamento começou, o estorno foi pedido ao gateway, mas o pedido ainda não chegou ao final (o gateway está processando, ou o processo foi interrompido no meio). Esses pedidos não aceitam outra mudança de status até o estorno ser resolvido. Exige view_orders ou manage_orders.

POST/api/v1/admin/orders/{id}/resolve-refundAdmin

Resolve a pending refund

Destrava um pedido da lista de estornos pendentes. A ação auto só conclui o cancelamento quando o pagamento já registra o estorno; finish e release são a sua confirmação, depois de conferir no gateway, de que o dinheiro voltou ou não voltou. Só funciona para pedido que está na fila de estornos pendentes, e uma tentativa muito recente (menos de 10 minutos) é recusada, porque o estorno ainda pode estar em andamento. Exige manage_orders.

Path parameters

iduuidobrigatório

Id do pedido com estorno pendente.

Corpo da requisição

actionstringpadrão: auto

autofinishrelease

auto: conclui só se o estorno já está registrado no pagamento. finish: você confirmou no gateway que o estorno foi feito; o cancelamento é concluído. release: você confirmou no gateway que nenhum estorno foi feito; o pedido volta ao status anterior.

Exemplo de requisição

bash

# Reembolsos bem-sucedidos
curl "$BASE_URL/api/v1/admin/orders/refunds?status=success&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

# Estornos pendentes e resolução automática
curl "$BASE_URL/api/v1/admin/orders/pending-refunds" -H "Authorization: Bearer $TOKEN"
curl -X POST "$BASE_URL/api/v1/admin/orders/$ORDER_ID/resolve-refund" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"auto"}'

Resposta

200Lista de reembolsos

json

{
  "refunds": [
    {
      "id": "2f097fcc-d6ae-452d-9143-ef3dd03c89b2",
      "order_id": "85d6f5fd-8848-44aa-b4b3-327df53e35a5",
      "order_number": "11692",
      "customer_name": "Tatiane Oliveira",
      "customer_email": "tatiane.oliveira@example.com",
      "amount": 19980,
      "currency": "BRL",
      "status": "success",
      "order_total": 19980,
      "created_at": "2026-09-09T05:12:54.070712Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

200Estornos pendentes

json

{
  "pending_refunds": [
    {
      "order_id": "85d6f5fd-8848-44aa-b4b3-327df53e35a5",
      "order_number": "11692",
      "claim_id": "c4a1e0b2-7d33-4f6e-9a1c-2b8f0e5d6a77",
      "claimed_at": "2026-10-11T19:02:11Z",
      "prev_status": "P",
      "target": "cancelled",
      "total": 19980,
      "refund_booked": false,
      "refund_pending": true
    }
  ],
  "total": 1
}

200Estorno resolvido

json

{ "outcome": "finished" }

Campos da resposta

refunds[].iduuid

Id do reembolso.

refunds[].amountinteger

Valor devolvido em centavos.

refunds[].statusstring

pendingsuccessfailed

Situação do reembolso.

refunds[].order_totalinteger

Total do pedido em centavos, para comparar com amount.

pending_refunds[].claim_iduuid

Identificador do estorno em andamento.

pending_refunds[].claimed_atstring

Quando o cancelamento reservou o pedido. RFC 3339.

pending_refunds[].prev_statusstring

Letra do status que o pedido tinha antes.

pending_refunds[].targetstring

Status para o qual o pedido ia (cancelled ou refunded).

pending_refunds[].refund_bookedboolean

true quando o pagamento já registra o estorno concluído (então auto conclui).

pending_refunds[].refund_pendingboolean

true quando há um estorno em andamento ou de resultado desconhecido; confira no gateway.

outcomestring

finishedreleased

(resolve-refund) finished: o cancelamento foi concluído. released: o pedido foi liberado e voltou ao status anterior.

Erros

Status	Quando	Corpo
400	`status` fora de `pending`, `success`, `failed` na lista; `action` inválida em `resolve-refund`	`{"error":"invalid status filter","detail":"status must be one of pending, success, failed"}` ou `{"error":"unknown_resolve_action","detail":"Ação inválida."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão	`{"error":"insufficient privileges","required":"manage_orders"}`
404	`resolve-refund` em pedido sem estorno pendente	`{"error":"no_cancel_claim","detail":"Este pedido não tem estorno pendente."}`
409	`resolve-refund` não pode concluir ainda	`{"error":"cancel_claim_too_recent"}`, `{"error":"needs_manual_confirmation"}`, `{"error":"refund_in_flight"}` ou `{"error":"refund_booked"}`, cada um com `detail` explicando o próximo passo

Veja também

Reembolsos

Lista os reembolsos feitos, acompanha os estornos pendentes e resolve os que travaram.

Esta página documenta as três rotas para acompanhar reembolsos: a lista de reembolsos feitos, a fila de estornos pendentes e a resolução de um estorno que travou.

GET/api/v1/admin/orders/refundsAdmin

Lista os reembolsos

Lista os reembolsos registrados nos pedidos da loja, do mais recente para o mais antigo, com o pedido e o cliente de cada um. Exige view_orders ou manage_orders.

Query parameters

statusstring

pendingsuccessfailed

Situação do reembolso.

searchstring

Texto livre: número do pedido, nome ou e-mail do cliente.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página. Valores muito altos voltam ao padrão.

GET/api/v1/admin/orders/pending-refundsAdmin

Pedidos com reembolso pendente

POST/api/v1/admin/orders/{id}/resolve-refundAdmin

Resolve a pending refund

Path parameters

iduuidobrigatório

Id do pedido com estorno pendente.

Corpo da requisição

actionstringpadrão: auto

autofinishrelease

Exemplo de requisição

bash

# Reembolsos bem-sucedidos
curl "$BASE_URL/api/v1/admin/orders/refunds?status=success&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

# Estornos pendentes e resolução automática
curl "$BASE_URL/api/v1/admin/orders/pending-refunds" -H "Authorization: Bearer $TOKEN"
curl -X POST "$BASE_URL/api/v1/admin/orders/$ORDER_ID/resolve-refund" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"auto"}'

Resposta

200Lista de reembolsos

json

{
  "refunds": [
    {
      "id": "2f097fcc-d6ae-452d-9143-ef3dd03c89b2",
      "order_id": "85d6f5fd-8848-44aa-b4b3-327df53e35a5",
      "order_number": "11692",
      "customer_name": "Tatiane Oliveira",
      "customer_email": "tatiane.oliveira@example.com",
      "amount": 19980,
      "currency": "BRL",
      "status": "success",
      "order_total": 19980,
      "created_at": "2026-09-09T05:12:54.070712Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

200Estornos pendentes

json

{
  "pending_refunds": [
    {
      "order_id": "85d6f5fd-8848-44aa-b4b3-327df53e35a5",
      "order_number": "11692",
      "claim_id": "c4a1e0b2-7d33-4f6e-9a1c-2b8f0e5d6a77",
      "claimed_at": "2026-10-11T19:02:11Z",
      "prev_status": "P",
      "target": "cancelled",
      "total": 19980,
      "refund_booked": false,
      "refund_pending": true
    }
  ],
  "total": 1
}

200Estorno resolvido

json

{ "outcome": "finished" }

Campos da resposta

refunds[].iduuid

Id do reembolso.

refunds[].amountinteger

Valor devolvido em centavos.

refunds[].statusstring

pendingsuccessfailed

Situação do reembolso.

refunds[].order_totalinteger

Total do pedido em centavos, para comparar com amount.

pending_refunds[].claim_iduuid

Identificador do estorno em andamento.

pending_refunds[].claimed_atstring

Quando o cancelamento reservou o pedido. RFC 3339.

pending_refunds[].prev_statusstring

Letra do status que o pedido tinha antes.

pending_refunds[].targetstring

Status para o qual o pedido ia (cancelled ou refunded).

pending_refunds[].refund_bookedboolean

true quando o pagamento já registra o estorno concluído (então auto conclui).

pending_refunds[].refund_pendingboolean

true quando há um estorno em andamento ou de resultado desconhecido; confira no gateway.

outcomestring

finishedreleased

(resolve-refund) finished: o cancelamento foi concluído. released: o pedido foi liberado e voltou ao status anterior.

Erros

Status	Quando	Corpo
400	`status` fora de `pending`, `success`, `failed` na lista; `action` inválida em `resolve-refund`	`{"error":"invalid status filter","detail":"status must be one of pending, success, failed"}` ou `{"error":"unknown_resolve_action","detail":"Ação inválida."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão	`{"error":"insufficient privileges","required":"manage_orders"}`
404	`resolve-refund` em pedido sem estorno pendente	`{"error":"no_cancel_claim","detail":"Este pedido não tem estorno pendente."}`
409	`resolve-refund` não pode concluir ainda	`{"error":"cancel_claim_too_recent"}`, `{"error":"needs_manual_confirmation"}`, `{"error":"refund_in_flight"}` ou `{"error":"refund_booked"}`, cada um com `detail` explicando o próximo passo