Simulations

Generate test enrolment states and test alerts for TEST mode organisations.

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

Authentication: Bearer token via API key.

Required abilities:

• simulations:enrollments for PATCH /v1/simulate/enrolments/{enrolment_id}

• simulations:alerts for POST /v1/simulate/alerts

Access scope model:

• Organisation-level keys can simulate data for their own organisation only.

• Admin partner-group keys can simulate data across all organisations for their partner.

• Non-admin partner-group keys can simulate data only for organisations assigned to their group.

Typical simulation flow:

1

Create an enrolment

Create an enrolment with /v2/enrolments.

2

Enable the enrolment for simulation

Set that enrolment to ENABLED with:

PATCH /v1/simulate/enrolments/{enrolment_id}

3

Generate a simulated alert

Generate a simulated alert with POST /v1/simulate/alerts.

---

PATCH /v1/simulate/enrolments/{enrolment_id} - update enrolment simulation status

Updates an enrolment status for simulation use.

API level: Organisation-level and partner-level Authentication: simulations:enrollments

URL parameters

Parameter	Type	Description
enrolment_id	string	Enrolment ID to update

Request body

Field	Type	Required	Description
status	string	Yes	New enrolment status: ENABLED or UNENROLLED

Important behaviour

• This endpoint is only available for TEST mode organisations.

• The enrolment must be accessible to the authenticated API key.

• For ETHOCA_ALERT enrolments, setting status to ENABLED activates configured descriptors for simulation matching.

Example request

curl -X PATCH "https://api.chargebackstop.com/v1/simulate/enrolments/enrl_abc456" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ENABLED"
  }'

Example response

{
  "id": "enrl_abc456",
  "organisation_id": "org_test123",
  "merchant_id": "mrch_abc123",
  "type": "ETHOCA_ALERT",
  "status": "ENABLED",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "TESTMERCHANT.COM",
        "match_type": "EXACT_MATCH"
      }
    ]
  },
  "verifi_rdr": null,
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-16T08:15:00Z",
  "note": null
}

---

POST /v1/simulate/alerts - create simulated alert

Creates a simulated network alert.

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

Request body

Field	Type	Required	Description
organisation_id	string	Yes	Organisation ID. Must be in TEST mode and accessible to the key
enrolment_id	string	Yes	Enrolment ID that belongs to organisation_id
status	string	No	Alert status: ACTION_REQUIRED, RESOLVED, INVALID. Verifi RDR only supports RESOLVED or INVALID
transaction_refund_outcome	string	No	Refund outcome: REFUNDED or NOT_REFUNDED. Only valid with status=RESOLVED
card_scheme	string	No	Card scheme. Use any supported scheme value, for example VISA, MASTERCARD, AMEX
amount_in_cents	integer	No	Transaction amount in cents. Must be a positive integer
currency_code	string	No	ISO 4217 currency code, for example USD, EUR, GBP
transaction_acquirer_reference_number	string	No	ARN. Must be exactly 23 characters
transaction_authorisation_code	string	No	Authorisation code. Must be exactly 6 characters

Important behaviour

• This endpoint is only available for TEST mode organisations.

• If status is omitted, the simulator chooses a valid status.

• If transaction_refund_outcome is provided without status, the created alert is set to RESOLVED.

• Simulated alerts trigger the same alert.created event flow as non-simulated alerts.

Example request

curl -X POST "https://api.chargebackstop.com/v1/simulate/alerts" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_test123",
    "enrolment_id": "enrl_abc456",
    "status": "RESOLVED",
    "transaction_refund_outcome": "REFUNDED",
    "card_scheme": "VISA",
    "amount_in_cents": 5000,
    "currency_code": "USD"
  }'

Example response

{
  "id": "netalrt_xyz789",
  "alert_network_id": "SIM123456",
  "organisation_id": "org_test123",
  "merchant_id": "mrch_abc123",
  "enrolment_id": "enrl_abc456",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "RESOLVED",
  "chargeback_reason_code": null,
  "transaction_amount_in_cents": 5000,
  "transaction_currency_code": "USD",
  "transaction_authorised_at": "2026-02-10T10:30:00Z",
  "action_required_deadline": null,
  "transaction_authorisation_code": "ABC123",
  "transaction_acquirer_reference_number": "12345678901234567890123",
  "transaction_statement_descriptor": "TESTMERCHANT.COM",
  "transaction_card_bin": "400000",
  "transaction_card_last4": "1234",
  "transaction_card_scheme": "VISA",
  "transaction_card_issuer": "Bank of America",
  "transaction_refund_outcome": "REFUNDED",
  "transaction_network_id": null,
  "subscription_cancel_outcome": null,
  "note": null,
  "created_at": "2026-02-16T08:20:00Z",
  "updated_at": "2026-02-16T08:20:00Z",
  "integration_id": null,
  "integration_transaction_id": null
}

---

Common error responses

Error responses use this shape:

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

Example: 401 Unauthorised

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

Example: 403 Forbidden

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

Example: 404 Not found

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

Example: 422 Unprocessable Entity (simulation not allowed)

{
  "errors": [
    {
      "code": "SIMULATION_NOT_ALLOWED",
      "message": "Alert simulation is only allowed for TEST mode organisations. Production Org is in LIVE mode."
    }
  ]
}

Example: 422 Unprocessable Entity (simulation validation error)

{
  "errors": [
    {
      "code": "SIMULATION_VALIDATION_ERROR",
      "message": "Invalid currency_code 'INVALID'. Must be a valid ISO 4217 code."
    }
  ]
}

Example: 422 Unprocessable Entity (invalid enum value)

{
  "errors": [
    {
      "code": "VALIDATION_ENUM",
      "message": "Validation error at ('body', 'data', 'status'). Input should be 'ENABLED' or 'UNENROLLED'."
    }
  ]
}

Additional reference: 500 Server error

{
  "errors": [
    {
      "code": "SERVER_ERROR",
      "message": "Server error"
    }
  ]
}