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 [e-mail].

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/v1/alerts/

Authorization

ApiKey

Query parameters

Response

200

OK

Body

application/json

items*Items

count*Count

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/alerts/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

{
  "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": "2025-02-05T17:06:59.315Z",
      "action_required_deadline": "2025-02-05T17:06:59.315Z",
      "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": "2025-02-05T17:06:59.315Z",
      "updated_at": "2025-02-05T17:06:59.315Z",
      "links": [
        {
          "rel": "text",
          "uri": "text"
        }
      ]
    }
  ],
  "count": 1
}

Get Alert

GET/v1/alerts/{alert_id}

Authorization

ApiKey

Path parameters

alert_id*Alert Id

Response

200

OK

Body

application/json

id*Id

organisation_id*Organisation Id

ChargebackStop Organisation ID. When the API authorisation key is assigned to multiple organisations, this field is used to identify the organisation that the alert belongs to.

merchant_id*Merchant Id

ChargebackStop Merchant ID. Used to identify the merchant account within ChargebackStop organisation.

enrolment_type*Type

Type of the alert network this alert was provided by.

ETHOCA_ALERTVERIFI_RDR

status*Status

Status of the alert within ChargebackStop. ACTION_REQUIRED means that ChargebackStop is waiting for the user to take action (either via PATCH /v1/alerts/{alert_id} API request or the dashboard). RESOLVED means that the alert has been resolved and any attempts to action on it will fail.

ACTION_REQUIREDRESOLVED

chargeback_reason_code*Chargeback Reason Code

Chargeback reason code of the disputed transaction as provided by the card scheme.

stringnull

transaction_amount_in_cents*Transaction Amount In Cents

Amount of the disputed transaction in cents. For example, if the transaction was USD 100, the value is 10000.

integernull

transaction_currency_code*Transaction Currency Code

ISO 4217 currency code of the transaction.

stringnull

transaction_authorised_at*Transaction Authorised At

Date and (optionally) time when the disputed transaction was authorised.

string (date-time)null

action_required_deadline*Action Required Deadline

Date and time when the user is expected to take action on this alert.

string (date-time)null

transaction_authorisation_code*Transaction Authorisation Code

Disputed transaction's authorisation code assigned by issuing bank. It's not unique, and sometimes transactions made in close time range get the same authorisation code.

stringnull

transaction_acquirer_reference_number*Transaction Acquirer Reference Number

Disputed transaction's Acquirer Reference Number (ARN) is a unique identifier assigned by the acquirer to the transaction and is used to identify the transaction between card schemes, issuers, and processors.

stringnull

transaction_statement_descriptor*Transaction Statement Descriptor

Disputed transaction's statement descriptor.

stringnull

transaction_card_bin*Transaction Card Bin

BIN is the first 6-8 digits of the card number that was used to make the disputed transaction. Sometimes known as IIN.

stringnull

transaction_card_last4*Transaction Card Last4

Last 4 digits of the card number that was used to make the disputed transaction.

stringnull

transaction_card_scheme*any of

Card scheme of the disputed transaction.

CardSchemenull

transaction_card_issuer*Transaction Card Issuer

Issuer of the card that was used to make the disputed transaction.

stringnull

transaction_refund_outcome*any of

Outcome of the refund attempt for the disputed transaction. null when status is ACTION_REQUIRED.

RefundOutcomenull

transaction_network_id*Transaction Network Id

Unique identifier for the transaction assigned by the card scheme on authorisation. Available for successful VISA, Mastercard, and American Express transactions.

stringnull

subscription_cancel_outcome*any of

Outcome of the subscription cancellation attempt for the disputed transaction. null when status is ACTION_REQUIRED or when the alert is not matched with any subscription.

CancellationOutcomenull

note*Note

User's note about this alert. Used to provide additional context to other team members within the organisation. Contains the same contents as 'Notes' field in the dashboard.

stringnull

created_at*Created At

Date and time when the alert was created in ChargebackStop platform.

string (date-time)null

updated_at*Updated At

Date and time when the alert was last updated in ChargebackStop platform.

string (date-time)null

links*Links

List of links related to this alert.

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/alerts/{alert_id}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

{
  "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": "2025-02-05T17:06:59.315Z",
  "action_required_deadline": "2025-02-05T17:06:59.315Z",
  "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": "2025-02-05T17:06:59.315Z",
  "updated_at": "2025-02-05T17:06:59.315Z",
  "links": [
    {
      "rel": "text",
      "uri": "text"
    }
  ]
}

Update Alert

PATCH/v1/alerts/{alert_id}

Authorization

ApiKey

Path parameters

alert_id*Alert Id

Body

application/json

actionany of

UpdateActionnull

noteNote

stringnull

Response

200

OK

Body

application/json

id*Id

organisation_id*Organisation Id

ChargebackStop Organisation ID. When the API authorisation key is assigned to multiple organisations, this field is used to identify the organisation that the alert belongs to.

merchant_id*Merchant Id

ChargebackStop Merchant ID. Used to identify the merchant account within ChargebackStop organisation.

enrolment_type*Type

Type of the alert network this alert was provided by.

ETHOCA_ALERTVERIFI_RDR

status*Status

Status of the alert within ChargebackStop. ACTION_REQUIRED means that ChargebackStop is waiting for the user to take action (either via PATCH /v1/alerts/{alert_id} API request or the dashboard). RESOLVED means that the alert has been resolved and any attempts to action on it will fail.

ACTION_REQUIREDRESOLVED

chargeback_reason_code*Chargeback Reason Code

Chargeback reason code of the disputed transaction as provided by the card scheme.

stringnull

transaction_amount_in_cents*Transaction Amount In Cents

Amount of the disputed transaction in cents. For example, if the transaction was USD 100, the value is 10000.

integernull

transaction_currency_code*Transaction Currency Code

ISO 4217 currency code of the transaction.

stringnull

transaction_authorised_at*Transaction Authorised At

Date and (optionally) time when the disputed transaction was authorised.

string (date-time)null

action_required_deadline*Action Required Deadline

Date and time when the user is expected to take action on this alert.

string (date-time)null

transaction_authorisation_code*Transaction Authorisation Code

Disputed transaction's authorisation code assigned by issuing bank. It's not unique, and sometimes transactions made in close time range get the same authorisation code.

stringnull

transaction_acquirer_reference_number*Transaction Acquirer Reference Number

Disputed transaction's Acquirer Reference Number (ARN) is a unique identifier assigned by the acquirer to the transaction and is used to identify the transaction between card schemes, issuers, and processors.

stringnull

transaction_statement_descriptor*Transaction Statement Descriptor

Disputed transaction's statement descriptor.

stringnull

transaction_card_bin*Transaction Card Bin

BIN is the first 6-8 digits of the card number that was used to make the disputed transaction. Sometimes known as IIN.

stringnull

transaction_card_last4*Transaction Card Last4

Last 4 digits of the card number that was used to make the disputed transaction.

stringnull

transaction_card_scheme*any of

Card scheme of the disputed transaction.

CardSchemenull

transaction_card_issuer*Transaction Card Issuer

Issuer of the card that was used to make the disputed transaction.

stringnull

transaction_refund_outcome*any of

Outcome of the refund attempt for the disputed transaction. null when status is ACTION_REQUIRED.

RefundOutcomenull

transaction_network_id*Transaction Network Id

Unique identifier for the transaction assigned by the card scheme on authorisation. Available for successful VISA, Mastercard, and American Express transactions.

stringnull

subscription_cancel_outcome*any of

Outcome of the subscription cancellation attempt for the disputed transaction. null when status is ACTION_REQUIRED or when the alert is not matched with any subscription.

CancellationOutcomenull

note*Note

User's note about this alert. Used to provide additional context to other team members within the organisation. Contains the same contents as 'Notes' field in the dashboard.

stringnull

created_at*Created At

Date and time when the alert was created in ChargebackStop platform.

string (date-time)null

updated_at*Updated At

Date and time when the alert was last updated in ChargebackStop platform.

string (date-time)null

links*Links

List of links related to this alert.

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/alerts/{alert_id}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "action": "REFUND"
    }),
});
const data = await response.json();

Response

200

{
  "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": "2025-02-05T17:06:59.315Z",
  "action_required_deadline": "2025-02-05T17:06:59.315Z",
  "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": "2025-02-05T17:06:59.315Z",
  "updated_at": "2025-02-05T17:06:59.315Z",
  "links": [
    {
      "rel": "text",
      "uri": "text"
    }
  ]
}