# Chargebacks

A chargeback occurs when a cardholder's bank reverses a payment and reclaims the funds on the customer's behalf. ODUS does not automatically detect chargebacks from your payment gateway — you must record them manually when your bank or processor notifies you.

Once recorded, the payment is marked as chargebacked and you can optionally restrict the customer from making further payments.

## Prerequisites

* A valid payment ID (`pay_...`) for the payment that received the chargeback.
* A secret API key with the `payment:record_chargeback` permission, if recording via the API.

## Record a chargeback via the API

Send a [`POST /v2/payments/{id}/chargebacks`](https://docs.odus.com/docs/api/core/v2/payment-controller-create-chargeback) request with the payment ID in the path.

An empty body is valid when you only want to mark the payment as chargebacked without applying any customer restrictions:

Minimal request

```
{}
```

warning

Even with an empty body, the customer is blacklisted while [**Blacklist customer on chargeback**](https://docs.odus.com/docs/guides/dashboard/merchant-configuration.md#blacklist-customer-on-chargeback) is on, which it is by default. To record a chargeback without blacklisting the customer, turn that setting off first.

After a successful request, the payment's `isChargebacked` field is set to `true` and `chargebackRecordedAt` is set to the current timestamp.

note

Recording a chargeback does not prevent further operations on the payment. You can still capture or reverse it after recording a chargeback.

important

If the charged-back payment settled a subscription — either its setup payment or a recurring renewal — ODUS cancels that subscription **immediately** when the chargeback is recorded. The subscription moves to `cancelled` and automatic billing is turned off. This happens for every recorded chargeback on a subscription payment, independently of the restriction options described below.

Invoice statuses are not changed by the chargeback itself: an already-settled invoice stays `paid`, and any still-open invoice is left to its own payment lifecycle rather than being voided here.

### Blacklist the customer

Blacklisting blocks all future payments by the customer based on their email address — including all products, recurring charges, and new customer-initiated payments.

Blacklisting also cancels immediately every other active subscription of every customer with that email, not only the one tied to the charged-back payment. See [The Blacklist](https://docs.odus.com/docs/guides/customers/customer-restrictions.md#the-blacklist).

By default, recording a chargeback blacklists the customer, however the chargeback is recorded. This is the [**Blacklist customer on chargeback**](https://docs.odus.com/docs/guides/dashboard/merchant-configuration.md#blacklist-customer-on-chargeback) setting in your merchant configuration, and it is on unless you turn it off.

If you turn the setting off, set `blacklistCustomer` to `true` in the request to blacklist the customer for that chargeback:

Record chargeback and blacklist customer

```
{

  "blacklistCustomer": true

}
```

warning

While **Blacklist customer on chargeback** is on, `blacklistCustomer` is ignored. Sending `false` does not stop the customer from being blacklisted, and the request does not fail.

### Apply fine-grained restrictions

Use the `customerRestrictions` object for more targeted control over what the customer can and cannot do after the chargeback.

Set `restrictCit` to block customer-initiated payments, `restrictMit` to block merchant-initiated payments, and `restrictReason` to record a human-readable explanation. See the [`POST /v2/payments/{id}/chargebacks`](https://docs.odus.com/docs/api/core/v2/payment-controller-create-chargeback) reference for the full parameter list.

Record chargeback with fine-grained restrictions

```
{

  "customerRestrictions": {

    "restrictMit": true,

    "restrictCit": false,

    "restrictReason": "Chargeback filed by customer on 2024-03-15"

  }

}
```

You can combine `blacklistCustomer` and `customerRestrictions` in the same request.

important

`blacklistCustomer` and `customerRestrictions` are independent mechanisms. Blacklisting is based on the customer's email and blocks payments across the platform. Customer restrictions are scoped to your merchant account and offer finer-grained control.

### Response

The payment object in the response includes:

* `isChargebacked: true`
* `chargebackRecordedAt`: the timestamp when the chargeback was recorded.

If restrictions were applied, the `customer` object embedded in the payment will also reflect the updated `restrictMit`, `restrictCit`, and `isRestricted` fields.

tip

Restrictions can also be managed independently of a chargeback using the [`POST /v2/customers/{id}/restrictions`](https://docs.odus.com/docs/api/core/v2/customer-controller-manage-restrictions) endpoint. This is useful if you need to update or remove restrictions at a later time.

## Record a chargeback via the Dashboard

1. In the Dashboard, go to **Payments**.

2. Find and open the payment that received the chargeback.

3. Click **Record chargeback**.

4. In the dialog, configure the available options:

   <!-- -->

   * **Restrict Recurring Payments** — blocks the customer's future recurring (merchant-initiated) charges, so any of their *other* active subscriptions stop renewing and lapse at the end of their current billing period. This is separate from the automatic cancellation above: the subscription tied to the charged-back payment is always cancelled immediately, regardless of this option.
   * **Restrict Customer Initiated Payments** — blocks future customer-initiated payments, such as upsells and one-off purchases.
   * **Restrict reason** — an optional note stored on the customer record.

5. Click **Submit**.

The dialog does not offer to blacklist the customer. While [**Blacklist customer on chargeback**](https://docs.odus.com/docs/guides/dashboard/merchant-configuration.md#blacklist-customer-on-chargeback) is on, which it is by default, every customer whose chargeback you record is blacklisted.

note

The **Record chargeback** action is only available for payments that have not already been chargebacked.

## View chargebacked payments

In the **Payments** list, use the display status filter and select **Chargeback** to show only payments with a recorded chargeback.