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.
Organisation-level keys receive 401 Unauthorised on all endpoints.

Migration from `/v1/enrolments` to `/v2/enrolments`

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

At a glance

Area

Action

Base path

/v1/enrolments

/v2/enrolments

Update request URLs

Create request merchant field

merchant_id (string)

merchant_ids (array of strings)

Update payload shape

Create response merchant field

merchant_id

merchant_ids

Update response parsing

List/get/delete response merchant field

merchant_id

merchant_ids

Update response parsing

New create validation

Not applicable

Rejects duplicate merchant IDs and mixed-organisation merchant sets

Handle new 422 codes

Merchant reference

merchant_id identifies one merchant

merchant_ids supports one or more merchants; missing merchant references return 404 Not found; mixed-organisation merchant sets return 422 MERCHANTS_DIFFERENT_ORGANISATIONS

Update merchant error handling

Endpoint mapping

All operations map 1:1 to v2 routes:

POST /v1/enrolments -> POST /v2/enrolments
GET /v1/enrolments -> GET /v2/enrolments
GET /v1/enrolments/{enrolment_id} -> GET /v2/enrolments/{enrolment_id}
DELETE /v1/enrolments/{enrolment_id} -> DELETE /v2/enrolments/{enrolment_id}

Authentication and abilities changes

v2 is still partner-level only.
Organisation-level keys are still not allowed.
v2 endpoints require enrolments_v2:read and enrolments_v2:write.
New API keys are provisioned with v2 enrolments abilities.
Some legacy keys created before v1 deprecation may include both enrolments:* and enrolments_v2:*.

Request and response schema differences

v1 create body (single merchant):

{
  "merchant_id": "mrch_abc123",
  "type": "ETHOCA_ALERT",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ECOMM.COM",
        "match_type": "STARTS_WITH"
      }
    ]
  }
}

v2 create body (one or more merchants):

{
  "merchant_ids": ["mrch_abc123", "mrch_def456"],
  "type": "ETHOCA_ALERT",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ECOMM.COM",
        "match_type": "STARTS_WITH"
      }
    ]
  }
}

v1 response field:

{
  "merchant_id": "mrch_abc123"
}

v2 response field:

{
  "merchant_ids": ["mrch_abc123", "mrch_def456"]
}

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

Behaviour differences to handle

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.
Out-of-scope organisation and merchant references are returned as 404 Not found.
Handle additional 422 business codes: DUPLICATE_MERCHANT_IDS and MERCHANTS_DIFFERENT_ORGANISATIONS.

What does not change

type values used by this API remain ETHOCA_ALERT and VERIFI_RDR.
GET /v2/enrolments still supports merchant_id, organisation_id, type, and status filters.
Deleting an enrolment still cancels it, and only PENDING enrolments can be cancelled.

Migration checklist

Switch routes

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

Update API key abilities

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

Update payloads

Update create payload builders from merchant_id to merchant_ids.

Update response parsing

Update response parsing from merchant_id to merchant_ids across create/list/get/delete flows.

Handle new 422 codes

Add handling for new 422 codes: DUPLICATE_MERCHANT_IDS and MERCHANTS_DIFFERENT_ORGANISATIONS.

Re-run tests

Re-run integration tests for enrolment create, list filters, detail, and cancel flows.

POST /v2/enrolments - Create enrolment

Create a new enrolment for one or more merchants.

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

Request body

Field

Type

Required

Validation

Description

merchant_ids

array[string]

Yes

At least one ID; duplicates are rejected; all merchants must be accessible and belong to the same organisation

Merchants to associate with the enrolment

type

string

Yes

ETHOCA_ALERT or VERIFI_RDR

Enrolment type

ethoca_alert

object

Conditionally

Required when type is ETHOCA_ALERT

Ethoca Alert configuration

verifi_rdr

object

Conditionally

Required when type is VERIFI_RDR

Verifi RDR configuration

Ethoca Alert configuration

Field

Type

Required

Validation

Description

descriptors

array[object]

Yes

At least one descriptor

Descriptor rules for Ethoca matching

descriptors[].descriptor

string

Yes

Minimum length 1

Descriptor text

descriptors[].match_type

string

Yes

STARTS_WITH or EXACT_MATCH

Descriptor matching mode

Verifi RDR configuration

Field

Type

Required

Validation

Description

bin

string

Conditionally

Provide together with caid, or omit both and provide arns

Visa BIN

caid

string

Conditionally

Provide together with bin, or omit both and provide arns

Visa CAID

arns

array[string]

Conditionally

At least one item when used

Visa ARNs

Important behaviour

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.

Example 1 request

curl -X POST "https://api.chargebackstop.com/v2/enrolments/" \
  -H "Authorization: Bearer <partner_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ids": ["mrch_abc123", "mrch_def456"],
    "type": "ETHOCA_ALERT",
    "ethoca_alert": {
      "descriptors": [
        {
          "descriptor": "ECOMM.COM",
          "match_type": "STARTS_WITH"
        }
      ]
    }
  }'

Example 1 response

{
  "id": "enrl_abc123",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123", "mrch_def456"],
  "type": "ETHOCA_ALERT",
  "status": "PENDING",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ECOMM.COM",
        "match_type": "STARTS_WITH",
        "status": "PENDING"
      }
    ]
  },
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:00:00Z",
  "note": null
}

Example 2 request

curl -X POST "https://api.chargebackstop.com/v2/enrolments/" \
  -H "Authorization: Bearer <partner_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ids": ["mrch_abc123"],
    "type": "VERIFI_RDR",
    "verifi_rdr": {
      "bin": "424242",
      "caid": "ABC1234567"
    }
  }'

Example 2 response

{
  "id": "enrl_def456",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123"],
  "type": "VERIFI_RDR",
  "status": "PENDING",
  "verifi_rdr": {
    "bin": "424242",
    "caid": "ABC1234567",
    "arns": null
  },
  "created_at": "2026-02-16T12:05:00Z",
  "updated_at": "2026-02-16T12:05:00Z",
  "note": null
}

GET /v2/enrolments - List enrolments

Return enrolments accessible to the authenticated partner-group key.

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

Query parameters

Parameter

Type

Description

merchant_id

string

Filter by one accessible merchant ID

organisation_id

string

Filter by one accessible organisation ID

type

string

Filter by enrolment type

status

string

Filter by enrolment status

limit

integer

Number of results per page

offset

integer

Number of results to skip

Important behaviour

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

Example 3 request

curl -X GET "https://api.chargebackstop.com/v2/enrolments/?merchant_id=mrch_abc123&type=ETHOCA_ALERT&status=PENDING&limit=20&offset=0" \
  -H "Authorization: Bearer <partner_api_key>"

Example 3 response

{
  "items": [
    {
      "id": "enrl_abc123",
      "organisation_id": "org_xyz456",
      "merchant_ids": ["mrch_abc123", "mrch_def456"],
      "type": "ETHOCA_ALERT",
      "status": "PENDING",
      "ethoca_alert": {
        "descriptors": [
          {
            "descriptor": "ECOMM.COM",
            "match_type": "STARTS_WITH",
            "status": "PENDING"
          }
        ]
      },
      "created_at": "2026-02-16T12:00:00Z",
      "updated_at": "2026-02-16T12:00:00Z",
      "note": null
    }
  ],
  "count": 1
}

GET /v2/enrolments/{enrolment_id} - Get enrolment by ID

Retrieve one accessible enrolment by ID.

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

URL parameters

Parameter

Type

Description

enrolment_id

string

Enrolment ID

Example 4 request

curl -X GET "https://api.chargebackstop.com/v2/enrolments/enrl_abc123" \
  -H "Authorization: Bearer <partner_api_key>"

Example 4 response

{
  "id": "enrl_abc123",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123", "mrch_def456"],
  "type": "ETHOCA_ALERT",
  "status": "PENDING",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ECOMM.COM",
        "match_type": "STARTS_WITH",
        "status": "PENDING"
      }
    ]
  },
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:00:00Z",
  "note": null
}

DELETE /v2/enrolments/{enrolment_id} - Cancel enrolment

Cancel one accessible enrolment.

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

URL parameters

Parameter

Type

Description

enrolment_id

string

Enrolment ID to cancel

Important behaviour

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

Example 5 request

curl -X DELETE "https://api.chargebackstop.com/v2/enrolments/enrl_abc123" \
  -H "Authorization: Bearer <partner_api_key>"

Example 5 response

{
  "id": "enrl_abc123",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123", "mrch_def456"],
  "type": "ETHOCA_ALERT",
  "status": "CANCELLED",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ECOMM.COM",
        "match_type": "STARTS_WITH",
        "status": "PENDING"
      }
    ]
  },
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:10:00Z",
  "note": "Enrolment cancelled via API request"
}

Common error responses

All error responses use this shape:

{
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Human-readable message"
    }
  ]
}

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 v2 ability)

Returned when the key is valid but does not have the required v2 ability.

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

404 Not found

Returned when the requested resource does not exist. This includes non-existent enrolments and non-existent organisation_id or merchant_id filters.

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

422 Unprocessable Entity (mixed organisation merchants)

{
  "errors": [
    {
      "code": "MERCHANTS_DIFFERENT_ORGANISATIONS",
      "message": "All merchants must belong to the same organisation"
    }
  ]
}

422 Unprocessable Entity (enrolment not pending)

{
  "errors": [
    {
      "code": "ENROLMENT_NOT_PENDING",
      "message": "Only enrolments in PENDING state can be cancelled"
    }
  ]
}

Other business validation codes you may receive:

Code

Meaning

DUPLICATE_MERCHANT_IDS

merchant_ids contains duplicate values

MISSING_ETHOCA_ALERT_CONFIG

ethoca_alert is required for ETHOCA_ALERT enrolments

MISSING_VERIFI_RDR_CONFIG

verifi_rdr is required for VERIFI_RDR enrolments

INVALID_MATCH_TYPE

Ethoca descriptor match_type is invalid

INVALID_VERIFI_RDR_CONFIG

Verifi payload does not provide valid BIN/CAID or ARNs

ETHOCA_ALERT_ENROLLMENT_ERROR

Upstream Ethoca enrolment validation failed

VERIFI_RDR_ENROLLMENT_ERROR

Upstream Verifi enrolment validation failed

PreviousAlerts NextOrders

Was this helpful?

hashtagMigration from /v1/enrolments to /v2/enrolments

hashtagAt a glance

hashtagEndpoint mapping

hashtagAuthentication and abilities changes

hashtagRequest and response schema differences

hashtagBehaviour differences to handle

hashtagWhat does not change

hashtagMigration checklist

hashtagSwitch routes

hashtagUpdate API key abilities

hashtagUpdate payloads

hashtagUpdate response parsing

hashtagHandle new 422 codes

hashtagRe-run tests

hashtagPOST /v2/enrolments - Create enrolment

hashtagRequest body

hashtagEthoca Alert configuration

hashtagVerifi RDR configuration

hashtagImportant behaviour

hashtagExample 1 request

hashtagExample 1 response

hashtagExample 2 request

hashtagExample 2 response

hashtagGET /v2/enrolments - List enrolments

hashtagQuery parameters

hashtagImportant behaviour

hashtagExample 3 request

hashtagExample 3 response

hashtagGET /v2/enrolments/{enrolment_id} - Get enrolment by ID

hashtagURL parameters

hashtagExample 4 request

hashtagExample 4 response

hashtagDELETE /v2/enrolments/{enrolment_id} - Cancel enrolment

hashtagURL parameters

hashtagImportant behaviour

hashtagExample 5 request

hashtagExample 5 response

hashtagCommon error responses

Migration from `/v1/enrolments` to `/v2/enrolments`

At a glance

Endpoint mapping

Authentication and abilities changes

Request and response schema differences

Behaviour differences to handle

What does not change

Migration checklist

Switch routes

Update API key abilities

Update payloads

Update response parsing

Handle new 422 codes

Re-run tests

POST /v2/enrolments - Create enrolment

Request body

Ethoca Alert configuration

Verifi RDR configuration

Important behaviour

Example 1 request

Example 1 response

Example 2 request

Example 2 response

GET /v2/enrolments - List enrolments

Query parameters

Important behaviour

Example 3 request

Example 3 response

GET /v2/enrolments/{enrolment_id} - Get enrolment by ID

URL parameters

Example 4 request

Example 4 response

DELETE /v2/enrolments/{enrolment_id} - Cancel enrolment

URL parameters

Important behaviour

Example 5 request

Example 5 response

Common error responses