Enroll merchants in alerts

You are a platform that wants your merchants covered by pre-chargeback alerts without sending them to a dashboard. This guide takes one merchant from no enrollment to alerts flowing, using the alert enrollment endpoints in API v3.

What you'll build

An alert enrollment covers one billing descriptor on one processor for one merchant. Each enrollment carries one or more alert programs, and every program confirms on its own schedule, so you track them separately.

How alerts deflect chargebacks is covered in Alerts model.

Prerequisites

• A platform API key with v3 access, shaped cf_live_<key_id>_<secret>. v3 sends it as Authorization: Bearer, not in the x-api-key header the 2025-04-01 API uses. A merchant key is refused with 403 WRONG_KEY_TYPE.
• The merchant's chargeflow_id, the 24-character account ID of a merchant in your portfolio.
• The merchant onboarded with Alerts. v3 has no endpoint for this step. Step 1 tells you whether it is done.
• The billing descriptor exactly as it appears on the cardholder's statement, and the processor it bills through.

The snippets read the key from CHARGEFLOW_PLATFORM_API_KEY:

export CHARGEFLOW_PLATFORM_API_KEY="YOUR_PLATFORM_API_KEY"

curl https://api.chargeflow.io/v3/merchants/00000000d0c5000000000001/alert_account \
  -H "Authorization: Bearer $CHARGEFLOW_PLATFORM_API_KEY"

{
  "object": "alert_account",
  "chargeflow_id": "00000000d0c5000000000001",
  "created_at": "2026-08-12T09:30:00Z",
  "settings": {
    "alerts_only": false,
    "manual_billing": false,
    "transaction_linking_disabled": false,
    "payment_method_authorized": true
  },
  "payment_method_authorized_at": "2026-08-12T09:31:00Z",
  "last_disenrollment_requested_at": null,
  "enrollment_count": 0,
  "provider_status_counts": {
    "in_progress": 0,
    "enrolled": 0,
    "active": 0,
    "in_process_of_disenrollment": 0,
    "disenrolled": 0,
    "dropped": 0
  },
  "livemode": true
}

curl -X POST https://api.chargeflow.io/v3/alert_enrollments \
  -H "Authorization: Bearer $CHARGEFLOW_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chargeflow_id": "00000000d0c5000000000001",
    "psp": "stripe",
    "descriptor": "EXAMPLE*STORE",
    "providers": ["ethoca", "cdrn"]
  }'

{
  "id": "aen_00000000d0c5000000000001-00000000-d0c5-4000-8000-000000000003",
  "object": "alert_enrollment",
  "created_at": "2026-08-12T09:30:00Z",
  "updated_at": "2026-08-12T09:30:00Z",
  "livemode": true,
  "psp": "stripe",
  "chargeflow_id": "00000000d0c5000000000001",
  "descriptor": "EXAMPLE*STORE",
  "providers": [
    {
      "provider": "ethoca",
      "status": "in_progress",
      "status_reason": "sent_to_enrollment",
      "retryable": null,
      "enrolled_at": null,
      "alerts_stopped_at": null,
      "updated_at": "2026-08-12T09:30:00Z"
    },
    {
      "provider": "cdrn",
      "status": "in_progress",
      "status_reason": "sent_to_enrollment",
      "retryable": null,
      "enrolled_at": null,
      "alerts_stopped_at": null,
      "updated_at": "2026-08-12T09:30:00Z"
    }
  ],
  "card_acceptor_id": null,
  "bin": null,
  "arns": []
}

curl -X POST https://api.chargeflow.io/v3/webhooks/registrations \
  -H "Authorization: Bearer $CHARGEFLOW_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_target": "https://example.com/hooks/chargeflow",
    "event_types": ["alerts.enrollment.status_changed"]
  }'

{
  "id": "whr_d0c5000001",
  "object": "webhook_registration",
  "url_target": "https://example.com/hooks/chargeflow",
  "event_types": ["alerts.enrollment.status_changed"],
  "is_active": true,
  "created_at": "2026-08-12T09:32:00.000Z",
  "updated_at": "2026-08-12T09:32:00.000Z",
  "livemode": true,
  "signing_secret": "YOUR_SIGNING_SECRET"
}

{
  "webhookId": "whd_d0c5000001",
  "eventId": "evt_d0c5000001",
  "creationDate": "2026-08-13T08:00:03.000Z",
  "type": "alerts.enrollment.status_changed",
  "livemode": true,
  "data": {
    "enrollment_id": "aen_00000000d0c5000000000001-00000000-d0c5-4000-8000-000000000003",
    "chargeflow_id": "00000000d0c5000000000001",
    "descriptor": "EXAMPLE*STORE",
    "psp": "stripe",
    "provider": "ethoca",
    "status": "enrolled",
    "status_reason": null,
    "occurred_at": "2026-08-13T08:00:02.381Z"
  }
}

Verify it worked

Retrieve the enrollment and read each program's status. This is also the fallback when a webhook is missed.

curl https://api.chargeflow.io/v3/alert_enrollments/aen_00000000d0c5000000000001-00000000-d0c5-4000-8000-000000000003 \
  -H "Authorization: Bearer $CHARGEFLOW_PLATFORM_API_KEY"

You should see the same object the create returned, with each entry in providers at its current status. To see every enrollment for a merchant, use List alert enrollments with chargeflow_id.

Read the status

Every program on an enrollment has its own status:

When a program is refused

A refused program does not get its own status: it stays in_progress with an error in status_reason and a retryable flag. Branch on retryable.

Every reason and its meaning is listed on Retrieve an alert enrollment.

Enroll many descriptors at once

A merchant with several descriptors can be enrolled in one call: up to 25 items, all for the same merchant. Each item takes the same fields as a single create, without chargeflow_id.

curl -X POST https://api.chargeflow.io/v3/alert_enrollments/bulk \
  -H "Authorization: Bearer $CHARGEFLOW_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chargeflow_id": "00000000d0c5000000000001",
    "enrollments": [
      { "psp": "stripe", "descriptor": "EXAMPLE*STORE" },
      { "psp": "adyen", "descriptor": "EXAMPLE*STORE EU", "providers": ["ethoca", "rdr"] }
    ]
  }'

You should see a 207 with one result per item, in request order. A 207 does not mean every item succeeded: check each item's status. A 200 or 202 carries alert_enrollment, anything else carries error.

{
  "results": [
    {
      "index": 0,
      "status": 200,
      "alert_enrollment": {
        "id": "aen_00000000d0c5000000000001-00000000-d0c5-4000-8000-000000000003",
        "object": "alert_enrollment",
        "created_at": "2026-08-12T09:30:00Z",
        "updated_at": "2026-08-12T09:30:00Z",
        "livemode": true,
        "psp": "stripe",
        "chargeflow_id": "00000000d0c5000000000001",
        "descriptor": "EXAMPLE*STORE",
        "providers": [
          {
            "provider": "ethoca",
            "status": "in_progress",
            "status_reason": "sent_to_enrollment",
            "retryable": null,
            "enrolled_at": null,
            "alerts_stopped_at": null,
            "updated_at": "2026-08-12T09:30:00Z"
          }
        ],
        "card_acceptor_id": null,
        "bin": null,
        "arns": []
      }
    },
    {
      "index": 1,
      "status": 422,
      "error": {
        "type": "validation_error",
        "code": "MISSING_FIELD",
        "message": "card_acceptor_id is required for rdr.",
        "field": "card_acceptor_id",
        "request_id": "00000000-d0c5-4000-8000-000000000004"
      }
    }
  ]
}

Resend only the items that failed with 500, 502 or 504: a retry is safe. A 422 item needs a fix first.

Stop an enrollment

Disenroll some programs by naming them in providers, or all of them by sending no body.

curl -X POST https://api.chargeflow.io/v3/alert_enrollments/aen_00000000d0c5000000000001-00000000-d0c5-4000-8000-000000000003/disenrollments \
  -H "Authorization: Bearer $CHARGEFLOW_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "providers": ["cdrn"], "reason": "Merchant request" }'

You should see a 202 with the enrollment, and the named program at in_process_of_disenrollment. It moves to disenrolled once the network confirms, which can take days. Until then the program is still billable and alerts can keep arriving, so keep handling them. The enrollment stays readable at the same id, and creating it again re-enrolls it.

Troubleshooting

Error bodies, and which statuses are safe to retry, are on v3 errors.

Next step