Alerts API

Reference for ChargebackStop REST API.

Capabilities

ChargebackStop REST API allows:

• Listing all alerts in the organisation

• Getting individual alert by its unique ID

• Actioning an alert

The API uses JSON both as an input and output data format.

Availability

ChargebackStop API is currently in private beta. If you are interested in exploring it, please contact us at [email protected].

Actioning alerts

Every alert with ACTION_REQUIRED status is expected to be actioned by the user. The deadline for actioning an alert is represented by the action_required_deadline field in the alert object, however we recommend sending your desired action as soon as possible. After actioning, the alert status is moved into RESOLVED, and cannot be changed anymore.

Behind the scenes, actioning the alert updates the alert provider (e.g. Ethoca) with the outcome. This allows them to stop the dispute if the user's action was to pro-actively refund the transaction, or send the dispute through if you chose to fight it.

For actions that refund the transaction, if your ChargebackStop merchant account is integrated with a payments provider (e.g. Stripe), we will automatically refund the payment. You can also choose to cancel the subscription associated with the payment

The update alert endpoint takes action parameter. It can be one of four values:

• REFUND

• CANCEL

• REFUND_AND_CANCEL

• ACCEPT_DISPUTE

Let's explore how each of these values works.

REFUND

All of the below actions are performed:

1. We let the alert provider know that you refunded the alert.

2. If your Merchant account is integrated with a payment provider, we will automatically refund the payment.

CANCEL

All of the below actions are performed:

1. We let the alert provider know that you did not refund the alert.

2. If your Merchant account is integrated with a payment provider and there's a subscription associated with the alert, we will automatically cancel it.

REFUND AND CANCEL

All of the below actions are performed:

1. We let the alert provider know that you refunded the alert.

2. If your Merchant account is integrated with a payment provider, we will automatically refund the payment.

3. If your Merchant account is integrated with a payment provider and there's a subscription associated with the alert, we will automatically cancel it.

ACCEPT_DISPUTE

All of the below actions are performed:

1. We let the alert provider know that you did not refund the alert.

API keys

In order to create an API key:

1. Open your ChargebackStop dashboard

2. Select "Settings" from the left-hand menu

3. Select "API Keys" from the tabs at the top

4. Click the "Create API key" button

   1. In the newly opened form enter your key's name. It's only used for your reference.

   2. Add expiration date if you want the key to stop working at some point in the future. If you want to use the key indefinitely, please leave this field empty.

5. Click "Create key"

6. You will see your API key in the green success box right under the tabs. You will only be able to see it once, so make sure to copy it (including the cbs_prefix) and save it securely. If you loose your key, you will need to revoke it and create a new one.

API documentation

Get Alerts

get

Authorizations

ApiKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

statusany ofOptional

string · enumOptionalPossible values:

or

nullOptional

sortany ofOptional

Field to sort by

Default: -alert_received_at

string · enumOptionalPossible values:

or

nullOptional

limitinteger · min: 1OptionalDefault: 100

offsetintegerOptionalDefault: 0

Responses

200

OK

application/json

get

/v1/alerts/

HTTPcURLJavaScriptPython

GET /v1/alerts/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "items": [
    {
      "id": "text",
      "organisation_id": "text",
      "merchant_id": "text",
      "enrolment_type": "ETHOCA_ALERT",
      "status": "ACTION_REQUIRED",
      "chargeback_reason_code": "text",
      "transaction_amount_in_cents": 1,
      "transaction_currency_code": "text",
      "transaction_authorised_at": "2026-02-04T02:42:45.024Z",
      "action_required_deadline": "2026-02-04T02:42:45.024Z",
      "transaction_authorisation_code": "text",
      "transaction_acquirer_reference_number": "text",
      "transaction_statement_descriptor": "text",
      "transaction_card_bin": "text",
      "transaction_card_last4": "text",
      "transaction_card_scheme": "VISA",
      "transaction_card_issuer": "text",
      "transaction_refund_outcome": "REFUNDED",
      "transaction_network_id": "text",
      "subscription_cancel_outcome": "CANCELLED",
      "note": "text",
      "created_at": "2026-02-04T02:42:45.024Z",
      "updated_at": "2026-02-04T02:42:45.024Z",
      "links": [
        {
          "rel": "text",
          "uri": "text"
        }
      ]
    }
  ],
  "count": 1
}

Get Alert

get

Authorizations

ApiKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

alert_idstringRequired

Responses

200

OK

application/json

get

/v1/alerts/{alert_id}

HTTPcURLJavaScriptPython

GET /v1/alerts/{alert_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "id": "text",
  "organisation_id": "text",
  "merchant_id": "text",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "ACTION_REQUIRED",
  "chargeback_reason_code": "text",
  "transaction_amount_in_cents": 1,
  "transaction_currency_code": "text",
  "transaction_authorised_at": "2026-02-04T02:42:45.024Z",
  "action_required_deadline": "2026-02-04T02:42:45.024Z",
  "transaction_authorisation_code": "text",
  "transaction_acquirer_reference_number": "text",
  "transaction_statement_descriptor": "text",
  "transaction_card_bin": "text",
  "transaction_card_last4": "text",
  "transaction_card_scheme": "VISA",
  "transaction_card_issuer": "text",
  "transaction_refund_outcome": "REFUNDED",
  "transaction_network_id": "text",
  "subscription_cancel_outcome": "CANCELLED",
  "note": "text",
  "created_at": "2026-02-04T02:42:45.024Z",
  "updated_at": "2026-02-04T02:42:45.024Z",
  "links": [
    {
      "rel": "text",
      "uri": "text"
    }
  ]
}

Update Alert

patch

Authorizations

ApiKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

alert_idstringRequired

Body

application/json

actionany ofOptional

string · enumOptionalPossible values:

or

nullOptional

noteany ofOptional

stringOptional

or

nullOptional

Responses

200

OK

application/json

patch

/v1/alerts/{alert_id}

HTTPcURLJavaScriptPython

PATCH /v1/alerts/{alert_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "action": "REFUND",
  "note": "text"
}

200

OK

{
  "id": "text",
  "organisation_id": "text",
  "merchant_id": "text",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "ACTION_REQUIRED",
  "chargeback_reason_code": "text",
  "transaction_amount_in_cents": 1,
  "transaction_currency_code": "text",
  "transaction_authorised_at": "2026-02-04T02:42:45.024Z",
  "action_required_deadline": "2026-02-04T02:42:45.024Z",
  "transaction_authorisation_code": "text",
  "transaction_acquirer_reference_number": "text",
  "transaction_statement_descriptor": "text",
  "transaction_card_bin": "text",
  "transaction_card_last4": "text",
  "transaction_card_scheme": "VISA",
  "transaction_card_issuer": "text",
  "transaction_refund_outcome": "REFUNDED",
  "transaction_network_id": "text",
  "subscription_cancel_outcome": "CANCELLED",
  "note": "text",
  "created_at": "2026-02-04T02:42:45.024Z",
  "updated_at": "2026-02-04T02:42:45.024Z",
  "links": [
    {
      "rel": "text",
      "uri": "text"
    }
  ]
}