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 restrictions:

Minimal request — record only

{}

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.

Blacklist the customer

Set blacklistCustomer to true to add the customer to the blacklist in addition to recording the chargeback. This blocks all future payments by the customer based on their email address — including all products, recurring charges, and new customer-initiated payments.

Record chargeback and blacklist customer

{
  "blacklistCustomer": true
}

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:
   • Blacklist customer — blocks all future payments by this customer based on their email address.
   • Restrict Recurring Payments — blocks future recurring subscription charges and cancels active subscriptions at the end of their current billing period.
   • 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.

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.