Issue a refund

In this guide you’ll issue a refund against a payment you already collected, then track it to completion. You can refund the full amount or part of it. A refund returns money to the customer. You request it in the currency your payment settled in, and the customer is paid back in the currency they paid. Refunds are asynchronous: you create one, then a refund.* webhook tells you the outcome.

Before you start

A sandbox API key (sk_sandbox_...) with the refunds:write scope. See Permissions.
A payment to refund. Its charge_id comes from the payment or the collection.succeeded webhook.
A webhook endpoint to receive the result. See Set up webhooks.

What can be refunded

Check is_refundable on the payment. When it is false, the refund is refused, so there is no point in trying. When it is true, the refund is accepted in almost every case, with one exception noted below. A payment can be refunded when all of this is true:

Its status is succeeded, accepted, or underpaid. A payment that is still created or processing, or that already failed, cannot be refunded.
Its payment method supports refunds. See the table below.
It does not already carry a refund. A payment takes one refund. Once you refund part of a payment, you cannot come back later for the rest.

A refund that failed does not count. Nothing moved, so the payment becomes refundable again and you can create a new refund for it.

Supported refund currencies

Payment method	Currencies	Can be refunded
Card	USD, NGN	Yes
Bank transfer	NGN	No
Mobile money	GHS, KES, TZS, UGX, XAF, XOF, RWF, MWK, ZMW	Yes
Crypto	USDT, USDC, ETH, SOL, BNB, CELO on their supported networks	Yes, with a `refund_address`

Steps

Create the refund

Call POST /v1/refunds with the payment you’re refunding and a unique reference. Omit amount for a full refund, or pass a decimal string for a partial one.

curl https://sandbox-api.bachs.io/v1/refunds \
  -H "Authorization: Bearer $BACHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_id": "ch_1a2b3c4d5e6f",
    "reference": "refund_9876",
    "reason": "Customer requested cancellation"
  }'

{
  "refund_id": "rfnd_4b9c2e7a1d35a0f81c62",
  "charge_id": "ch_1a2b3c4d5e6f",
  "reference": "refund_9876",
  "status": "processing",
  "requested_amount": "29.00",
  "refunded_amount": null,
  "refund_fee_amount": "0.00",
  "fee_bearer": "org",
  "reason": "Customer requested cancellation",
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:00Z",
  "completed_at": null
}

The refund starts in processing, and your balance is reserved for it straight away. When a refund succeeds, the payment becomes refunded for a full refund or partially_refunded for a partial refund, and is_refundable becomes false. When we refund a payment automatically, it becomes auto_refunded instead, so you can tell the two apart.For a partial refund, add an amount in the payment’s settlement currency:

Partial refund

curl https://sandbox-api.bachs.io/v1/refunds \
  -H "Authorization: Bearer $BACHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "charge_id": "ch_1a2b3c4d5e6f", "reference": "refund_9877", "amount": "10.00" }'

Pass a unique reference per refund (max 128 characters). Reusing one returns a duplicate error. Add an idempotency_key (max 255 characters) to make retries safe: the same key on the same payment returns the refund you already created, for 24 hours.

Track it with a webhook

Refunds finish asynchronously. Listen for the refund.* events to know the outcome.

refund.paid

{
  "id": "evt_5c4b3a2f1e",
  "type": "refund.paid",
  "created_at": "2026-04-27T12:03:00Z",
  "organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "data": {
    "refund_id": "rfnd_4b9c2e7a1d35a0f81c62",
    "charge_id": "ch_1a2b3c4d5e6f",
    "reference": "refund_9876",
    "status": "success",
    "requested_amount": "29.00",
    "refunded_amount": "29.00",
    "refund_fee_amount": "0.00",
    "fee_bearer": "org",
    "reason": "Customer requested cancellation"
  }
}

You get refund.created when the refund is accepted, refund.paid when it goes through, and refund.failed if it does not.

Event	`status` in the payload	What it means
`refund.created`	`processing`	Accepted. Your balance is reserved and the outcome is not known yet.
`refund.paid`	`success`	The money has left us on its way to the customer. Final.
`refund.failed`	`failed`	Nothing moved. Your reserved balance is released and you can try again. Final.

Check the status any time

Retrieve a refund by ID to see where it is, or list refunds for reconciliation.

curl https://sandbox-api.bachs.io/v1/refunds/rfnd_4b9c2e7a1d35a0f81c62 \
  -H "Authorization: Bearer $BACHS_API_KEY"

curl https://sandbox-api.bachs.io/v1/refunds \
  -H "Authorization: Bearer $BACHS_API_KEY"

If a create call fails with a network error (500, 502, 503, 504), do not assume the refund was not created. Retrieve it with the by-charge endpoint before you try again, or a blind retry answers 409 CONFLICT.

How long a refund takes

A refund passes through two stages, and only the first one is ours.

With us. We reserve your balance and send the refund to the route that collected the payment. This is where refund.created reaches you.
With the customer’s bank, wallet, or card issuer. We report refund.paid when the money has left us. How long it then takes to appear in the customer’s account is set by their bank, not by us.

Tell customers the second stage exists. A refund.paid webhook is not the same as money the customer can see.

Payment method	When the customer sees the money
Card (USD and NGN)	5 to 7 working days
Bank transfer (NGN)	1 to 7 working days
Mobile money	1 to 7 working days
Crypto	As soon as the network confirms the transaction

These windows start from refund.paid, not from the moment you created the refund. They are what the banks and wallets take, so quote them as a range and not as a promise.

What a refund costs you

You request the amount in the settlement currency, the currency the payment paid you in. The customer gets back the currency they paid, converted at the rate the original payment settled at.
If the payment converted currencies, you fund the conversion at today’s rate. Buying back the customer’s currency can cost more or less than you were paid, and the difference is yours. If we sold you a guaranteed rate on the payment, that rate stands and the movement is ours.
Fees already charged are not returned. Our processing fee on the original payment stays charged, and on Connect the platform fee is not reversed either. See Refunds on Connect charges.
fee_bearer decides who absorbs any fee the refund itself carries: org (you) or customer (taken out of what the customer receives). If you omit it, your account’s fee handling decides. refund_fee_amount is "0" when no refund fee applies.

Crypto refunds

For a payment made in crypto, pass refund_address, the wallet the money goes back to, on the same network as the original payment. Without it the refund is refused.

{ "charge_id": "ch_...", "reference": "refund_9878", "refund_address": "0xabc...def" }

A crypto refund cannot be recalled. Check the address with the customer before you create it.

When a refund is refused

Status and `error_code`	Message	What happened	What to do
`400` `BAD_REQUEST`	Refunds are not supported for this charge	The route that collected the payment cannot return money.	Send a payout instead.
`400` `BAD_REQUEST`	Charge is not refundable in status `...`	The payment never completed, or it is already refunded.	Read the payment’s status and `is_refundable`.
`400` `BAD_REQUEST`	Insufficient balance to refund	Your balance cannot fund the refund. Nothing was written and nothing moved.	Fund the balance, then create the refund again.
`400` `BAD_REQUEST`	Refund amount `...` exceeds refundable balance	The `amount` is more than the payment can return.	Ask for the remaining amount or less.
`400` `BAD_REQUEST`	Refunds are not supported at the moment	Refunds are turned off across the platform.	Nothing on your side. Contact support.
`409` `CONFLICT`	A refund already exists for this charge	The payment already carries a refund that did not fail.	Retrieve it instead of creating another.
`409` `CONFLICT`	Refund reference already exists	You reused a `reference`.	Send a new one.

From the dashboard

You can refund without writing code. Open Transactions, click the payment, and choose Issue a refund. The button is offered on any payment with is_refundable: true, with the same one exception as the API. It appears in the same list and fires the same webhooks.

Testing

In the sandbox, force an outcome with simulated_outcome:

{ "charge_id": "ch_...", "reference": "refund_test", "simulated_outcome": "success" }

Values are success and failed. Sandbox refunds move no real money.

Next steps

The payment object: find a payment’s charge_id and is_refundable.
The refund object: every field on a refund.
Refunds on Connect charges: which balance a refund debits on a split payment.
Set up webhooks: receive refund.* events.

Get Started

Products & pricing

Subscriptions

Customer portal

Payments

Payouts

Dashboard

Developer Portal

CLI

For You and Your Customers

Issue a refund

Before you start

What can be refunded

Supported refund currencies

Steps

How long a refund takes

What a refund costs you

Crypto refunds

When a refund is refused

From the dashboard

Testing

Next steps

​Before you start

​What can be refunded

​Supported refund currencies

​Steps

​How long a refund takes

​What a refund costs you

​Crypto refunds

​When a refund is refused

​From the dashboard

​Testing

​Next steps

Before you start

What can be refunded

Supported refund currencies

Steps

How long a refund takes

What a refund costs you

Crypto refunds

When a refund is refused

From the dashboard

Testing

Next steps