Orders API Integration Guide

This guide is for partners building a white-label integration where your platform creates customer organisations, creates merchants, uploads complete order data through the Orders API, receives charge

Reference documentation

What you will build

Your integration should support this lifecycle:

Create one ChargebackStop organisation per customer.
Create one or more merchants inside that organisation.
Create a CUSTOM_ORDERS integration linked to the merchant or merchants.
Upload COMPLETE orders with card transaction identifiers that support chargeback alert matching.
Create chargeback alert enrolments for Ethoca Alerts and/or Verifi RDR.
Receive enrolment.created, enrolment.updated, alert.created, and alert.updated webhooks.
Resolve actionable Ethoca alerts with PATCH /v1/alerts/{alert_id}.
Promote the same flow from a TEST partner account to a LIVE production partner account.

Environments and accounts

ChargebackStop uses the same API host for test and production:

https://api.chargebackstop.com

The account mode controls whether records are TEST or LIVE.

Environment	Account	Purpose	Notes
Development	TEST partner account	Build API client, webhook receiver, order upload, and alert action workflows	Organisations created under a TEST partner become TEST organisations. Simulation endpoints work only with TEST organisations.
Production	LIVE partner account	Create real customer organisations, submit production orders, and receive real alerts	LIVE organisations cannot use simulation endpoints. Real enrolments must be approved/enabled before alerts arrive.

Before you write code

Ask ChargebackStop for a TEST partner account. In that TEST account:

Open the partner dashboard.
Go to the partner settings or administrator group developer settings.
Create a TEST partner API key.
Add a TEST webhook endpoint for enrolment.created, enrolment.updated, alert.created, and alert.updated.
Reveal and store the webhook signing secret.

For local development, expose your webhook receiver through a temporary HTTPS URL, such as a tunnel, because webhook endpoint URLs must be HTTPS.

Authentication and access model

All API requests use a bearer token:

Authorization: Bearer <api_key>
Content-Type: application/json

For partner-owned onboarding, create a partner-group API key in your partner dashboard. Admin partner-group keys can access all organisations under the partner account. Non-admin partner-group keys can access only organisations assigned to that group.

Admin partner key
Restricted partner key

Use an admin partner-group key for automated customer onboarding because it can create organisations, merchants, and enrolments.

Required abilities for the full flow:

organisations:read, organisations:write
merchants:read, merchants:write
integrations:read, integrations:write
orders:read, orders:write, orders:update
enrolments_v2:read, enrolments_v2:write
alerts:read, alerts:write
rulesets:read, rulesets:write if you will create custom RDR resolution rules
simulations:alerts, simulations:enrollments for TEST only

Data you should store

At minimum, store these mappings in your platform:

Your system	ChargebackStop ID	Why it matters
Customer account	`organisation_id`	Required for Orders, Alerts filters, Simulations, and Integrations.
Merchant/MID/CAID/provider account	`merchant_id`	Required for Integrations and Enrolments.
Orders feed connection	`integration_id`	Required for every `COMPLETE` order.
Alert provider enrolment	`enrolment_id`	Required for simulation, enrolment status tracking, and RDR ruleset assignment.
Order	`order_id` and `reference_id`	`reference_id` is your stable idempotency key for create. `order_id` is used for `PATCH /v1/orders/{order_id}`.
Alert	`alert_id`	Required for `GET /v1/alerts/{alert_id}` and `PATCH /v1/alerts/{alert_id}`.

Orders API requirements for alert matching

Send COMPLETE orders as soon as they are available, and backfill recent history before enabling real alert traffic. Agree the backfill window with ChargebackStop during onboarding.

Required order fields for COMPLETE mode:

Field	Description
`type`	Must be `COMPLETE`.
`organisation_id`	Customer organisation ID.
`integration_id`	`CUSTOM_ORDERS` integration ID.
`reference_id`	Stable unique order identifier from your system.
`order_datetime`	ISO 8601 order timestamp.
`order_number`	Customer-facing order number.
`order_subtotal_amount_in_cents`	Subtotal before tax.
`order_currency`	ISO 4217 currency code.
`order_total_amount_in_cents`	Total amount.
`order_status`	`OPEN_PENDING`, `OPEN_PENDING_RETURN`, `CLOSED_COMPLETE`, `CLOSED_CANCELLED`, or `OTHER`.

For alert matching, include at least one transaction per order.

Required transaction fields:

Field	Description
`reference_id`	Stable unique transaction identifier within the integration.
`amount_in_cents`	Transaction amount.
`currency`	ISO 4217 currency code.
`payment_method_type`	Usually `CARD`.
`authorisation_status`	Usually `SETTLED` for completed payments.
`payment_method_reference_id`	Your payment method or payment transaction reference.
`authorised_at`	ISO 8601 authorisation timestamp.
`payment_method_card_brand`	Required for card transactions, for example `VISA` or `MASTERCARD`.
`payment_method_card_last_4`	Required for card transactions.

Send as many matching identifiers as possible:

Identifier	Recommendation
`acquirer_reference_number`	Send whenever available. This is the strongest matching identifier.
`authorisation_code`	Send whenever available, especially with card last 4.
`payment_method_card_bin`	Send whenever available, especially with card brand, last 4, amount, and currency.

Enrolment requirements

Create a separate enrolment for each chargeback alert product the customer will use. Save the returned enrolment_id; it is the identifier you will use for status tracking, TEST simulations, and RDR ruleset assignment.

Ethoca Alerts
Verifi RDR

Use type: ETHOCA_ALERT.

Required enrolment data:

Field	Requirement
`merchant_ids`	One or more merchant IDs from the same organisation.
`ethoca_alert.descriptors`	One or more billing descriptors.
`ethoca_alert.descriptors[].descriptor`	The descriptor text Ethoca should enrol.
`ethoca_alert.descriptors[].match_type`	`STARTS_WITH` or `EXACT_MATCH`.

Ethoca enrolment is descriptor based. Do not use ARN or BIN + CAID as the Ethoca enrolment identifier. ARN, authorisation code, BIN, last 4, amount, currency, and transaction dates belong on Orders API transaction records so alerts can be matched to uploaded orders.

Use type: VERIFI_RDR.

Required enrolment data:

Field	Requirement
`merchant_ids`	One or more merchant IDs from the same organisation.
`verifi_rdr.bin` and `verifi_rdr.caid`	Preferred for BIN + CAID enrolment. Some partners call this BIN + CID; the API field name is `caid`.
`verifi_rdr.arns`	Use this instead of BIN + CAID when the RDR enrolment is ARN based.

Provide either bin and caid together, or provide at least one ARN in arns.

By default, a Verifi RDR BIN + CAID enrolment is published without a custom ruleset. That means eligible RDR cases for that BIN + CAID follow the default RDR flow and are accepted/refunded at the network level. If the customer wants exceptions, create a platform-run resolution ruleset and attach it to the RDR enrolment_id before go-live.

End-to-end TEST flow

Run this flow in a TEST partner account first.

Set your environment variables

export CBS_API_BASE="https://api.chargebackstop.com"
export CBS_API_KEY="cbs_REPLACE_WITH_TEST_PARTNER_API_KEY"

Confirm your key works by listing organisations:

curl -X GET "$CBS_API_BASE/v1/organisations/?limit=10&offset=0" \
  -H "Authorization: Bearer $CBS_API_KEY"

Create a customer organisation

Use one organisation per customer.

curl -X POST "$CBS_API_BASE/v1/organisations/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Fitness"
  }'

Example TEST response:

{
  "id": "org_abc123",
  "name": "[TEST] Acme Fitness",
  "mode": "TEST",
  "created_at": "2026-02-17T10:00:00Z",
  "updated_at": "2026-02-17T10:00:00Z",
  "links": [{"rel": "self", "uri": "/v1/organisations/org_abc123"}]
}

Save organisation_id.

Create a merchant

Use external_id for the merchant identifier your team recognises, such as MID, CAID, or provider account ID.

curl -X POST "$CBS_API_BASE/v1/merchants/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_abc123",
    "name": "Acme Fitness Main Store",
    "type": "GENERIC",
    "external_id": "mid_123456789"
  }'

Example response:

{
  "id": "mrch_abc123",
  "organisation_id": "org_abc123",
  "name": "Acme Fitness Main Store",
  "type": "GENERIC",
  "external_id": "mid_123456789",
  "default_representment_service_type": null,
  "created_at": "2026-02-17T10:02:00Z",
  "updated_at": "2026-02-17T10:02:00Z",
  "links": [{"rel": "self", "uri": "/v1/merchants/mrch_abc123"}]
}

Save merchant_id.

Create a custom orders integration

Create one CUSTOM_ORDERS integration for the orders feed you will use for this customer.

curl -X POST "$CBS_API_BASE/v1/integrations/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_abc123",
    "name": "Acme Fitness Orders API",
    "type": "CUSTOM_ORDERS",
    "status": "ENABLED",
    "merchant_ids": ["mrch_abc123"]
  }'

Example response:

{
  "id": "int_abc123",
  "organisation_id": "org_abc123",
  "name": "Acme Fitness Orders API",
  "type": "CUSTOM_ORDERS",
  "status": "ENABLED",
  "merchant_ids": ["mrch_abc123"],
  "links": [{"rel": "self", "uri": "/v1/integrations/int_abc123"}]
}

Save integration_id.

Create a chargeback alert enrolment

Create one enrolment per product. The examples below use the same merchant, but production customers may need separate enrolments for different descriptors, BIN + CAID pairs, or ARN sets.

Ethoca Alert
Verifi RDR

Ethoca enrolments use descriptors.

curl -X POST "$CBS_API_BASE/v2/enrolments/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ids": ["mrch_abc123"],
    "type": "ETHOCA_ALERT",
    "ethoca_alert": {
      "descriptors": [
        {
          "descriptor": "ACMEFIT",
          "match_type": "STARTS_WITH"
        }
      ]
    }
  }'

Example response:

{
  "id": "enrl_ethoca123",
  "organisation_id": "org_abc123",
  "merchant_ids": ["mrch_abc123"],
  "type": "ETHOCA_ALERT",
  "status": "PENDING",
  "ethoca_alert": {
    "descriptors": [
      {
        "descriptor": "ACMEFIT",
        "match_type": "STARTS_WITH",
        "status": "PENDING"
      }
    ]
  },
  "created_at": "2026-02-17T10:03:00Z",
  "updated_at": "2026-02-17T10:03:00Z",
  "note": null,
  "links": [{"rel": "self", "uri": "/v2/enrolments/enrl_ethoca123"}]
}

Save the Ethoca enrolment_id.

Verifi RDR enrolments use either BIN + CAID or ARNs.

BIN + CAID example:

curl -X POST "$CBS_API_BASE/v2/enrolments/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ids": ["mrch_abc123"],
    "type": "VERIFI_RDR",
    "verifi_rdr": {
      "bin": "424242",
      "caid": "ACMEFITCAID01"
    }
  }'

Example response:

{
  "id": "enrl_rdr123",
  "organisation_id": "org_abc123",
  "merchant_ids": ["mrch_abc123"],
  "type": "VERIFI_RDR",
  "status": "PENDING",
  "verifi_rdr": {
    "bin": "424242",
    "caid": "ACMEFITCAID01",
    "arns": null
  },
  "created_at": "2026-02-17T10:04:00Z",
  "updated_at": "2026-02-17T10:04:00Z",
  "note": null,
  "links": [{"rel": "self", "uri": "/v2/enrolments/enrl_rdr123"}]
}

ARN-based example:

{
  "merchant_ids": ["mrch_abc123"],
  "type": "VERIFI_RDR",
  "verifi_rdr": {
    "arns": ["74027012345678901234567"]
  }
}

Save the RDR enrolment_id. You will need it if the customer wants custom RDR decisioning through a ruleset.

Enable the TEST enrolment for simulations
Section titled “Enable the TEST enrolment for simulations”

Simulation endpoints work only in TEST mode. Mark each TEST enrolment you want to simulate as ENABLED.
```
curl -X PATCH "$CBS_API_BASE/v1/simulate/enrolments/enrl_ethoca123" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ENABLED"
  }'
```
For a Verifi RDR TEST enrolment, use the RDR enrolment_id in the same endpoint.

Submit a COMPLETE order

The Orders API accepts a JSON array, even when you submit one order.

curl -X POST "$CBS_API_BASE/v1/orders/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "type": "COMPLETE",
      "organisation_id": "org_abc123",
      "integration_id": "int_abc123",
      "reference_id": "order-10001",
      "order_datetime": "2026-02-17T09:59:00Z",
      "order_number": "AF-10001",
      "order_subtotal_amount_in_cents": 4900,
      "order_currency": "USD",
      "order_total_amount_in_cents": 4900,
      "order_status": "CLOSED_COMPLETE",
      "customer_email": "casey.jordan@example.com",
      "transactions": [
        {
          "reference_id": "txn-10001",
          "amount_in_cents": 4900,
          "currency": "USD",
          "payment_method_type": "CARD",
          "authorisation_status": "SETTLED",
          "payment_method_reference_id": "pay_10001",
          "authorised_at": "2026-02-17T09:59:05Z",
          "descriptor": "ACMEFIT MONTHLY",
          "payment_method_card_brand": "VISA",
          "payment_method_card_last_4": "4242",
          "payment_method_card_bin": "424242",
          "authorisation_code": "123456",
          "acquirer_reference_number": "74027012345678901234567"
        }
      ]
    }
  ]'

Example response:

{
  "created": 1,
  "failed": 0,
  "results": [
    {
      "id": "ord_abc123",
      "reference_id": "order-10001",
      "type": "COMPLETE",
      "organisation_id": "org_abc123",
      "integration_id": "int_abc123",
      "created_at": "2026-02-17T10:05:00Z",
      "transactions": [
        {
          "reference_id": "txn-10001",
          "amount_in_cents": 4900,
          "currency": "USD",
          "payment_method_type": "CARD",
          "authorisation_status": "SETTLED",
          "payment_method_reference_id": "pay_10001",
          "authorised_at": "2026-02-17T09:59:05Z",
          "payment_method_card_brand": "VISA",
          "payment_method_card_last_4": "4242",
          "payment_method_card_bin": "424242",
          "authorisation_code": "123456",
          "acquirer_reference_number": "74027012345678901234567"
        }
      ],
      "links": [{"rel": "self", "uri": "/v1/orders/ord_abc123"}]
    }
  ],
  "errors": []
}

Save order_id.

Simulate an actionable chargeback alert

Use this to test alert webhooks and alert resolution. The simulator creates a test alert and triggers the same alert.created webhook flow as a non-simulated alert.

curl -X POST "$CBS_API_BASE/v1/simulate/alerts" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_abc123",
    "enrolment_id": "enrl_ethoca123",
    "status": "ACTION_REQUIRED",
    "card_scheme": "VISA",
    "amount_in_cents": 4900,
    "currency_code": "USD",
    "transaction_acquirer_reference_number": "74027012345678901234567",
    "transaction_authorisation_code": "123456"
  }'

Example response:

{
  "id": "netalrt_abc123",
  "alert_network_id": "SIM123456",
  "organisation_id": "org_abc123",
  "merchant_id": "mrch_abc123",
  "enrolment_id": "enrl_ethoca123",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "ACTION_REQUIRED",
  "transaction_amount_in_cents": 4900,
  "transaction_currency_code": "USD",
  "transaction_authorised_at": "2026-02-10T10:30:00Z",
  "action_required_deadline": "2026-02-19T10:30:00Z",
  "transaction_authorisation_code": "123456",
  "transaction_acquirer_reference_number": "74027012345678901234567",
  "transaction_statement_descriptor": "ACMEFIT",
  "transaction_card_bin": "400000",
  "transaction_card_last4": "1234",
  "transaction_card_scheme": "VISA",
  "transaction_card_issuer": "Bank of America",
  "transaction_refund_outcome": null,
  "subscription_cancel_outcome": null,
  "note": null,
  "integration_id": null,
  "integration_transaction_id": null
}

Resolve the simulated alert

For a Custom Orders-only integration, ChargebackStop cannot refund through your processor. Your system should perform the refund, cancellation, or customer handling in your own platform first, then update the alert with the outcome.

If you refunded the customer:

curl -X PATCH "$CBS_API_BASE/v1/alerts/netalrt_abc123" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "REFUND",
    "note": "Refund completed in partner platform before actioning alert."
  }'

If you want to accept/fight the dispute and did not refund:

curl -X PATCH "$CBS_API_BASE/v1/alerts/netalrt_abc123" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "ACCEPT_DISPUTE",
    "note": "Merchant chose not to refund this alert."
  }'

Example response:

{
  "id": "netalrt_abc123",
  "organisation_id": "org_abc123",
  "merchant_id": "mrch_abc123",
  "enrolment_id": "enrl_ethoca123",
  "enrolment_type": "ETHOCA_ALERT",
  "status": "RESOLVED",
  "transaction_refund_outcome": "REFUNDED",
  "note": "Refund completed in partner platform before actioning alert.",
  "links": [{"rel": "self", "uri": "/v1/alerts/netalrt_abc123"}]
}

Webhook implementation

Create a partner webhook endpoint for:

enrolment.created
enrolment.updated
alert.created
alert.updated

Webhook endpoints must be HTTPS and should return a 2xx response within 20 seconds. Use the X-Idempotency-Key header and the event id to prevent duplicate processing. Retries use the same X-Idempotency-Key.

Verify signatures

To verify please refer to the Webhooks documentation.

Process enrolment webhooks

Use enrolment webhooks to manage whether a customer enrolment is live in your product.

Example enrolment.updated payload:

{
  "id": "evt_enrolmentupdated123",
  "type": "enrolment.updated",
  "created_at": "2026-02-17T10:30:00Z",
  "data": {
    "object": {
      "id": "enrl_rdr123",
      "organisation_id": "org_abc123",
      "merchant_ids": ["mrch_abc123"],
      "type": "VERIFI_RDR",
      "status": "ENABLED",
      "verifi_rdr": {
        "bin": "424242",
        "caid": "ACMEFITCAID01",
        "arns": null
      },
      "created_at": "2026-02-17T10:04:00Z",
      "updated_at": "2026-02-17T10:30:00Z",
      "note": null
    },
    "previous_attributes": {
      "status": "PENDING"
    }
  },
  "api_version": "v2"
}

Recommended handling:

Enrolment status	Partner system behavior
`PENDING`	Store the enrolment and show it as submitted, not live.
`IN_PROGRESS`	Show it as being configured by ChargebackStop or the alert provider.
`ACTION_REQUIRED`	Block go-live for that enrolment and show the customer-facing `note` to your operations team or customer success team.
`ENABLED`	Mark the enrolment live. Start expecting alerts for that product and identifier.
`FAILED`	Mark the enrolment failed and escalate with the `note` and enrolment ID.
`CANCELLED`, `PAUSED`, `UNENROLLED`	Mark the enrolment inactive. Stop treating the identifier as live for new alert traffic.

Process alert webhooks

Use this webhook processing pattern:

Verify X-Signature.
Store event id, type, created_at, api_version, and data.object.
Deduplicate by event id. You may also store X-Idempotency-Key for delivery tracing.
Return 2xx quickly.
Process the alert asynchronously.
Fetch the latest alert with GET /v1/alerts/{alert_id} before taking irreversible action.

Example alert.created decision logic:

if alert.status == "ACTION_REQUIRED" and alert.enrolment_type == "ETHOCA_ALERT":
    show alert to merchant or run partner decisioning
    if merchant_refunded_in_partner_platform:
        PATCH /v1/alerts/{id} {"action": "REFUND"}
    else if merchant_accepts_or_fights_dispute:
        PATCH /v1/alerts/{id} {"action": "ACCEPT_DISPUTE"}
else:
    store alert as informational

Alert resolution rules

Ethoca and Verifi RDR resolve differently.

Provider	Alert behavior	What your integration must do
Ethoca Alerts (`ETHOCA_ALERT`)	Alerts can arrive in `ACTION_REQUIRED` with `action_required_deadline`.	Decide quickly, perform any off-platform refund/cancellation first, then call `PATCH /v1/alerts/{alert_id}`.
Verifi RDR (`VERIFI_RDR`)	Alerts are resolved at the network level and arrive as `RESOLVED` or `INVALID`.	Configure RDR rules before go-live if needed. Do not expect an action-required workflow.

Ethoca alert resolution

For Custom Orders-only integrations, the usual manual actions are:

API action	Use when	Result
`REFUND`	You refunded the transaction in your own platform.	Alert is marked resolved with refunded outcome.
`ACCEPT_DISPUTE`	You did not refund and will accept or fight the dispute outside the alert workflow.	Alert is marked resolved with not-refunded outcome.

Use CANCEL and REFUND_AND_CANCEL only when your ChargebackStop setup has the processor/subscription context needed to support those actions, or when ChargebackStop confirms they fit your workflow.

Verifi RDR default decisioning

For Verifi RDR, the default path is intentionally simple:

Create a VERIFI_RDR enrolment for the customer's BIN + CAID.
Wait until the enrolment becomes ENABLED.
If no platform-run ruleset is attached to that RDR enrolment, eligible RDR cases for that BIN + CAID are accepted/refunded by default at the network level.

RDR alerts generally arrive in ChargebackStop after the network decision has already happened. They should be stored and reconciled, not routed into an ACTION_REQUIRED queue.

Customise Verifi RDR with a ruleset

Create a platform-run ruleset only when the customer wants exceptions to the default RDR refund flow. Attach the ruleset to the RDR enrolment_id.

RDR ruleset constraints:

Constraint	Detail
Required API abilities	`rulesets:read` and `rulesets:write`.
Endpoint	`POST /v1/rulesets/`.
Enrolments	Use one or more `VERIFI_RDR` BIN + CAID enrolment IDs from the same organisation. Confirm with ChargebackStop before relying on custom rulesets for ARN-based RDR enrolments.
Ruleset count	Each enrolment can have one platform-run ruleset.
Outcomes for RDR	Use `REFUND` or `ACCEPT_DISPUTE`. `REFUND_AND_CANCEL` is published to Verifi as `REFUND`; handle cancellation in your own system. Do not use `CANCEL` for RDR decisioning.
Rule types	`AMOUNT` and `DESCRIPTOR`. Only one rule of each type is allowed per ruleset.
Amount currency	Must be `USD`.

Example: keep the default refund behavior for most RDR cases, but accept the dispute instead of refunding when the amount is greater than $100 or the descriptor starts with ACMEFIT HIGHVALUE.

curl -X POST "$CBS_API_BASE/v1/rulesets/" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_abc123",
    "enrolment_ids": ["enrl_rdr123"],
    "outcome": "ACCEPT_DISPUTE",
    "join_operator": "OR",
    "rules": [
      {
        "type": "AMOUNT",
        "parameters": {
          "operator": "GREATER_THAN",
          "currency_code": "USD",
          "amount_in_cents": 10000
        }
      },
      {
        "type": "DESCRIPTOR",
        "parameters": {
          "descriptors": [
            {
              "value": "ACMEFIT HIGHVALUE",
              "match_type": "STARTS_WITH"
            }
          ]
        }
      }
    ]
  }'

Example response:

{
  "id": "rset_abc123",
  "organisation_id": "org_abc123",
  "enrolment_ids": ["enrl_rdr123"],
  "outcome": "ACCEPT_DISPUTE",
  "join_operator": "OR",
  "rules": [
    {
      "id": "resrule_amount123",
      "type": "AMOUNT",
      "parameters": {
        "operator": "GREATER_THAN",
        "currency_code": "USD",
        "amount_in_cents": 10000
      },
      "created_at": "2026-02-17T10:10:00Z",
      "updated_at": "2026-02-17T10:10:00Z"
    },
    {
      "id": "resrule_descriptor123",
      "type": "DESCRIPTOR",
      "parameters": {
        "descriptors": [
          {
            "value": "ACMEFIT HIGHVALUE",
            "match_type": "STARTS_WITH"
          }
        ]
      },
      "created_at": "2026-02-17T10:10:00Z",
      "updated_at": "2026-02-17T10:10:00Z"
    }
  ],
  "created_at": "2026-02-17T10:10:00Z",
  "updated_at": "2026-02-17T10:10:00Z"
}

To update an existing ruleset:

Use PATCH /v1/rulesets/{ruleset_id} for enrolment_ids, outcome, or join_operator.
Use PATCH /v1/rulesets/{ruleset_id}/rules/{rule_id} for rule criteria.
Do not send rules to PATCH /v1/rulesets/{ruleset_id}; rule updates are handled by the nested rule endpoints.

Order update patterns

Create orders once with POST /v1/orders/. Use PATCH /v1/orders/{order_id} to add or update later lifecycle data such as refunds, disputes, delivery status, subscription status, or order communications.

Example refund update:

curl -X PATCH "$CBS_API_BASE/v1/orders/ord_abc123" \
  -H "Authorization: Bearer $CBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refunds": [
      {
        "reference_id": "refund-10001",
        "amount_in_cents": 4900,
        "currency": "USD",
        "status": "SUCCEEDED",
        "original_transaction_reference_id": "txn-10001",
        "refund_datetime": "2026-02-17T11:20:00Z"
      }
    ]
  }'

Error handling and retries

The Orders API uses partial success after schema validation. One valid order in a batch can be created even if another order in the same batch fails.

Handle these cases explicitly:

Case	Recommended handling
`200` with `failed > 0`	Some orders in the batch were rejected. Route the entries in `errors[]` to a retry or investigation queue.
`400` fully-failed batch	Every order was rejected; nothing was created. Same body shape as `200` — inspect `errors[]`.
`429 RATE_LIMITED`	Retry with exponential backoff. Limits are 100 requests per minute per endpoint per organisation or partner group.
`DUPLICATE_ORDER`	Treat as a reconciliation case. Fetch the order with `GET /v1/orders/?reference_id=<reference_id>`.
`INVALID_ORDER_TYPE`	Ensure `COMPLETE` orders use a `CUSTOM_ORDERS` integration.
`INVALID_INTEGRATION`	Check `integration_id`, organisation access, and integration status.
`MISSING_FIELD`	Validate payloads before enqueueing. Required fields can depend on order mode and enabled product features.
`422` schema validation	No orders were processed. Fix the top-level request shape or field types and retry.
`5xx`	Retry safely with the same `reference_id` values.

Sandbox acceptance checklist

Complete this checklist before asking ChargebackStop to move you to production.

Production launch checklist

When sandbox testing is complete, ChargebackStop will provision or enable your LIVE production partner account.

Create production credentials
Section titled “Create production credentials”

In the LIVE partner account:
1. Create a new production partner API key.
2. Store it in your production secrets manager.
3. Register a production HTTPS webhook endpoint.
4. Select enrolment.created, enrolment.updated, alert.created, and alert.updated.
5. Reveal and store the webhook signing secret.
Do not reuse TEST API keys or TEST webhook secrets.
Create production customer records
Section titled “Create production customer records”

For each production customer:
1. Create the organisation.
2. Create the merchant or merchants.
3. Create the CUSTOM_ORDERS integration.
4. Save all returned IDs in your production database.
Production organisation mode will be LIVE.
Submit production order history
Section titled “Submit production order history”

Before alert traffic begins, backfill recent complete order history for each customer. Include transaction matching identifiers, refunds, and disputes wherever available.

Monitor:
- Orders accepted vs failed
- Duplicate references
- Missing ARN/auth code/BIN coverage
- Rate limiting
- Payload validation errors
Create real chargeback alert enrolments
Section titled “Create real chargeback alert enrolments”

Create real Ethoca Alert and/or Verifi RDR enrolments using production descriptors, BIN/CAID, or ARNs.

For RDR, create any custom rulesets before go-live if the customer does not want the default accept/refund flow for every eligible BIN + CAID case.

Enrolments are created in PENDING. Treat an enrolment as live only after enrolment.updated or GET /v2/enrolments/{enrolment_id} returns status: "ENABLED".
Verify first production alerts
Section titled “Verify first production alerts”

For the first real alerts:
1. Confirm your webhook receives the enrolment events and marks each live enrolment ENABLED.
2. Fetch the latest alert via GET /v1/alerts/{alert_id}.
3. Check whether integration_id and integration_transaction_id are present for matched alerts.
4. Confirm your refund/accept-dispute workflow resolves Ethoca alerts before action_required_deadline.
5. Confirm alert.updated arrives after resolution.
Escalate unmatched alerts to ChargebackStop with the alert ID, order reference, transaction reference, ARN, auth code, card brand, BIN, last 4, amount, currency, and timestamps.

Operational recommendations

Send orders continuously, not only after an alert is received.
Keep webhook handlers fast. Verify, persist, enqueue, and return 2xx.
Use enrolment.updated and GET /v2/enrolments/{enrolment_id} to drive customer-facing enrolment status.
Poll GET /v1/alerts?status=ACTION_REQUIRED as a fallback if webhook delivery is interrupted.
Alert your operations team well before action_required_deadline.
Treat REFUND as a declaration that your system has already refunded when using Custom Orders without a processor integration.
Create RDR rulesets before go-live when the customer wants exceptions to the default RDR accept/refund behavior.
Keep TEST and LIVE credentials, webhook secrets, IDs, and queues separate.
Rotate API keys immediately after suspected exposure.

Orders API Integration Guide

Reference documentation

What you will build

Environments and accounts

Before you write code

Authentication and access model

Data you should store

Orders API requirements for alert matching

Enrolment requirements

End-to-end TEST flow

Set your environment variables

Create a customer organisation

Create a merchant

Create a custom orders integration

Create a chargeback alert enrolment

Enable the TEST enrolment for simulations

Submit a COMPLETE order

Simulate an actionable chargeback alert

Resolve the simulated alert

Webhook implementation

Verify signatures

Process enrolment webhooks

Process alert webhooks

Alert resolution rules

Ethoca alert resolution

Verifi RDR default decisioning

Customise Verifi RDR with a ruleset

Order update patterns

Error handling and retries

Sandbox acceptance checklist

Production launch checklist

Create production credentials

Create production customer records

Submit production order history

Create real chargeback alert enrolments

Verify first production alerts

Operational recommendations