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	v1	v2	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

1

Switch routes

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

2

Update API key abilities

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

3

Update payloads

Update create payload builders from merchant_id to merchant_ids.

4

Update response parsing

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

5

Handle new 422 codes

Add handling for new 422 codes: DUPLICATE_MERCHANT_IDS and MERCHANTS_DIFFERENT_ORGANISATIONS.

6

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.

Ethoca descriptor validation

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.

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,
  "links": [
    {
      "rel": "self",
      "uri": "/v2/enrolments/enrl_abc123"
    }
  ]
}

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,
  "links": [
    {
      "rel": "self",
      "uri": "/v2/enrolments/enrl_def456"
    }
  ]
}

---

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,
      "links": [
        {
          "rel": "self",
          "uri": "/v2/enrolments/enrl_abc123"
        }
      ]
    }
  ],
  "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,
  "links": [
    {
      "rel": "self",
      "uri": "/v2/enrolments/enrl_abc123"
    }
  ]
}

---

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",
  "links": [
    {
      "rel": "self",
      "uri": "/v2/enrolments/enrl_abc123"
    }
  ]
}

---

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