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	Padrão	Descrição
`amount`	number (float)	Não	valor reembolsável restante	Valor do reembolso parcial. Se omitido, reembolsa o valor reembolsável restante. Deve ser ≤ `amount_remaining`
`webhook_refund_url`	string (URL)	Não	—	URL dedicada que receberá a notificação de webhook do reembolso, além da URL de webhook padrão configurada para a carteira

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
Python
JavaScript

curl -s -X POST "https://sandbox.api.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"

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://sandbox.api.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']}")

const token = process.env.A55_API_TOKEN;
const base = process.env.A55_API_BASE_URL || "https://sandbox.api.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
Python
JavaScript

curl -s -X POST "https://sandbox.api.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
  }'

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

print(
    f"Reembolso parcial: {partial_refund['status']} "
    f"(reembolsado {partial_refund['amount_refunded']}, "
    f"restante {partial_refund['amount_remaining']})"
)

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 }),
  }
).then((r) => r.json());

console.log(
  `Reembolso parcial: ${partialRefund.status} ` +
    `(reembolsado ${partialRefund.amount_refunded}, ` +
    `restante ${partialRefund.amount_remaining})`
);

Reembolso com URL de webhook dedicada

Use webhook_refund_url para enviar a notificação do reembolso para uma URL diferente do webhook padrão configurado para a carteira. O webhook padrão continua recebendo o evento — a nova URL é adicionada além dele.

cURL
Python
JavaScript

curl -s -X POST "https://sandbox.api.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,
    "webhook_refund_url": "https://your-app.com/webhooks/a55/refunds"
  }'

refund_with_webhook = requests.post(
    f"{base}/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/",
    json={
        "amount": 50.25,
        "webhook_refund_url": "https://your-app.com/webhooks/a55/refunds",
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"Reembolso enfileirado — webhook chegará no seu endpoint de reembolsos: {refund_with_webhook['status']}")

const refundWithWebhook = 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,
      webhook_refund_url: "https://your-app.com/webhooks/a55/refunds",
    }),
  }
).then((r) => r.json());

console.log(
  `Reembolso enfileirado — webhook chegará no seu endpoint de reembolsos: ${refundWithWebhook.status}`
);

Webhooks de reembolso são aditivos

webhook_refund_url não substitui a URL de webhook padrão da carteira — ela é chamada além dela. A URL padrão continua recebendo todos os eventos de pagamento (incluindo reembolsos), e a URL dedicada recebe apenas as notificações de reembolso. Use isso quando os eventos de reembolso precisarem ser processados por um sistema downstream separado.

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` quando totalmente reembolsada, `partially_refunded` quando ainda há saldo restante
`amount_refunded`	number (float)	Valor total reembolsado até agora em todas as operações de reembolso desta cobrança
`amount_remaining`	number (float)	Valor reembolsável restante. Quando chega a `0`, a cobrança está totalmente reembolsada
`message`	object	Mensagens do provedor/adquirente coletadas durante a(s) tentativa(s) de reembolso
`refunds`	array	Histórico de operações de reembolso realizadas nesta cobrança

Item de `refunds[]`

Campo	Tipo	Descrição
`refund_uuid`	string	UUID da operação de reembolso
`amount`	number (float)	Valor deste reembolso específico
`status`	string	Status do reembolso: `refunded` ou `refund_error`
`reason`	string	Motivo do reembolso
`created`	datetime	Data de criação do reembolso (ISO 8601)

Exemplo completo de resposta

Reembolso total

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "refunded",
  "amount_refunded": 100.00,
  "amount_remaining": 0.00,
  "message": {},
  "refunds": [
    {
      "refund_uuid": "9b1f0c88-3a3c-4f2f-9d6e-1f0a2d4e88c1",
      "amount": 100.00,
      "status": "refunded",
      "reason": "customer_request",
      "created": "2026-04-27T18:00:00Z"
    }
  ]
}

Reembolso parcial

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "partially_refunded",
  "amount_refunded": 50.25,
  "amount_remaining": 49.75,
  "message": {},
  "refunds": [
    {
      "refund_uuid": "5c2a13f0-5e74-4b21-9c6a-2bd9d9b0aa10",
      "amount": 50.25,
      "status": "refunded",
      "reason": "customer_request",
      "created": "2026-04-27T18:00:00Z"
    }
  ]
}

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	`errors.wallet.charge_refund_not_available`	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
422	`errors.wallet.charge_refund_amount_exceeded`	`amount` solicitado é maior que `amount_remaining`	A resposta inclui o `amount_remaining` atual — refaça a chamada com um valor ≤ a esse

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.

Quick Reference

Por que reembolsos importam​

Fluxo de reembolso​

Autenticação​

Parâmetros de caminho​

Campos opcionais do corpo​

Exemplos de código​

Reembolso total​

Reembolso parcial​

Reembolso com URL de webhook dedicada​

Campos da resposta​

Item de refunds[]​

Exemplo completo de resposta​

Reembolso total​

Reembolso parcial​

Respostas de erro​

Por que reembolsos importam

Fluxo de reembolso

Autenticação

Parâmetros de caminho

Campos opcionais do corpo

Exemplos de código

Reembolso total

Reembolso parcial

Reembolso com URL de webhook dedicada

Campos da resposta

Item de `refunds[]`

Exemplo completo de resposta

Reembolso total

Reembolso parcial

Respostas de erro