Reembolsar cobrança

Quick Reference

WhatReembolsar uma cobrança capturada

WhyDevolver fundos ao pagador — prevenir chargebacks, tratar devoluções e manter a confiança do cliente

Reading Time5 min

DifficultyIntermediate

PrerequisitesAuthentication → A captured charge (status: confirmed or paid)

POST/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/Bearer TokenReembolsar uma cobrança

Por que reembolsos importam

Sem reembolsos	Com reembolsos
Clientes insatisfeitos abrem chargebacks (taxa de disputa de $25+ cada)	Você devolve os fundos proativamente antes de uma disputa ser aberta
A taxa de chargeback sobe acima de 1% — bandeiras de cartão sinalizam sua conta	A taxa de reembolso não conta contra seu limite de chargeback
Confiança do cliente se deteriora após uma experiência ruim	Reembolsos rápidos transformam um negativo em "eles resolveram"
Contabilidade mostra receita superestimada	Valores reembolsados ajustam o relatório de receita automaticamente
Tickets de suporte se acumulam com "cadê meu dinheiro?"	Status do reembolso é rastreável via Consultar Cobrança e webhooks

---

Fluxo de reembolso

---

Autenticação

Requer token Bearer. Veja Autenticação.

Parâmetros de caminho

Ambos os UUIDs vão no caminho da URL, não no corpo da requisição nem na query string:

Campo	Tipo	Obrigatório	Descrição
charge_uuid	string (UUID)	Sim	Cobrança a reembolsar
wallet_uuid	string (UUID)	Sim	Carteira proprietária da cobrança

Campos opcionais do corpo

Campo	Tipo	Obrigatório	Descrição
amount	number	Não	Valor do reembolso parcial. Omita para reembolso total
reason	string	Não	Motivo do reembolso para conciliação e relatórios

Parâmetros de caminho, não corpo

Diferente da maioria dos endpoints da A55, o endpoint de reembolso recebe charge_uuid e wallet_uuid no caminho da URL: POST /api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/

---

Exemplos de código

Reembolso total

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/wallet/charge/51dcca6e-7310-4b73-a94c-90835408f2ff/refund/f47ac10b-58cc-4372-a567-0e02b2c3d479/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Python

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")

charge_uuid = "51dcca6e-7310-4b73-a94c-90835408f2ff"
wallet_uuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479"

refund = requests.post(
    f"{base}/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"Refund: {refund['charge_uuid']} — Status: {refund['status']}")

JavaScript

const token = process.env.A55_API_TOKEN;
const base = process.env.A55_API_BASE_URL || "https://core-manager.a55.tech";

const chargeUuid = "51dcca6e-7310-4b73-a94c-90835408f2ff";
const walletUuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479";

const refund = await fetch(
  `${base}/api/v1/bank/wallet/charge/${chargeUuid}/refund/${walletUuid}/`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  }
).then((r) => r.json());

console.log(`Refund: ${refund.charge_uuid} — Status: ${refund.status}`);

Reembolso parcial

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/wallet/charge/51dcca6e-7310-4b73-a94c-90835408f2ff/refund/f47ac10b-58cc-4372-a567-0e02b2c3d479/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.25,
    "reason": "Customer returned 1 of 3 items"
  }'

Python

partial_refund = requests.post(
    f"{base}/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/",
    json={
        "amount": 50.25,
        "reason": "Customer returned 1 of 3 items",
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"Partial refund: {partial_refund['status']}")

JavaScript

const partialRefund = await fetch(
  `${base}/api/v1/bank/wallet/charge/${chargeUuid}/refund/${walletUuid}/`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 50.25,
      reason: "Customer returned 1 of 3 items",
    }),
  }
).then((r) => r.json());

console.log(`Partial refund: ${partialRefund.status}`);

---

Campos da resposta

Campo	Tipo	Descrição
charge_uuid	string	Identificador da cobrança reembolsada
wallet_uuid	string	Carteira proprietária da cobrança
status	string	refunded em caso de sucesso
message	object	Detalhes adicionais ou objeto vazio em caso de sucesso

---

Exemplo completo de resposta

Reembolso total

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "refunded",
  "message": {}
}

Reembolso parcial

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "refunded",
  "message": {}
}

---

Respostas de erro

Status	Código	Descrição	Resolução
400	errors.wallet.not_found	UUID da carteira não existe	Verifique o wallet_uuid no caminho da URL
400	REFUND_NOT_ALLOWED	Cobrança não está em estado reembolsável	Somente cobranças confirmed ou paid podem ser reembolsadas. Verifique o status da cobrança com Consultar cobrança
401	unauthorized	Token Bearer inválido ou expirado	Renove seu token de acesso via Cognito
404	CHARGE_NOT_FOUND	Cobrança não encontrada	Verifique o charge_uuid no caminho da URL
422	amount_exceeds_captured	Valor do reembolso parcial excede o valor capturado	O valor do reembolso deve ser ≤ ao valor capturado

Reembolsos de parcelas são tudo ou nada

Se um pagamento foi feito em parcelas, um reembolso total devolve todas as parcelas integralmente. Você não pode reembolsar uma única parcela. Para devoluções parciais em pagamentos parcelados, use um reembolso parcial com um amount específico.

Reembolso vs. chargeback — comparação de custos

Processar um reembolso custa nada além do pagamento revertido. Um chargeback custa o valor do pagamento mais uma taxa de disputa ($25–$100 dependendo da bandeira do cartão). Sempre reembolse proativamente quando uma reclamação legítima chegar.

Prazo do reembolso

Reembolsos levam 5–10 dias úteis para aparecer no extrato do pagador, dependendo do banco emissor do cartão. Informe seus clientes sobre esse prazo para reduzir tickets de suporte com "cadê meu reembolso?".

Consultar cobrança →Verificar o status do reembolso consultando a cobrança.Listar cobranças →Encontrar cobranças para reembolsar na sua lista de transações.Webhooks →Receber um webhook quando o reembolso for processado.