Enrolments

Create, list, retrieve, update, 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, PATCH, 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}

PATCH /v2/enrolments/{enrolment_id} is v2 only. It has no v1 equivalent.

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, with one addition: v2 responses include ethoca_alert.descriptors[].status, which v1 responses do not return.

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

The ETHOCA_ALERT and VERIFI_RDR type values work the same way in v1 and v2. Order Insight and Consumer Clarity enrolments are available in v2 only.
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
Section titled “Switch routes”

Switch all enrolments routes from /v1/enrolments to /v2/enrolments.
Update API key abilities
Section titled “Update API key abilities”

Ensure API keys include enrolments_v2:read and enrolments_v2:write.
Update payloads
Section titled “Update payloads”

Update create payload builders from merchant_id to merchant_ids.
Update response parsing
Section titled “Update response parsing”

Update response parsing from merchant_id to merchant_ids across create/list/get/delete flows.
Handle new 422 codes
Section titled “Handle new 422 codes”

Add handling for new 422 codes: DUPLICATE_MERCHANT_IDS and MERCHANTS_DIFFERENT_ORGANISATIONS.
Re-run tests
Section titled “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.

This section covers ETHOCA_ALERT and VERIFI_RDR enrolments. VERIFI_ORDER_INSIGHT and ETHOCA_CONSUMER_CLARITY enrolments are enabled individually for each partner account. For these types, see Create Order Insight or Consumer Clarity enrolment.

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.
In responses, ethoca_alert.descriptors[].status is read-only and set by the platform. Its value is PENDING, ACTIVE, or SUPPRESSED. Do not send it in a create request. This field is v2 only — the v1 enrolments endpoint does not return it.

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.

Each descriptor carries its own status that tracks this lifecycle: PENDING while Ethoca is still validating it, ACTIVE once it is live, and SUPPRESSED when it is no longer matched. A descriptor becoming ACTIVE emits an enrolment.updated webhook, so you can follow individual descriptors instead of polling.

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"
    }
  ]
}

PATCH /v2/enrolments/{enrolment_id} - Append Ethoca descriptors

Append one or more Ethoca Alert descriptors to an existing enrolment. This endpoint never removes or modifies existing descriptors.

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

URL parameters

Parameter	Type	Description
`enrolment_id`	string	Enrolment ID to update

Request body

Field	Type	Required	Validation	Description
`ethoca_alert`	object	Conditionally	Required for `ETHOCA_ALERT` enrolments	Ethoca Alert descriptors to append

Ethoca Alert configuration

Field	Type	Required	Validation	Description
`descriptors`	array[object]	Yes	At least one descriptor	Descriptor rules to append
`descriptors[].descriptor`	string	Yes	Minimum length 1	Descriptor text
`descriptors[].match_type`	string	Yes	`STARTS_WITH` or `EXACT_MATCH`	Descriptor matching mode

Important behaviour

Currently only ETHOCA_ALERT enrolments can be updated. Other types return 422 ENROLMENT_TYPE_NOT_SUPPORTED.
Descriptors can be appended when enrolment status is PENDING, IN_PROGRESS, ACTION_REQUIRED, or ENABLED. Other statuses return 422 ENROLMENT_STATUS_NOT_APPENDABLE.
The enrolment-level status does not change.
New descriptors are created with a read-only status of PENDING.
A descriptor with the same descriptor and match_type as an existing descriptor is rejected with 422 DUPLICATE_DESCRIPTOR.
Duplicate descriptor and match_type pairs in the same request are also rejected with 422 DUPLICATE_DESCRIPTOR.
Appending descriptors emits an enrolment.updated webhook with previous_attributes.ethoca_alert.descriptors.

Example 5 request

curl -X PATCH "https://api.chargebackstop.com/v2/enrolments/enrl_abc123" \
  -H "Authorization: Bearer <partner_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ethoca_alert": {
      "descriptors": [
        {
          "descriptor": "SHOP.COM",
          "match_type": "EXACT_MATCH"
        }
      ]
    }
  }'

Example 5 response

{
  "id": "enrl_abc123",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123", "mrch_def456"],
  "type": "ETHOCA_ALERT",
  "status": "ENABLED",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ECOMM.COM",
        "match_type": "STARTS_WITH",
        "status": "ACTIVE"
      },
      {
        "descriptor": "SHOP.COM",
        "match_type": "EXACT_MATCH",
        "status": "PENDING"
      }
    ]
  },
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T13: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 6 request

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

Example 6 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"
    }
  ]
}

POST /v2/enrolments - Create Order Insight or Consumer Clarity enrolment

Create a Verifi Order Insight or Ethoca Consumer Clarity enrolment from an existing enrolment for the same merchants.

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

These enrolment types must be enabled for your partner account. Contact support to enable them. Until then, the API returns 422 INVALID_ENROLMENT_TYPE and responses do not include verifi_order_insight or ethoca_consumer_clarity.

Request body

Field	Type	Required	Validation	Description
`merchant_ids`	array[string]	Yes	Must match the merchants on the source enrolment	Merchants to associate with the enrolment
`type`	string	Yes	`VERIFI_ORDER_INSIGHT` or `ETHOCA_CONSUMER_CLARITY`	Enrolment type
`verifi_order_insight`	object	Conditionally	Required when `type` is `VERIFI_ORDER_INSIGHT`	Order Insight configuration
`ethoca_consumer_clarity`	object	Conditionally	Required when `type` is `ETHOCA_CONSUMER_CLARITY`	Consumer Clarity configuration

Order Insight and Consumer Clarity configuration

Field	Type	Required	Validation	Description
`source_enrolment_id`	string	Yes	A `VERIFI_RDR` enrolment for Order Insight, or an `ETHOCA_ALERT` enrolment for Consumer Clarity	The enrolment to create from
`deflection_enabled`	boolean	Yes	`true` or `false`	Request Compelling Evidence 3.0 for Order Insight, or First Party Trust for Consumer Clarity

Important behaviour

The source enrolment must be in the same organisation as the merchants. Its status must be PENDING, IN_PROGRESS, ACTION_REQUIRED, or ENABLED.
A source enrolment can have only one active enrolment created from it. If that enrolment is cancelled or fails, you can create a new one.
Order Insight copies the Visa BIN, CAID, and ARNs from the source enrolment when the enrolment is created. Later changes to the source enrolment are not copied. If the source enrolment has ARNs only, bin and caid appear after our team completes the enrolment.
The enrolment is created in PENDING status. Our team then completes the enrolment with the network. To track its status, use the GET endpoint or subscribe to the enrolment.updated webhook.
PATCH does not support these enrolment types. DELETE works for enrolments in PENDING status.

Example 7 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_ORDER_INSIGHT",
    "verifi_order_insight": {
      "source_enrolment_id": "enrl_def456",
      "deflection_enabled": true
    }
  }'

Example 7 response

{
  "id": "enrl_ghi789",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123"],
  "type": "VERIFI_ORDER_INSIGHT",
  "status": "PENDING",
  "verifi_order_insight": {
    "bin": "424242",
    "caid": "ABC1234567",
    "source_enrolment_id": "enrl_def456",
    "deflection_enabled": true
  },
  "created_at": "2026-02-16T12:10:00Z",
  "updated_at": "2026-02-16T12:10:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v2/enrolments/enrl_ghi789"
    }
  ]
}

Example 8 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": "ETHOCA_CONSUMER_CLARITY",
    "ethoca_consumer_clarity": {
      "source_enrolment_id": "enrl_abc123",
      "deflection_enabled": false
    }
  }'

Example 8 response

{
  "id": "enrl_jkl012",
  "organisation_id": "org_xyz456",
  "merchant_ids": ["mrch_abc123"],
  "type": "ETHOCA_CONSUMER_CLARITY",
  "status": "PENDING",
  "ethoca_consumer_clarity": {
    "source_enrolment_id": "enrl_abc123",
    "deflection_enabled": false
  },
  "created_at": "2026-02-16T12:15:00Z",
  "updated_at": "2026-02-16T12:15:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v2/enrolments/enrl_jkl012"
    }
  ]
}

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
`ENROLMENT_TYPE_NOT_SUPPORTED`	PATCH is not supported for this enrolment type
`ENROLMENT_STATUS_NOT_APPENDABLE`	Enrolment status does not allow appending descriptors
`DUPLICATE_DESCRIPTOR`	Descriptor and match type already exist or are duplicated in the request
`INVALID_ENROLMENT_TYPE`	This enrolment type is not available for your partner account
`MISSING_VERIFI_ORDER_INSIGHT_CONFIG`	`verifi_order_insight` is required for `VERIFI_ORDER_INSIGHT` enrolments
`MISSING_ETHOCA_CONSUMER_CLARITY_CONFIG`	`ethoca_consumer_clarity` is required for `ETHOCA_CONSUMER_CLARITY` enrolments
`INVALID_SOURCE_ENROLMENT_TYPE`	The source enrolment has the wrong type
`INVALID_SOURCE_ENROLMENT_STATUS`	The source enrolment status does not allow this request
`MERCHANTS_DO_NOT_MATCH_SOURCE`	`merchant_ids` does not match the merchants on the source enrolment
`SOURCE_ENROLMENT_INCOMPLETE`	The source enrolment has no Visa BIN and CAID and no Visa ARNs
`ENROLMENT_ALREADY_EXISTS`	An active enrolment already exists for the source enrolment, or for its Visa BIN and CAID

Enrolments

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

Ethoca descriptor validation

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

PATCH /v2/enrolments/{enrolment_id} - Append Ethoca descriptors

URL parameters

Request body

Ethoca Alert configuration

Important behaviour

Example 5 request

Example 5 response

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

URL parameters

Important behaviour

Example 6 request

Example 6 response

POST /v2/enrolments - Create Order Insight or Consumer Clarity enrolment

Request body

Order Insight and Consumer Clarity configuration

Important behaviour

Example 7 request

Example 7 response

Example 8 request

Example 8 response

Common error responses

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