1 of 43

ChargebackStop | DOCS

Welcome

ChargebackStop gives you a single platform to prevent chargebacks before they happen. We sit between you and the card networks, handling the integration, automation, and resolution logic so you can focus on your business.

This documentation covers everything you need to get set up, configure your products, and start preventing disputes.

Every chargeback has a lifecycle. We intervene at three different stages, each with its own protection layer. Use one, two, or all three depending on your risk profile and goals.

Digital Receipts push rich order data to cardholders and their banks in real time. When a cardholder views a transaction in their banking app or a bank agent opens a dispute portal, they see subscription details, itemised breakdowns, delivery tracking, and more, before a dispute is ever raised.

Platform

Digital Receipts

Introduction

Digital Receipts let you send additional order information to cardholders and their banks, including subscription details, itemised breakdowns, in-flight refunds, and more. When implemented, they reduce cardholder confusion, help banks better understand charges before raising a dispute, and ultimately lower your chargeback rate.

Cardholder views a transaction

A cardholder opens a transaction in their banking app.

Use cases

B2C subscription products

Display subscription billing cycles to cardholders
Embed deep-links for managing subscriptions or requesting refunds

Merchant of Record PSPs

Surface the details of the sub-merchant that delivered the goods or services

eCommerce brands

Show itemised breakdowns of items ordered, including delivery and tracking status

Intergrating

You may need to perform additional integration work to support Digital Receipts. Depending on your payment processor or CRM, we may need extra information to return data to cardholders and their banks.

During your initial conversations with our team, we'll evaluate which of three paths applies to your setup:

No additional work needed: We can gather enough data from your payment processor, CRM, or eCommerce platform. No work required from your technical team.
Partial order enrichment: We can pull most of the data from your existing integrations, but some additional enrichment is needed from your side.

Systematic Dispute Deflection

Introduction

Systematic Dispute Deflection prevents friendly fraud by proving historic cardholder purchase activity with qualifying data. When a deflection is successful, the dispute is blocked by the card networks before it's raised. You retain the funds, prevent fraud claims (TC40s) from being filed, and reduce your dispute rate.

How it works

Cardholder attempts a dispute

A cardholder contacts their bank to dispute a transaction.

Real-time lookup

The card network performs a real-time lookup against your historical transaction data.

Dispute blocked

If the criteria for deflection are met, the dispute is instantly blocked and never reaches you.

A dispute becomes eligible for deflection when the cardholder has completed at least two previous transactions within 120 to 365 days before the disputed charge. These earlier transactions form the purchase history used to verify legitimacy.

For a deflection to succeed, identifiers unique to the cardholder must match across the disputed transaction and the historic purchase history. Qualifying identifiers include:

IP address
Email address
Device fingerprint
Billing address

At least two identifiers must match, and one of them must be either an IP address or an email address.

Currently, deflection is attempted for the following dispute conditions:

Visa 10.4 — Card Not Present
Mastercard 4814 — Card Not Present

Other conditions may become eligible as the card networks expand their programs.

Systematic Dispute Deflection is powered by two card network solutions. We harmonise both systems into a single unified interface built to scale and support both programs as they evolve. You never need to integrate directly or manage those connections.

Compelling Evidence 3.0 (Visa)
First Party Trust (Mastercard)

Integrating

Systematic Dispute Deflection builds on top of the same data set used for Digital Receipts, in addition to the qualifying data.

Customer's IP address or device fingerprint
Customer's email address

The qualifying data identifiers listed above are mandatory for deflection. If you're setting up Digital Receipts alongside this product, pay close attention to the required fields for Consumer Clarity, First Party Trust, Order Insights, and Compelling Evidence 3.0 during your integration.

Both products share the same underlying data pipeline. Getting your Digital Receipts integration right means Systematic Dispute Deflection works out of the box.

VAMP Ratio Reduction

The is Visa's unified framework for monitoring fraud and dispute levels across merchants. If your VAMP ratio exceeds Visa's thresholds, you risk fines, restrictions, or removal from the network.

is the only tool available that can prevent first-party misuse disputes and remove the associated fraud notices (TC40s) from your VAMP ratio. Chargeback alerts and other prevention tools resolve disputes reactively, but the TC40 has already been filed and still counts against you. Systematic Dispute Deflection blocks the dispute before it's created, and the TC40 is excluded from your VAMP calculation entirely.

Visa introduced VAMP in 2024/25 to replace its previous fragmented monitoring programs with a single framework. It monitors your fraud and dispute activity relative to your transaction volume. If your ratio crosses Visa's thresholds, your acquirer is notified and you may face escalating consequences.

Visa updated the VAMP formula to include all disputes, both fraudulent and non-fraud, rather than fraud-only. This makes first-party misuse (friendly fraud, subscription confusion, unrecognised charges) significantly more important to your ratio than before, and harder to address without the right tooling.

When a cardholder attempts to dispute a transaction, our system checks their purchase history against qualifying identifiers you've provided through Digital Receipts, IP address, email, device fingerprint, and billing address. If the evidence proves prior legitimate activity, the dispute is blocked at the network level.

Chargeback Alerts

Introduction

Chargeback prevention alerts warn you of a dispute before it becomes an official chargeback with your payment service provider. When you receive an alert, you can refund the transaction and avoid the chargeback entirely.

A cardholder contacts their bank to dispute a transaction they made with your business.

As the issuer begins filing the dispute, they check whether you're enrolled to receive alerts (this depends on the card network and issuer).

Alert Providers

Chargeback alerts are powered by Visa and Mastercard. ChargebackStop is an authorized, direct reseller of alert data from both card networks. We handle onboarding, management, and automation so you get full value from alerts without extra overhead.

Ethoca Alerts (Mastercard) covers roughly 95% of Mastercard-related chargebacks and about 40% of Visa-related chargebacks. Learn more here.

Verifi RDR (Visa) covers roughly 95% of Visa-related chargebacks. Learn more here.

When both programs are enabled together, merchants typically see up to 95%* dispute prevention coverage across all Visa and Mastercard transactions.

A note on coverage estimates: The 95% figure reflects what we typically see across our customer portfolio. Your actual coverage depends on issuer spread and cardholder regions. Contact our sales or support team with details about your setup and volume, we can give you a specific estimate before you onboard.

What about Amex & Discover?

Both alert providers offer some coverage for Amex and Discover disputes, but availability depends on your payment processor setup. Reach out to sales or support to confirm what's possible for your configuration.

Enrolments

An enrollment registers your merchant setup with ChargebackStop and the card networks (Visa and Mastercard). You'll likely have more than one enrollment, each merchant account and product requires its own.

Our onboarding and support teams handle all enrollment work and communicate with the card networks on your behalf. No action needed from you.

View your enrollments in your dashboard under Settings > Enrollments.

Ethoca enrollment is descriptor-based. If your descriptor is too generic or already enrolled by another merchant globally across Ethoca's network, the enrollment may need attention. When this happens, our support team will reach out to discuss alternatives — for example, using a more specific descriptor or a different match type. This typically takes 1–2 business days to resolve, after which we resubmit the enrollment.

ChargebackStop manages your enrollments, but if you need to pause, extend, or reduce coverage, contact our support team. They'll gather the required information and make the changes. Depending on what you're changing, there may be a delay while we coordinate with the card networks.

Resolution Rules

Resolution rules tell the system how to handle incoming alerts, whether to refund, dismiss, or escalate for manual review. You can filter by transaction amount, date, reason code, reason category, and more.

Go to Settings > Resolution Rules to create, edit, or delete rules.

Each resolution rule applies to exactly one enrollment. If you have multiple enrollments or merchant accounts, you'll need separate rules for each. This gives you precise control over behavior per merchant account.

Changes to a resolution rule apply only to alerts received after you save. Already-received alerts aren't affected. If you have unresolved alerts that should match a new rule, contact support, we can re-queue them for processing.

If an incoming alert doesn't match any rule, it goes to manual review in the Action Required tab. You'll have up to 48 hours to make a refund decision (timeframe varies by network). After that, the alert is automatically declined.

Ethoca Alerts

Ethoca Alerts cover roughly 95% of Mastercard disputes and 40% of Visa disputes. Alerts can be fully automated or managed individually.

When you receive an alert, you have two options:

Refund the transaction and resolve the alert
Dismiss the alert, skip the refund, and let the chargeback proceed

If you've set up a resolution rule, this happens automatically. Otherwise, the alert appears in your dashboard. You have 48 hours from receipt to provide an outcome. If you don't respond in time, the alert is automatically declined and the chargeback comes through.

Transaction Matching

Our system locates transactions in your account using data received from the card networks. This is the foundation for automation and resolution rules.

Depending on your account agreement, available integrations, and connector quality, we offer either strict matching or soft matching.

With strict matching enabled, every alert from the card network is matched to a transaction in your payment processor, and the refund is confirmed as executed.

If the system can't find a match, someone on our team manually investigates using the alert data and transaction records. If we still can't locate it, you're automatically credited for that alert.

If connector data quality or account configuration prevents strict matching, we fall back to soft matching. The system attempts a best-case match, but if it fails, the alert lands in your dashboard as "Action Required" for manual review.

We try to offer strict matching to as many customers as possible at no extra cost. But some setups make it technically impossible, missing data fields, limited query options, or specific configurations. Examples:

Developer

API documentation

All API endpoints authenticate using bearer tokens (Authorization: Bearer cbs_<token>). There are two types of API key:

Partner key — tied to a partner group; can access resources across all organisations within that group.
Organisation key — tied to a single organisation; can only access resources belonging to that organisation.

The sections below describe which APIs are available to each key type.

Merchants

Manage merchants under your partner account.

This endpoint set is partner-level only. Organisation API keys cannot access these endpoints.

Base URL: https://api.chargebackstop.com/v1/merchants/ Authentication: Bearer token via API key.

Required abilities:

merchants:read for GET endpoints
merchants:write for POST, PATCH, and DELETE endpoints

Access scope model:

Admin partner-group keys can access merchants across all organisations belonging to their partner.
Non-admin partner-group keys can access merchants only in organisations explicitly assigned to their group.
Organisation-level keys receive 401 Unauthorised on all endpoints in this API.

GET /v1/merchants - List merchants

Returns merchants accessible to the authenticated partner-group API key.

API level: Partner-level only Authentication: merchants:read

Query parameters

Parameter

Type

Description

organisation_id

string

Filter by organisation ID

type

string

Filter by merchant type

name

string

Case-insensitive partial match on merchant name

external_id

string

Filter by exact external merchant ID

sort

string

Sort field: name, type, created_at, updated_at; prefix with - for descending

limit

integer

Number of results per page

offset

integer

Number of results to skip

When sort is omitted, results are ordered by created_at descending.

Example request

Example response

POST /v1/merchants - Create merchant

Create a new merchant for an accessible organisation.

API level: Partner-level only Authentication: merchants:write

Request body

Field

Type

Required

Validation

Description

organisation_id

string

Yes

Must be accessible by API key

Organisation that owns the merchant

name

string

Yes

Min length 1

Merchant display name

type

string

Yes

Must be a supported merchant type

Merchant type

external_id

string

Max length 250

Optional external merchant ID

default_representment_service_type

string

PHYSICAL_GOODS, ONLINE_SERVICES, or OFFLINE_SERVICES

Default representment service type. If you do not use ChargebackStop representment/disputes workflows, omit this field.

If you do not use ChargebackStop representment/disputes workflows, skip default_representment_service_type.

Example request

Example response

GET /v1/merchants/{merchant_id} - Get merchant by ID

Retrieve one accessible merchant by ID.

API level: Partner-level only Authentication: merchants:read

URL parameters

Parameter

Type

Description

merchant_id

string

Merchant ID

Example request

Example response

PATCH /v1/merchants/{merchant_id} - Update merchant

Update one accessible merchant.

API level: Partner-level only Authentication: merchants:write

URL parameters

Parameter

Type

Description

merchant_id

string

Merchant ID to update

Request body

At least one field should be provided.

Field

Type

Required

Validation

Description

name

string

Min length 1

Updated merchant name

type

string

Must be a supported merchant type

Updated merchant type

external_id

string or null

Optional

Updated external ID (null clears value)

default_representment_service_type

string or null

PHYSICAL_GOODS, ONLINE_SERVICES, OFFLINE_SERVICES, or null

Updated default representment service type. If you do not use ChargebackStop representment/disputes workflows, omit this field.

Merchant type changes are blocked when related integrations, enrolments, or data providers exist.
Other fields can still be updated when type changes are blocked.
If you do not use ChargebackStop representment/disputes workflows, skip default_representment_service_type.

Example request

Example response

DELETE /v1/merchants/{merchant_id} - Delete merchant

Delete one accessible merchant.

API level: Partner-level only Authentication: merchants:write

URL parameters

Parameter

Type

Description

merchant_id

string

Merchant ID to delete

Deletion is blocked when the merchant has related enrolments or alerts.

Example request

Example response

204 No Content

Common error responses

401 Unauthorised

Returned for invalid or expired API keys, and for organisation-level keys calling this partner-only API.

403 Forbidden (missing ability)

Returned when the API key is valid but missing required ability (merchants:read or merchants:write).

404 Not found

Returned when the merchant is not found.

422 Unprocessable Entity (merchant type change restricted)

422 Unprocessable Entity (merchant deletion restricted)

Other business validation codes you may receive:

Code

Meaning

INVALID_MERCHANT_TYPE

type is not a valid merchant type

INVALID_REPRESENTMENT_SERVICE_TYPE

default_representment_service_type is not valid

MERCHANT_TYPE_CHANGE_RESTRICTED

Requested type change is blocked by related records

MERCHANT_DELETION_RESTRICTED

Merchant cannot be deleted due to related records

Integrating with ChargebackStop

ChargebackStop for Partners has extensive API and webhook capabilities.

To understand how our API and platform work, it helps to learn these terms and their relationships.

Your partner account.

In production, you’ll typically only have one.

An organisation within your partner account.

Integration

Stripe

Do I need to have a Stripe account?

No, we work with all processors and a Stripe integration is not required. Do note, some of our functionality is only available with Stripe currently (billing descriptors etc.)

You can skip manual API key setup by using this magic link that pre-fills all required permissions.

Stripe Integration Instructions

Create a new restricted API key in Stripe (https://dashboard.stripe.com/apikeys) ensuring that all the required permissions (see the full list below) are selected.
1. Follow this link to open the API keys page in Stripe with all of our required permissions pre-filled: Create ChargebackStop key in Stripe
Grab your Stripe account ID from your profile page ().
Login to ChargebackStop and under > Integrations add your Stripe account ID and restricted key.

In order to match network alerts to your Stripe transactions and automate refunds, we need to sync the following data into our system:

→ Payment intents / charges

→ Customers

→ Refunds

→ Subscriptions

→ Payment methods (without card numbers)

→ Last 4 digits of card number

→ BIN

→ Disputes

→ Early fraud notification

Stripe made the decision to not disclose card brand, card last 4, authorisation code, BIN, or ARN for transactions paid for with Link in their API. As a result, If you use Stripe Link as a payment method in your Stripe integration, we won't be able to automatically match alerts to Stripe transactions.

If we cannot match an alert due to multiple matching Link transactions existing, you might still be charged for the alert. This is not a valid creditable scenario recognised by Verifi nor Ethoca.

There are a few suggested options to try and prevent unmatched alerts and potentially being charged for them:

Use Link in wallet mode.
If Stripe Checkout is not used, alternative approaches are available, although these may require some additional configuration. Please reach out to discuss.
Don’t offer Link

If these options don’t work for your specific case, then we can provide you with the opportunity to manually match these. Instead of us automatically resolving as “Not Refunded” we can add these to your “Action Required” queue. This gives you the opportunity to manually action this alert. Reach out to us, should you wish to activate this.

Adyen

We are aware of the fact that this integration guide is quite long. We are happy to run this integration for you in your Adyen account.

To have ChargebackStop team perform the integration process for you, please add our Client Services account ([email protected]) as a user to your Adyen account.

Make sure to include the following permissions.

Accounts

Company account and all associated merchant accounts

Roles

Authorize.net

You don't need Authorize.net account in order to use ChargebackStop. We work with all processors and an Authorize.net integration is not required.

Integrating Authorize.net

ChargebackStop ↔ Authorize.net integration is straightforward.

Log in to your Authorize.net account.
From the top navigation bar, select "Account".
In "Security Settings" section, select "API Credentials & Keys"

In the page that opens, take note of the "API Login ID" value.

If you already use Authorize.net API in other integrations, you'll need to find your Transaction Key in order to integrate with ChargebackStop. If you are confident that you don't use Authorize.net API anywhere you can select "New Transaction Key" at the bottom page, and click "Submit".
Open , and select "Authorize.net" from the "Add provider" dropdown.

In the pop up window that opens, enter:
1. Integration name - this is for your reference purposes only
2. Login ID - API Login ID from step 4.

ChargebackStop will validate your API details, and activate the integration if they are correct.

NMI

ChargebackStop ↔ NMI integration is straightforward.

Log in to your NMI account
Click "My Settings" in the top right corner
Scroll down to "Private Security Keys"

Merchants

Manage merchants under your partner account.

This endpoint set is partner-level only. Organisation API keys cannot access these endpoints.

Base URL: https://api.chargebackstop.com/v1/merchants/ Authentication: Bearer token via API key.

Required abilities:

merchants:read for GET endpoints
merchants:write for POST, PATCH, and DELETE endpoints

Access scope model:

Admin partner-group keys can access merchants across all organisations belonging to their partner.
Non-admin partner-group keys can access merchants only in organisations explicitly assigned to their group.
Organisation-level keys receive 401 Unauthorised on all endpoints in this API.

GET /v1/merchants - List merchants

Returns merchants accessible to the authenticated partner-group API key.

API level: Partner-level only Authentication: merchants:read

Query parameters

Parameter

Type

Description

organisation_id

string

Filter by organisation ID

type

string

Filter by merchant type

name

string

Case-insensitive partial match on merchant name

external_id

string

Filter by exact external merchant ID

sort

string

Sort field: name, type, created_at, updated_at; prefix with - for descending

limit

integer

Number of results per page

offset

integer

Number of results to skip

When sort is omitted, results are ordered by created_at descending.

Example request

curl -X GET "https://api.chargebackstop.com/v1/merchants/?limit=20&offset=0&sort=-created_at" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "items": [
    {
      "id": "mrch_abc123",
      "organisation_id": "org_xyz456",
      "name": "Acme Stripe EU",
      "type": "STRIPE",
      "external_id": "acct_eu_001",
      "default_representment_service_type": "PHYSICAL_GOODS",
      "created_at": "2026-02-10T09:30:00Z",
      "updated_at": "2026-02-10T09:30:00Z",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/merchants/mrch_abc123"
        }
      ]
    },
    {
      "id": "mrch_def789",
      "organisation_id": "org_xyz456",
      "name": "Acme Adyen UK",
      "type": "ADYEN",
      "external_id": null,
      "default_representment_service_type": null,
      "created_at": "2026-02-08T15:12:44Z",
      "updated_at": "2026-02-08T15:12:44Z",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/merchants/mrch_def789"
        }
      ]
    }
  ],
  "count": 2
}

POST /v1/merchants - Create merchant

Create a new merchant for an accessible organisation.

API level: Partner-level only Authentication: merchants:write

Request body

Field

Type

Required

Validation

Description

organisation_id

string

Yes

Must be accessible by API key

Organisation that owns the merchant

name

string

Yes

Min length 1

Merchant display name

type

string

Yes

Must be a supported merchant type

Merchant type

external_id

string

Max length 250

Optional external merchant ID

default_representment_service_type

string

PHYSICAL_GOODS, ONLINE_SERVICES, or OFFLINE_SERVICES

Default representment service type. If you do not use ChargebackStop representment/disputes workflows, omit this field.

If you do not use ChargebackStop representment/disputes workflows, skip default_representment_service_type.

Example request

curl -X POST "https://api.chargebackstop.com/v1/merchants/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_xyz456",
    "name": "Acme Stripe US",
    "type": "STRIPE",
    "external_id": "acct_us_002",
    "default_representment_service_type": "PHYSICAL_GOODS"
  }'

Example response

{
  "id": "mrch_new123",
  "organisation_id": "org_xyz456",
  "name": "Acme Stripe US",
  "type": "STRIPE",
  "external_id": "acct_us_002",
  "default_representment_service_type": "PHYSICAL_GOODS",
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:00:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/merchants/mrch_new123"
    }
  ]
}

GET /v1/merchants/{merchant_id} - Get merchant by ID

Retrieve one accessible merchant by ID.

API level: Partner-level only Authentication: merchants:read

URL parameters

Parameter

Type

Description

merchant_id

string

Merchant ID

Example request

curl -X GET "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "id": "mrch_abc123",
  "organisation_id": "org_xyz456",
  "name": "Acme Stripe EU",
  "type": "STRIPE",
  "external_id": "acct_eu_001",
  "default_representment_service_type": "PHYSICAL_GOODS",
  "created_at": "2026-02-10T09:30:00Z",
  "updated_at": "2026-02-16T09:05:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/merchants/mrch_abc123"
    }
  ]
}

PATCH /v1/merchants/{merchant_id} - Update merchant

Update one accessible merchant.

API level: Partner-level only Authentication: merchants:write

URL parameters

Parameter

Type

Description

merchant_id

string

Merchant ID to update

Request body

At least one field should be provided.

Field

Type

Required

Validation

Description

name

string

Min length 1

Updated merchant name

type

string

Must be a supported merchant type

Updated merchant type

external_id

string or null

Optional

Updated external ID (null clears value)

default_representment_service_type

string or null

PHYSICAL_GOODS, ONLINE_SERVICES, OFFLINE_SERVICES, or null

Updated default representment service type. If you do not use ChargebackStop representment/disputes workflows, omit this field.

Merchant type changes are blocked when related integrations, enrolments, or data providers exist.
Other fields can still be updated when type changes are blocked.
If you do not use ChargebackStop representment/disputes workflows, skip default_representment_service_type.

Example request

curl -X PATCH "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Stripe Europe",
    "external_id": "acct_eu_010",
    "default_representment_service_type": "ONLINE_SERVICES"
  }'

Example response

{
  "id": "mrch_abc123",
  "organisation_id": "org_xyz456",
  "name": "Acme Stripe Europe",
  "type": "STRIPE",
  "external_id": "acct_eu_010",
  "default_representment_service_type": "ONLINE_SERVICES",
  "created_at": "2026-02-10T09:30:00Z",
  "updated_at": "2026-02-16T12:10:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/merchants/mrch_abc123"
    }
  ]
}

DELETE /v1/merchants/{merchant_id} - Delete merchant

Delete one accessible merchant.

API level: Partner-level only Authentication: merchants:write

URL parameters

Parameter

Type

Description

merchant_id

string

Merchant ID to delete

Deletion is blocked when the merchant has related enrolments or alerts.

Example request

curl -X DELETE "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \
  -H "Authorization: Bearer <api_key>"

Example response

204 No Content

Common error responses

401 Unauthorised

Returned for invalid or expired API keys, and for organisation-level keys calling this partner-only API.

{
  "errors": [
    {
      "code": "UNAUTHORISED",
      "message": "Unauthorised"
    }
  ]
}

403 Forbidden (missing ability)

Returned when the API key is valid but missing required ability (merchants:read or merchants:write).

{
  "errors": [
    {
      "code": "FORBIDDEN",
      "message": "Forbidden"
    }
  ]
}

404 Not found

Returned when the merchant is not found.

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "Not found"
    }
  ]
}

422 Unprocessable Entity (merchant type change restricted)

{
  "errors": [
    {
      "code": "MERCHANT_TYPE_CHANGE_RESTRICTED",
      "message": "Cannot change merchant type when integrations are associated with this merchant."
    }
  ]
}

422 Unprocessable Entity (merchant deletion restricted)

{
  "errors": [
    {
      "code": "MERCHANT_DELETION_RESTRICTED",
      "message": "Merchant cannot be deleted because it has active enrollments. Please contact support if you need to delete this merchant."
    }
  ]
}

Other business validation codes you may receive:

Code

Meaning

INVALID_MERCHANT_TYPE

type is not a valid merchant type

INVALID_REPRESENTMENT_SERVICE_TYPE

default_representment_service_type is not valid

MERCHANT_TYPE_CHANGE_RESTRICTED

Requested type change is blocked by related records

MERCHANT_DELETION_RESTRICTED

Merchant cannot be deleted due to related records

Organisations

Manage organisations under your partner account.

This endpoint set is partner-level only. Organisation API keys cannot access these endpoints.

Base URL: https://api.chargebackstop.com/v1/organisations/ Authentication: Bearer token via API key.

Required abilities:

organisations:read for GET endpoints
organisations:write for POST, PATCH, and DELETE endpoints

Access scope model:

Admin partner-group keys can access all organisations belonging to their partner.
Non-admin partner-group keys can access only organisations explicitly assigned to their group.
Organisation-level keys receive 401 Unauthorised on all endpoints in this API.

Returns organisations accessible to the authenticated partner-group API key.

Because organisation mode must match partner mode on create, results for a given partner key are expected to be single-mode (LIVE or TEST).

API level: Partner-level only Authentication: organisations:read

Parameter

Type

Description

Create a new organisation for the authenticated partner.

API level: Partner-level only Authentication: organisations:write

Field

Type

Required

Validation

Description

Retrieve one accessible organisation by ID.

API level: Partner-level only Authentication: organisations:read

Parameter

Type

Description

Update organisation details.

API level: Partner-level only Authentication: organisations:write

Parameter

Type

Description

Field

Type

Required

Validation

Description

Delete an organisation if it has no related dependent records.

API level: Partner-level only Authentication: organisations:write

Parameter

Type

Description

204 No Content

Returned for invalid/expired API keys, and for organisation-level keys calling this partner-only API.

Returned when the API key is valid but missing required ability (organisations:read or organisations:write).

Returned when the organisation does not exist or is outside the key's accessible scope.

Used for business-rule and schema validation errors.

Example: business validation (delete blocked):

Other business validation codes you may receive:

Code

Meaning

Schema validation errors are also returned as 422 with VALIDATION_* codes (for example, invalid field values or empty name).

Alerts

List, retrieve, and action network alerts for accessible organisations.

Verifi RDR alerts are resolved automatically. Verifi RDR alerts arrive with status RESOLVED or INVALID and do not require actioning. The ACTION_REQUIRED status and the PATCH endpoint for actioning alerts apply to Ethoca alerts only.

Ethoca alerts in ACTION_REQUIRED status must be actioned. Refunding the transaction alone is not enough to prevent a chargeback. You must also action the alert using the PATCH endpoint so that Ethoca is notified and can stop the dispute. Unactioned alerts provide no value — the chargeback will proceed regardless of whether you refunded the customer. If you have resolution rules configured, matching alerts are resolved automatically. In rare cases, an alert may still appear as ACTION_REQUIRED if the system cannot match the alert to a transaction or cannot process the refund.

Base URL: https://api.chargebackstop.com/v1/alerts/

Authentication: Bearer token via API key.

Required abilities:

alerts:read for GET endpoints
alerts:write for PATCH endpoints

Access scope model:

Organisation-level keys can access alerts for their own organisation only.
Admin partner-group keys can access alerts across all organisations for their partner.
Non-admin partner-group keys can access alerts only for organisations assigned to their group.

Returns a paginated list of alerts accessible to the authenticated key.

API level: Organisation-level and partner-level Authentication: alerts:read

Parameter

Type

Description

Code

Description

If both alert_received_at_gte and alert_received_at_lte are sent, alert_received_at_gte must be less than or equal to alert_received_at_lte.
Default sort order is newest alert received first (-alert_received_at).

Returns one alert if it is visible to the authenticated key.

API level: Organisation-level and partner-level Authentication: alerts:read

Parameter

Type

Description

Code

Description

The same eligibility rules as list alerts apply.
Non-existent alerts return 404 Not found.

Updates the alert note and/or actions the alert.

API level: Organisation-level and partner-level Authentication: alerts:write

Parameter

Type

Description

All fields are optional.

Field

Type

Required

Description

Code

Description

This endpoint applies to Ethoca alerts only. Verifi RDR alerts are resolved automatically and cannot be actioned.
If note is provided, it is saved on the alert.
If action is omitted, only the note is updated.

Error responses use this shape:

Rulesets - developer preview

Create and manage resolution rulesets and their child rules.

Base URL: https://api.chargebackstop.com/v1/rulesets/

Authentication: Bearer token via API key.

Required abilities:

rulesets:read for GET endpoints
rulesets:write for POST, PATCH, and DELETE endpoints

Access scope model:

Organisation-level keys can access rulesets for their own organisation only.
Admin partner-group keys can access rulesets across all organisations for their partner.
Non-admin partner-group keys can access rulesets only for organisations assigned to their group.

A rule is defined by its type and a parameters object whose shape depends on the type. Each ruleset can contain at most one rule of each type. The same rule types apply to embedded rules on POST /v1/rulesets and to the nested POST / PATCH rule endpoints.

Matches the transaction amount against a threshold.

Field

Type

Description

Example parameters:

Matches the transaction's statement descriptor against one or more entries.

Field

Type

Description

Each descriptor entry:

Field

Type

Description

Example parameters:

Creates one ruleset and optionally creates child rules within the same request.

API level: Organisation-level and partner-level Authentication: rulesets:write

Field

Type

Description

Returns a paginated list of accessible rulesets.

API level: Organisation-level and partner-level Authentication: rulesets:read

Parameter

Type

Description

Returns one accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:read

Updates one accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Field

Type

Description

Deletes one accessible ruleset and its child rules.

API level: Organisation-level and partner-level Authentication: rulesets:write

Adds one rule to an existing accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Field

Type

Description

Returns one accessible rule from an accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:read

Updates one accessible rule within an accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Field

Type

Description

Deletes one accessible rule from an accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Partner SSO

If you're a ChargebackStop Partner you're able to integrate custom SSO for your users to easily authenticate into their organisations from your application, no re-authentication required.

Note that this is not for integrating enterprise SSO providers such as Okta or Azure AD for partner or merchant accounts, if you want to enable enterprise SSO login options please contact support.

These are instructions on how to generate Single Sign-On tokens on your server. These token can be used to authenticate your users into our merchant dashboard for your organisations.

1. Generate your Partner SSO Key

You can do this by logging into your partner dashboard and under Settings > Single Sign-On (SSO) for Organisations and generate a key. Store this key in a secure environment variable on your server. Do not expose this key in any frontend interface.

2. Get your Partner ID

From your partner dashboard grab the first ID in the URL. For example:

https://dashboard.chargebackstop.com/partners/ptnr_T1Ng7EgYrY7uaKMgPsASE/settings

In this case ptnr_T1Ng7EgYrY7uaKMgPsASE would be your Partner ID.

3. Generate your SSO Token

You can do this using all major programming languages, see below for common examples:

We use JSON Web Tokens to securely authenticate your users. First, install the appropriate JWT library for your server.

These tokens must be used within 15 minutes of issuance (UTC timezone)

Your user must already be a member of an organisation with your partner account. If the user is not a member the SSO will fail, and due to security implications you cannot SSO a user that is a member of an organisation outside of your partner account.

Your Base URL will be either https://dashboard.chargebackstop.com, or your own white label instance such https://chargebacks.example.com, make sure to redirect your customer to the right one.

Your Partner ID will be the ID we retrieved earlier such as ptnr_T1Ng7EgYrY7uaKMgPsASE

Your SSO Token will be the token we generated above. You need to generate this token each time.

Putting it all together

For example

https://dashboard.chargebackstop.com/auth/partner-organisation-sso?partner_id=ptnr_T1Ng7xxxxx&token=eyJhbGciOiJIUzI1NiIsInR5cCIyyyyy

If you have any questions, please let our customer success team know and we'll do our best to help you.

Enrolments

Create, list, retrieve, and cancel network alert enrolments for one or more merchants.

Versioning notice (important):

This is the first v2 API documentation for enrolments.
/v1/enrolments is deprecated and should not be used for new integrations.
Use /v2/enrolments with enrolments_v2:* abilities.
New API keys are provisioned with enrolments_v2:* abilities for enrolments access.
Some legacy keys created before /v1/enrolments was deprecated may include both enrolments:* and enrolments_v2:* abilities.

Base URL: https://api.chargebackstop.com/v2/enrolments/

Authentication: Bearer token via API key.

Required abilities:

enrolments_v2:read for GET endpoints
enrolments_v2:write for POST and DELETE endpoints

Access scope model:

This API is partner-level only.
Admin partner-group keys can access enrolments across organisations available to their partner.
Non-admin partner-group keys can access enrolments only for organisations assigned to their group.

Use this section to migrate existing enrolments integrations from v1 to v2.

Area

Action

All operations map 1:1 to v2 routes:

POST /v1/enrolments -> POST /v2/enrolments
GET /v1/enrolments -> GET /v2/enrolments

v2 is still partner-level only.
Organisation-level keys are still not allowed.
v2 endpoints require enrolments_v2:read and enrolments_v2:write.

v1 create body (single merchant):

v2 create body (one or more merchants):

v1 response field:

v2 response field:

Other core fields (id, organisation_id, type, status, ethoca_alert, verifi_rdr, timestamps, note) stay the same contract shape.

merchant_ids must not contain duplicates.
All merchants in one create request must be accessible to the key.
All merchants in one create request must belong to the same organisation.

type values used by this API remain ETHOCA_ALERT and VERIFI_RDR.
GET /v2/enrolments still supports merchant_id, organisation_id, type

Switch all enrolments routes from /v1/enrolments to /v2/enrolments.

Ensure API keys include enrolments_v2:read and enrolments_v2:write.

Create a new enrolment for one or more merchants.

API level: Partner-level only Authentication: enrolments_v2:write

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

The API rejects mixed-organisation merchant lists with MERCHANTS_DIFFERENT_ORGANISATIONS.
The enrolment is created in PENDING status.
Responses return merchant_ids (plural), not merchant_id

Ethoca validates descriptors asynchronously after the enrolment is created. This can take a few days. If the descriptor is too generic or already enrolled by another merchant globally across Ethoca's network, the enrolment moves to ACTION_REQUIRED. When this happens, our support team reaches out to the merchant to agree on an alternative descriptor. This typically takes 1–2 business days. Once resolved, the enrolment is resubmitted. To track enrolment status, poll the GET endpoint every 2–3 hours or subscribe to a webhook to watch for status changes.

Return enrolments accessible to the authenticated partner-group key.

API level: Partner-level only Authentication: enrolments_v2:read

Parameter

Type

Description

Filtering by a non-existent organisation returns 404 Not found.
Filtering by a non-existent merchant returns 404 Not found.

Retrieve one accessible enrolment by ID.

API level: Partner-level only Authentication: enrolments_v2:read

Parameter

Type

Description

Cancel one accessible enrolment.

API level: Partner-level only Authentication: enrolments_v2:write

Parameter

Type

Description

Only enrolments in PENDING status can be cancelled.
Cancellation sets status to CANCELLED and sets note to Enrolment cancelled via API request.

All error responses use this shape:

Other business validation codes you may receive:

Code

Meaning

API integration guide

Full API documentation is available here: https://api.chargebackstop.com/v1/docs.

V2 API documentation (enrolments endpoint only for now): https://api.chargebackstop.com/v2/docs.

Onboarding a new customer into your partner account

Create an organisation

Use the /v1/organisations endpoint. Save the organisation ID for later use in the memberships and merchants APIs.

Sample request:

curl -X POST "https://api.chargebackstop.com/v1/organisations/" \
  -H "Authorization: Bearer <partner_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Fitness"
  }'

Sample response:

{
  "id": "org_abc123",
  "name": "Acme Fitness",
  "mode": "LIVE",
  "created_at": "2026-02-17T10:00:00Z",
  "updated_at": "2026-02-17T10:00:00Z"
}

Save organisation_id = org_abc123. You will use this in memberships, merchants, and integrations requests.

Use the /v1/memberships endpoint.

You can skip this step if you do not intend for your users to log in to ChargebackStop.

Sample request:

Sample response:

This creates the customer user and links them to the organisation.

Use the /v1/merchants endpoint. Save the merchant account IDs for later use in the integrations and enrolments APIs.

Sample request:

Sample response:

Save merchant_id = mrch_abc123. You will use this in integrations and enrolments requests.

Use the /v1/integrations endpoint. Save the integration ID for later use in the orders API.

Sample request:

Sample response:

Save integration_id = int_abc123. You will use this for orders submissions.

Use the /v2/enrolments endpoint. Verifi RDR and Ethoca enrolments are separate; create both if the customer wants both services.

See .

Create Ethoca enrolment

Sample request:

Sample response:

Save ethoca_enrolment_id = enrl_ethoca123 if you need to track this enrolment status.

Use the /v1/rulesets endpoint to control what happens when a pre-dispute alert matches a transaction. A ruleset is scoped to one or more enrolments of the same type — you cannot combine Ethoca and Verifi RDR enrolments in the same ruleset. If you need the same logic for both, create one ruleset per enrolment type.

See .

Verifi RDR

By default, every Verifi RDR alert results in a refund of the matching transaction. Verifi RDR alerts are resolved at the network level, so they arrive already resolved and have no ACTION_REQUIRED state — they are not actionable after the fact.

Use the /v1/orders endpoint.

Send a COMPLETE order that satisfies alert matching requirements. COMPLETE orders can be sent directly to your CUSTOM_ORDERS integration.

Sample request:

Sample response:

This creates a COMPLETE order with the core card transaction fields required for alert matching.

If you want to run the same onboarding flow end-to-end and print all created IDs automatically, use:

Before running it, save the script below as onboarding-flow.js and set API_KEY.

Full onboarding flow script (Node.js):

Every Ethoca alert with ACTION_REQUIRED status is expected to be actioned by the user. The deadline is represented by the action_required_deadline field in the alert object. However, we recommend sending your chosen action as soon as possible. After actioning, the alert status moves to RESOLVED and can no longer be changed. Verifi RDR alerts arrive already resolved and are not actionable.

Behind the scenes, actioning an alert updates Ethoca with the outcome. This allows them to stop the dispute if the user proactively refunded the transaction, or let the dispute proceed if you chose to fight it.

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

The update alert endpoint (PATCH /v1/alerts/{alert_id}) takes the following parameters:

action - the action to perform on the alert (see below)
note - an optional customer-facing comment/note about the alert

The action parameter can be one of four values:

REFUND
CANCEL
REFUND_AND_CANCEL

Let's explore how each of these values works.

We let the alert provider know that you refunded the alert.
If your merchant account is integrated with a payment provider, we automatically refund the payment.

We let the alert provider know that you did not refund the alert.
If your merchant account is integrated with a payment provider and there is a subscription associated with the alert, we automatically cancel it.

We let the alert provider know that you refunded the alert.
If your merchant account is integrated with a payment provider, we automatically refund the payment.
If your merchant account is integrated with a payment provider and there is a subscription associated with the alert, we automatically cancel it.

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

If you have not integrated ChargebackStop with any payment processing services, you will most likely use only REFUND and ACCEPT_DISPUTE.

This API is also available to your customers. They can generate API keys for their own organisations in the organisation dashboard and action alerts via API.

If you enabled payment processor integrations in your organisations and enabled automatic matching, GET /v1/alerts responses include two additional fields:

integration_id - ChargebackStop integration ID that contains the transaction matched to this alert
integration_transaction_id - transaction ID matched to this alert in your payment processor. For Stripe, this looks like pi_3SPJO4KRFSLReU4y04XJUvLN. For other processors it varies.

Ethoca and Verifi RDR resolve alerts through fundamentally different mechanisms. Both flows are documented in detail in the sections above — use this contrast as a quick reference.

Ethoca (ETHOCA_ALERT) — Alerts enter an ACTION_REQUIRED state with a deadline (action_required_deadline). You (or your customer) must call PATCH /v1/alerts/{alert_id} with one of REFUND, CANCEL, REFUND_AND_CANCEL, or ACCEPT_DISPUTE before the deadline. If no action is taken, the dispute proceeds. Resolution rulesets can auto-action matched alerts when a payment processor integration is in place, but the underlying mechanism is still the same

In TEST mode, you can use simulation endpoints to test webhooks and actioning alerts.

/* * Simple onboarding flow example for partner API keys. * * Update the variables in the CONFIG section, then run: * node onboarding-flow.js */ // ----------------------------------------------------------------------------- // CONFIG // ----------------------------------------------------------------------------- const API_BASE_URL = "https://api.chargebackstop.com"; const API_KEY = "REPLACE_WITH_PARTNER_API_KEY"; const MEMBER_USER_EMAIL = "[email protected]"; const MEMBER_FIRST_NAME = "Casey"; const MEMBER_LAST_NAME = "Jordan"; const ORGANISATION_NAME = "Acme Fitness"; const MERCHANT_NAME = "Acme Fitness Main Store"; const MERCHANT_TYPE = "GENERIC"; const MERCHANT_EXTERNAL_ID = "acct_1ABCDEF2345678"; const INTEGRATION_NAME = "Acme Fitness Orders"; const ORDER_REFERENCE_ID = "order-10001"; const ORDER_NUMBER = "AF-10001"; const ORDER_CUSTOMER_EMAIL = MEMBER_USER_EMAIL; const ORDER_TRANSACTION_REFERENCE_ID = "txn-10001"; // ----------------------------------------------------------------------------- // HELPERS // ----------------------------------------------------------------------------- function fail(message, details) { console.error(`\nERROR: ${message}`); if (details !== undefined) { console.error(JSON.stringify(details, null, 2)); } process.exit(1); } function logStep(stepNumber, title) { console.log(`\n[Step ${stepNumber}] ${title}`); } function printJson(label, data) { console.log(`${label}:`); console.log(JSON.stringify(data, null, 2)); } async function apiRequest({ method, path, body }) { const response = await fetch(`${API_BASE_URL}${path}`, { method, headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: body ? JSON.stringify(body) : undefined, }); const rawText = await response.text(); let data = null; if (rawText.length > 0) { try { data = JSON.parse(rawText); } catch (error) { data = { raw: rawText }; } } if (!response.ok) { fail(`Request failed: ${method} ${path} (${response.status})`, data); } return data; } // ----------------------------------------------------------------------------- // FLOW // ----------------------------------------------------------------------------- async function main() { if (API_KEY.includes("REPLACE_WITH_PARTNER_API_KEY")) { fail("Set API_KEY at the top of this file before running the script."); } const createdIds = { organisation_id: null, membership_id: null, merchant_id: null, integration_id: null, ethoca_enrolment_id: null, verifi_enrolment_id: null, order_id: null, }; logStep(1, "Create organisation"); const organisation = await apiRequest({ method: "POST", path: "/v1/organisations/", body: { name: ORGANISATION_NAME, }, }); createdIds.organisation_id = organisation.id; printJson("Response", organisation); console.log(`Saved organisation_id: ${createdIds.organisation_id}`); logStep(2, "Create membership"); const membership = await apiRequest({ method: "POST", path: "/v1/memberships/", body: { organisation_id: createdIds.organisation_id, first_name: MEMBER_FIRST_NAME, last_name: MEMBER_LAST_NAME, email: MEMBER_USER_EMAIL, role: "ADMIN", is_alert_action_required_email_enabled: true, is_alert_resolved_email_enabled: true, is_alert_dismissed_email_enabled: true, is_evidence_requested_email_enabled: true, }, }); createdIds.membership_id = membership.id; printJson("Response", membership); console.log(`Saved membership_id: ${createdIds.membership_id}`); logStep(3, "Create merchant"); const merchant = await apiRequest({ method: "POST", path: "/v1/merchants/", body: { organisation_id: createdIds.organisation_id, name: MERCHANT_NAME, type: MERCHANT_TYPE, external_id: MERCHANT_EXTERNAL_ID, }, }); createdIds.merchant_id = merchant.id; printJson("Response", merchant); console.log(`Saved merchant_id: ${createdIds.merchant_id}`); logStep(4, "Create custom orders integration"); const integration = await apiRequest({ method: "POST", path: "/v1/integrations/", body: { organisation_id: createdIds.organisation_id, name: INTEGRATION_NAME, type: "CUSTOM_ORDERS", status: "ENABLED", merchant_ids: [createdIds.merchant_id], }, }); createdIds.integration_id = integration.id; printJson("Response", integration); console.log(`Saved integration_id: ${createdIds.integration_id}`); logStep(5, "Create Ethoca enrolment"); const ethocaEnrolment = await apiRequest({ method: "POST", path: "/v2/enrolments/", body: { merchant_ids: [createdIds.merchant_id], type: "ETHOCA_ALERT", ethoca_alert: { descriptors: [ { descriptor: "ACMEFIT", match_type: "STARTS_WITH", }, ], }, }, }); createdIds.ethoca_enrolment_id = ethocaEnrolment.id; printJson("Response", ethocaEnrolment); console.log(`Saved ethoca_enrolment_id: ${createdIds.ethoca_enrolment_id}`); logStep(6, "Create Verifi RDR enrolment"); const verifiEnrolment = await apiRequest({ method: "POST", path: "/v2/enrolments/", body: { merchant_ids: [createdIds.merchant_id], type: "VERIFI_RDR", verifi_rdr: { bin: "424242", caid: "ABC1234567", }, }, }); createdIds.verifi_enrolment_id = verifiEnrolment.id; printJson("Response", verifiEnrolment); console.log(`Saved verifi_enrolment_id: ${createdIds.verifi_enrolment_id}`); logStep(7, "Submit COMPLETE order for alert matching"); const orderResponse = await apiRequest({ method: "POST", path: "/v1/orders/", body: [ { type: "COMPLETE", organisation_id: createdIds.organisation_id, integration_id: createdIds.integration_id, reference_id: ORDER_REFERENCE_ID, order_datetime: "2026-02-17T09:59:00Z", order_number: ORDER_NUMBER, order_subtotal_amount_in_cents: 4900, order_currency: "USD", order_total_amount_in_cents: 4900, order_status: "CLOSED_COMPLETE", customer_email: ORDER_CUSTOMER_EMAIL, transactions: [ { reference_id: ORDER_TRANSACTION_REFERENCE_ID, amount_in_cents: 4900, currency: "USD", payment_method_type: "CARD", authorisation_status: "SETTLED", payment_method_reference_id: "pi_3QJ2ABCD12345678", authorised_at: "2026-02-17T09:59:05Z", payment_method_card_brand: "VISA", payment_method_card_last_4: "4242", acquirer_reference_number: "74027012345678901234567", }, ], }, ], }); printJson("Response", orderResponse); if (orderResponse.failed > 0) { console.log("\nOrder was not created. API returned validation errors."); } else if (orderResponse.results && orderResponse.results.length > 0) { createdIds.order_id = orderResponse.results[0].id; } console.log("\nDone. IDs to save for future requests:"); printJson("Created IDs", createdIds); } main().catch((error) => { fail("Unexpected script error", { message: error.message, stack: error.stack, }); });

Orders

Submit order data to ChargebackStop for chargeback prevention and dispute resolution. This API powers integrations with Mastercard Consumer Clarity, Visa Order Insight, and chargeback alert matching.

Base URL: https://api.chargebackstop.com/v1/orders/

Authentication: Bearer token via API key. Required abilities vary by endpoint (all newly created API keys include these Orders abilities by default):

orders:read for GET endpoints
orders:write for POST endpoints
orders:update for PATCH endpoints

Rate limits:

100 requests per minute per endpoint, per organisation/partner group
Each endpoint has an independent rate limit pool (e.g., hitting the list limit doesn't affect create)
Rate limits are applied by owner (organisation or partner group), not by API key

Batch Limit: Maximum 100 orders per request (POST only).

Retrieve a paginated list of orders with optional filtering and sorting.

Authentication: Bearer token via API key with orders:read ability.

Parameter

Type

Description

Retrieve a single order by its internal id (the id field returned in JSON responses), not by reference_id.

To retrieve an order by reference_id, use the list endpoint: GET /v1/orders?reference_id=<your_reference_id>.

Authentication: Bearer token via API key with orders:read ability.

Parameter

Type

Description

Returns the full order object with all nested relations (transactions, deliveries, items, refunds, subscriptions, disputes).

404 Not Found - Order does not exist or is not accessible:

Submit order data to ChargebackStop for chargeback prevention and dispute resolution.

Authentication: Bearer token via API key with orders:write ability.

Rate Limit: 100 requests per minute per organisation/partner group.

Batch Limit: Maximum 100 orders per request.

Request Body: JSON array of order objects (even when submitting a single order).

Schema validation before partial success: Partial success applies after request schema validation. If the top-level request is invalid (for example, body is not an array or fields have invalid types), the API returns a full-request 422 and no orders are processed.

Mode

Use Case

Integration Type

Important: Order type and integration type must match
COMPLETE orders can ONLY be created with CUSTOM_ORDERS integrations. Attempting to create a COMPLETE order on a Stripe, Adyen, or other payment processor integration will return INVALID_ORDER_TYPE.
PARTIAL orders can ONLY be created with non-CUSTOM_ORDERS integrations (Stripe, Adyen, Shopify, etc.) and require orders enrichment to be enabled by ChargebackStop support. Attempting to create a PARTIAL order on a CUSTOM_ORDERS integration will return INVALID_ORDER_TYPE

Use PARTIAL mode when you already have a payment processor integration (Stripe, Adyen, Shopify, etc.) connected to ChargebackStop and want to enrich your orders with additional data.

Prerequisites:

An existing integration (Stripe, Adyen, etc.) with orders enrichment enabled by the ChargebackStop team
API key with orders:write ability

Minimal required fields:

Field

Description

Device identifier required: PARTIAL orders must include at least one of: device_ip_address, device_id, or device_fingerprint. This is used for fraud prevention and dispute evidence.

Example 1: Basic PARTIAL Order

These field sets are required for PARTIAL mode, and are required for all order modes when digital receipts or deflection is enabled.

Examples below use PARTIAL payloads, but the same field sets can be included in COMPLETE orders.

Consumer Clarity helps reduce chargebacks by providing cardholders with detailed purchase information in their banking app, making transactions more recognisable.

Required fields for Consumer Clarity:

Field

Description

Example 2: Consumer Clarity (Mastercard)

Order Insight provides Visa cardholders with purchase details directly in their banking app, helping them recognise legitimate transactions.

Required fields for Order Insight:

Field

Description

Example 3: Order Insight (Visa)

Some merchants (particularly Merchant of Record platforms) may need to include product and merchant information with each order if default settings are not configured in the platform.

Note: If product and merchant information varies per order, include it in each order submission. If the values are stable across all orders, you can set defaults in the ChargebackStop platform instead.

Product information fields:

Field

Description

Merchant information fields:

Field

Description

Example 4: Product and merchant information

First-Party Trust is a Mastercard programme that helps identify legitimate transactions by linking customer identity data (email, device) across purchases. This strengthens fraud prevention and reduces first-party fraud chargebacks.

Required fields for FPT:

Field

Description

Example 5: First-Party Trust (Mastercard)

Compelling Evidence 3.0 is a Visa programme that helps merchants win disputes by proving the cardholder has a history of legitimate purchases. By submitting customer and device data with each order, you build evidence that can be used in dispute responses.

Required fields for CE3.0:

Field

Description

Example 6: Compelling Evidence 3.0 (Visa)

Use COMPLETE mode when you do not have an existing payment processor integration to enrich and want to submit full order data directly to ChargebackStop. This mode supports digital receipts, deflection, and alert matching, and is for merchants using the CUSTOM_ORDERS integration type.

Prerequisites:

A CUSTOM_ORDERS integration
API key with orders:write ability

Required fields for COMPLETE orders:

Field

Description

To match orders with chargeback alerts, you must include at least one transaction with specific fields that enable accurate matching. The richer the data set you provide, the better the matching accuracy will be — we recommend including as many transaction fields as possible.

Required transaction fields:

Field

Description

Additional required fields for card payments:

Field

Description

Matching identifiers (send all three whenever possible):

Identifier

Recommendation

Notes

For card payments, at least one matching identifier is required. Best practice is to send all three identifiers whenever available, or as many as possible.

Why these fields matter:

ARN (Acquirer Reference Number): The most reliable identifier for matching - directly links to the network transaction
Authorisation Code: The 6-digit code from the issuer, used with card last 4 when ARN is not available
Card BIN: The first 6-8 digits of the card, helps narrow down matches when combined with other card details and amount

Note: It is worth sending any related refunds and disputes for the order. Including these records helps us detect invalid alerts more accurately.

Example 7: Alert matching (COMPLETE)

This example includes all available fields for a COMPLETE order.

Required column abbreviations:

Abbreviation

Feature

Validation wording note:

Required means the field must be present in the request payload. It does not, by itself, imply a non-empty string value.
1-255 chars means the API enforces a non-empty string.
Up to 255 chars means the API enforces only a maximum length, and an empty string may still be accepted when the field is otherwise optional.

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

Field

Type

Required

Validation

Description

At least one device identifier is required for PARTIAL orders, and for FPT/CE3.0 when enabled.

Field

Type

Required

Validation

Description

Field

Type

Required

Description

Request/response shape: Both requests and responses use nested merchant_address.

Limit: Maximum 10 transactions per order.

At least one transaction is required for Alert Matching.

Field

Type

Required

Validation

Description

When payment_method_type is CARD, the following fields are required:

Field

Type

Required

Description

Note: For alert matching with card payments, send all three identifiers whenever available (acquirer_reference_number, authorisation_code, and payment_method_card_bin). If you cannot provide all three, provide at least one of the following combinations:
acquirer_reference_number (works on its own)

Field

Type

Required

Description

Limit: Maximum 10 deliveries per order.

Field

Type

Required

Description

Create uniqueness scope: On POST, deliveries are unique per integration by reference_id. Reusing a delivery reference_id for the same integration returns DUPLICATE_DELIVERY.

Field

Type

Required

Description

When type is PHYSICAL, the following fields are required:

Field

Type

Required

Description

Field

Type

Required

Description

Limit: Maximum 10 items per order.

Field

Type

Required

Description

Limit: Maximum 10 refunds per order.

Field

Type

Required

Description

Create uniqueness scope: On POST, refunds are unique per integration by reference_id. Reusing a refund reference_id for the same integration returns DUPLICATE_REFUND.

Limit: Maximum 10 subscriptions per order.

Upsert behaviour: Subscriptions are identified by reference_id per integration. If a subscription with the same reference_id already exists, it will be updated with the new values. The subscription will be linked to the new order while maintaining links to previous orders. This allows the same subscription to span multiple orders (e.g., monthly renewals).
Warning: Full replace semantics - When updating a subscription, ALL optional fields are replaced, not merged. If you omit a field in a subsequent request, it will be set to NULL. For example, if Order 1 creates a subscription with display_name: "Pro Plan" and Order 2 references the same subscription without display_name, the display name will be cleared.

Field

Type

Required

Description

Limit: Maximum 10 disputes per order.

Field

Type

Required

Description

Create uniqueness scope: On POST, disputes are unique per integration by reference_id. Reusing a dispute reference_id for the same integration returns DUPLICATE_DISPUTE.

All address objects (billing, shipping, merchant) use this structure:

Field

Type

Required

Validation

Note: When providing an address, include at least one of line_1, line_2, or line_3, plus city, country_subdivision, postal_code, and country.

All currency fields must be valid ISO 4217 codes. Common examples: USD, EUR, GBP, CAD, AUD, JPY. See the for the full list.

Phone fields must be in E.164 format:

Start with +
Followed by 1-15 digits
No spaces or special characters

Valid: +14155551234, +442071234567 Invalid: 415-555-1234, (415) 555-1234

All email fields are validated for proper email format.

All *_in_cents fields must be non-negative integers (>= 0).

Code

Description

The API uses partial success semantics for per-order processing: valid orders are created even if other orders in the same batch fail. Each order is processed independently, and failures do not cause a rollback of successfully created orders.

This behaviour applies after request schema validation. Schema-level validation failures return a full-request 422 response and skip per-order processing.

The response includes:

created: Number of orders successfully created
failed: Number of orders that failed validation
results: Array of successfully created orders

Returned when you exceed 100 requests per minute for the endpoint.

Successful GET /v1/orders, GET /v1/orders/{order_id}, POST /v1/orders, and PATCH /v1/orders/{order_id} responses all use the same canonical order object shape.

Each order object includes:

Core fields: id, reference_id, type, organisation_id, integration_id, created_at
Any documented order, customer, device, and merchant fields that are present for that order

Each nested object includes its own server-generated id plus the documented fields for that resource.

Partially update an existing order and its nested objects.

Authentication: Bearer token via API key with orders:update ability.

URL parameters:

order_id (required): The order ID to update

All fields are optional. Only provided fields will be updated.

Field

Type

Description

Update deliveries that belong to the order. Each delivery is identified by reference_id.

Important:

Only deliveries belonging to this order can be updated
Delivery type (DIGITAL or PHYSICAL) cannot be changed after creation
Fields are type-constrained: digital fields only work on DIGITAL deliveries, physical fields only work on

Field

Type

Description

If you include physical_shipping_address in a PATCH request, send a complete valid address object rather than a partial address fragment.

Example 9: Update physical delivery status

Update existing subscriptions by reference_id. Only subscriptions that already exist can be updated - to create new subscriptions, use the POST endpoint when creating an order.

Field

Type

Required

Description

Example 10: Update subscription status

Create new refunds or update existing refunds. For existing refunds, amount_in_cents and currency are immutable, while status, original_transaction_reference_id, and refund_datetime can be updated.

Field

Type

Required

Description

Example 11: Create new refund

Example 12: Update existing refund status

Create new disputes or update existing disputes. For existing disputes, amount_in_cents, currency, and type are immutable, while stage, status, network_reason_code, is_rapid_dispute_resolution, evidence_due_by, payment_method_type, and card_brand can be updated.

Field

Type

Required

Description

Example 13: Update dispute status

Code

Description

Returns the updated order with all nested objects.

Success Response (200)

Error Response (422)

Not Found Response (404)

[ { "type": "COMPLETE", "organisation_id": "org_abc123", "integration_id": "int_custom789", "reference_id": "order-2024-001", "order_datetime": "2024-01-15T10:30:00Z", "order_number": "ORD-2024-001", "order_subtotal_amount_in_cents": 9000, "order_currency": "USD", "order_tax_amount_in_cents": 720, "order_total_amount_in_cents": 9720, "order_status": "CLOSED_COMPLETE", "order_phone": "+14155551234", "order_is_adult_content": false, "order_request_refund_url": "https://example.com/orders/ORD-2024-001/refund", "order_buy_again_url": "https://example.com/orders/ORD-2024-001/reorder", "order_write_review_url": "https://example.com/orders/ORD-2024-001/review", "order_view_url": "https://example.com/orders/ORD-2024-001", "order_proof_of_consent": "Customer agreed to Terms of Service on 2024-01-15 via checkout checkbox", "order_communications": "Order confirmation email sent 2024-01-15. Shipping notification sent 2024-01-16.", "customer_email": "[email protected]", "customer_first_name": "John", "customer_last_name": "Doe", "customer_account_id": "[email protected]", "order_email": "[email protected]", "device_ip_address": "216.24.60.94", "device_id": "device-abc123", "device_fingerprint": "fp-xyz789", "merchant_reference_id": "merchant-001", "merchant_name": "Example Corporation", "merchant_store_name": "Example Store", "merchant_store_description": "Your one-stop shop for widgets and gadgets", "merchant_contact_email": "[email protected]", "merchant_customer_service_email": "[email protected]", "merchant_contact_phone": "+14155559876", "merchant_address": { "line_1": "100 Commerce St", "line_2": "Suite 500", "line_3": "Building A", "city": "San Francisco", "country_subdivision": "CA", "postal_code": "94105", "country": "US" }, "merchant_store_url": "https://store.example.com", "merchant_url": "https://example.com", "merchant_terms_and_conditions_url": "https://example.com/terms", "merchant_logo_url": "https://example.com/logo.png", "merchant_refund_policy_url": "https://example.com/refund-policy", "transactions": [ { "reference_id": "txn-001", "amount_in_cents": 9720, "currency": "USD", "payment_method_type": "CARD", "authorisation_status": "SETTLED", "payment_method_reference_id": "pm_card_abc123", "authorised_at": "2024-01-15T10:30:05Z", "descriptor": "EXAMPLE STORE", "descriptor_prefix": "EXAMPLE", "descriptor_suffix": "STORE", "authorisation_code": "123456", "acquirer_reference_number": "74027012345678901234567", "network_id": "network-txn-123", "settlement_datetime": "2024-01-16T00:00:00Z", "cvc_verified": true, "three_d_secure_verified": true, "payment_method_card_brand": "VISA", "payment_method_card_last_4": "4242", "payment_method_card_exp_month": 12, "payment_method_card_exp_year": 2026, "payment_method_card_bin": "424242", "payment_method_card_wallet_type": "APPLE_PAY", "payment_method_card_issuer": "Chase Bank", "billing_address": { "line_1": "123 Main St", "line_2": "Apt 4B", "city": "New York", "country_subdivision": "NY", "postal_code": "10001", "country": "US" } } ], "deliveries": [ { "reference_id": "dlv-physical-001", "type": "PHYSICAL", "physical_shipping_carrier": "UPS", "physical_shipping_tracking_number": "1Z999AA10123456784", "physical_shipping_status": "DELIVERED", "physical_shipping_datetime_shipped": "2024-01-16T08:00:00Z", "physical_shipping_datetime_delivered": "2024-01-18T14:30:00Z", "physical_shipping_address": { "line_1": "123 Main St", "line_2": "Apt 4B", "city": "New York", "country_subdivision": "NY", "postal_code": "10001", "country": "US" } }, { "reference_id": "dlv-digital-001", "type": "DIGITAL", "digital_delivery_datetime": "2024-01-15T10:35:00Z", "digital_download_start_datetime": "2024-01-15T10:36:00Z", "digital_download_end_datetime": "2024-01-15T10:37:00Z", "digital_delivery_ip_address": "216.24.60.175", "digital_notification_sent": true, "digital_notification_sent_datetime": "2024-01-15T10:35:00Z", "digital_notification_method": "EMAIL" } ], "items": [ { "reference_id": "item-001", "name": "Widget Pro", "price_in_cents": 4500, "quantity": 2, "product_url": "https://example.com/products/widget-pro", "product_reference_id": "prod-widget-pro", "sku": "WIDGET-PRO-001", "delivery_reference_id": "dlv-physical-001" }, { "reference_id": "item-002", "name": "Digital License Key", "price_in_cents": 0, "quantity": 1, "product_url": "https://example.com/products/license", "product_reference_id": "prod-license", "sku": "LICENSE-001", "delivery_reference_id": "dlv-digital-001", "subscription_reference_id": "sub-001" } ], "refunds": [ { "reference_id": "refund-001", "amount_in_cents": 4500, "currency": "USD", "status": "SUCCEEDED", "original_transaction_reference_id": "txn-001", "refund_datetime": "2024-01-17T12:00:00Z" } ], "subscriptions": [ { "reference_id": "sub-001", "interval": "MONTH", "interval_price_in_cents": 2999, "interval_currency": "USD", "status": "ACTIVE", "display_name": "Pro Plan Monthly", "trial_start_date": "2024-01-01T00:00:00Z", "trial_end_date": "2024-01-14T23:59:59Z", "trial_price_in_cents": 0, "trial_currency": "USD", "start_date": "2024-01-15T00:00:00Z", "next_charge_date": "2024-02-15T00:00:00Z" } ], "disputes": [ { "reference_id": "dispute-001", "amount_in_cents": 4500, "currency": "USD", "stage": "1ST_CHARGEBACK", "status": "OPEN", "type": "CHARGEBACK", "network_reason_code": "10.4", "is_rapid_dispute_resolution": false, "evidence_due_by": "2024-02-15T23:59:59Z", "payment_method_type": "CARD", "card_brand": "VISA" } ] } ]