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 if recording via the API.

Record a chargeback via the API

Send a POST /payments/{id}/record-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 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.

By default, recording a chargeback blacklists the customer, however the chargeback is recorded. This is the 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 /payments/{id}/record-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 /customers/{id}/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 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.