Refund charge

Quick Reference

WhatRefund a captured charge

WhyReturn funds to the payer — prevent chargebacks, handle returns, and maintain customer trust

Reading Time5 min

DifficultyIntermediate

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

POST/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/Bearer TokenRefund a charge

Why refunds matter

Without refunds	With refunds
Unhappy customers file chargebacks ($25+ dispute fee each)	You return funds proactively before a dispute is filed
Chargeback ratio rises above 1% — card networks flag your account	Refund ratio doesn't count against your chargeback threshold
Customer trust erodes after a bad experience	Fast refunds turn a negative into a "they made it right" moment
Accounting shows overstated revenue	Refunded amounts adjust revenue reporting automatically
Support tickets pile up with "where's my money?"	Refund status is trackable via Get Charge and webhooks

Refund flow

Authentication

Requires Bearer token. See Authentication.

Path parameters

Both UUIDs go in the URL path, not in the request body or query string:

Field	Type	Required	Description
`charge_uuid`	string (UUID)	Yes	Charge to refund
`wallet_uuid`	string (UUID)	Yes	Wallet that owns the charge

Optional body fields

Field	Type	Required	Default	Description
`amount`	number (float)	No	full remaining amount	Partial refund amount. If omitted, the full remaining amount of the charge is refunded. Must be ≤ `amount_remaining`

Path parameters, not body

Unlike most A55 endpoints, the refund endpoint takes charge_uuid and wallet_uuid in the URL path: POST /api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/

Code examples

Full refund

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}`);

Partial refund

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"Partial refund: {partial_refund['status']} "
    f"(refunded {partial_refund['amount_refunded']}, "
    f"remaining {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(
  `Partial refund: ${partialRefund.status} ` +
    `(refunded ${partialRefund.amount_refunded}, ` +
    `remaining ${partialRefund.amount_remaining})`
);

Response fields

Field	Type	Description
`charge_uuid`	string	Refunded charge identifier
`wallet_uuid`	string	Wallet that owned the charge
`status`	string	`refunded` when fully refunded, `partially_refunded` when there is still remaining balance
`amount_refunded`	number (float)	Total amount refunded so far across all refund operations on this charge
`amount_remaining`	number (float)	Remaining refundable amount. When it reaches `0`, the charge is fully refunded
`message`	object	Provider/acquirer messages collected during the refund attempt(s)
`refunds`	array	History of refund operations performed on this charge

`refunds[]` item

Field	Type	Description
`refund_uuid`	string	UUID of the refund operation
`amount`	number (float)	Amount of this specific refund
`status`	string	Refund status: `refunded` or `refund_error`
`reason`	string	Reason for the refund
`created`	datetime	Refund creation date (ISO 8601)

Complete response example

Full refund

{
  "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"
    }
  ]
}

Partial refund

{
  "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"
    }
  ]
}

Error responses

Status	Code	Description	Resolution
400	`errors.wallet.not_found`	Wallet UUID does not exist	Verify `wallet_uuid` in the URL path
400	`errors.wallet.charge_refund_not_available`	Charge is not in a refundable state	Only `confirmed` or `paid` charges can be refunded. Check charge status with Get charge
401	`unauthorized`	Invalid or expired Bearer token	Refresh your access token via Cognito
422	`errors.wallet.charge_refund_amount_exceeded`	Requested `amount` is greater than `amount_remaining`	The response body includes the current `amount_remaining` — retry with a value ≤ that

Installment refunds are all-or-nothing

If a payment was made in installments, a full refund returns all installments in full. You cannot refund a single installment. For partial returns on installment payments, use a partial refund with a specific amount.

Refund vs. chargeback — costs comparison

Processing a refund costs you nothing beyond the reversed payment. A chargeback costs you the payment amount plus a dispute fee ($25–$100 depending on the card network). Always refund proactively when a legitimate complaint arrives.

Refund timing

Refunds take 5–10 business days to appear on the payer's statement, depending on the card issuer. Inform your customers about this timeline to reduce "where's my refund?" support tickets.

Get charge →Verify refund status by polling the charge.List charges →Find charges to refund in your transaction list.Webhooks →Receive a webhook when the refund is processed.

Quick Reference

Why refunds matter​

Refund flow​

Authentication​

Path parameters​

Optional body fields​

Code examples​

Full refund​

Partial refund​

Response fields​

refunds[] item​

Complete response example​

Full refund​

Partial refund​

Error responses​

Why refunds matter

Refund flow

Authentication

Path parameters

Optional body fields

Code examples

Full refund

Partial refund

Response fields

`refunds[]` item

Complete response example

Full refund

Partial refund

Error responses