Soon (v3)
Alerts
Enroll descriptors in alert programs and track each provider leg
Was this page helpful?
Enroll descriptors in alert programs and track each provider leg
bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
How many objects to return. 1 to 100.
1 <= value <= 10020Opaque. Pass the next_cursor from the previous response to fetch the page after it; omit it for the first page. Do not construct or parse this value.
Which of your merchants to list enrollments for. A merchant outside your portfolio is 403 merchant_not_in_portfolio.
^[0-9a-f]{24}$The unit of enrollment, so the first filter a caller reaches for. One value, 1 to 255 characters.
1 <= length <= 255One value.
1 <= length <= 64One value. Matches the per-provider leg: a descriptor live on Ethoca and still waiting on RDR answers to both.
Value in
Matches a provider leg's status: in_progress, enrolled, active, in_process_of_disenrollment, disenrolled or dropped. Repeat it for several: ?status=in_progress&status=enrolled.
application/json
application/json
curl -X GET "https://example.com/v3/alert_enrollments?chargeflow_id=68ce8d25b5438c0a1b2c3d4e"{ "object": "list", "data": [ { "id": "aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a", "object": "alert_enrollment", "created_at": "2026-08-12T09:30:00Z", "updated_at": "2026-08-12T09:30:00Z", "livemode": false, "psp": "stripe", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "descriptor": "PAYRA*MO", "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": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ] } ], "has_more": false, "next_cursor": null}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
application/json
The billing descriptor to enroll, up to 255 characters and not blank. One enrollment per psp and descriptor pair.
\Slength <= 255Which of your merchants to enroll. The merchant must be onboarded with Alerts, or this is 404 alert_account_not_found. A merchant outside your portfolio is 403 merchant_not_in_portfolio.
Which alert programs to enroll in. Defaults to ["ethoca"]. All programs are checked when you send the request: if any is unavailable or lacks its identifiers, the request is 422 and nothing is created. Once accepted, each program enrolls on its own, so one failing later does not affect the others.
| Program | Needs |
|---|---|
ethoca, cdrn | psp and descriptor |
rdr, tc40 | psp and descriptor, plus card_acceptor_id, bin and at least one of arns |
RDR refunds automatically. It resolves a matching dispute inside the card network by refunding the cardholder before it becomes a chargeback. Neither you nor Chargeflow can decline that refund per alert, so leave rdr out if the merchant does not accept automatic refunds.
["ethoca"]The card acceptor id (CAID). Required for RDR and TC40, with bin and arns.
^[A-Za-z0-9]{1,32}$The acquiring BIN. Required for RDR and TC40, with card_acceptor_id and arns.
^\d{6,8}$One to three acquirer reference numbers, each 23 digits with 4 as the second digit. At least one is required for RDR and TC40, with card_acceptor_id and bin.
The alerts vendor the merchant uses today, if any. Lets us catch a descriptor that would be enrolled twice.
length <= 100application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v3/alert_enrollments" \ -H "Content-Type: application/json" \ -d '{ "psp": "stripe", "descriptor": "PAYRA*MO", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "providers": [ "ethoca" ], "card_acceptor_id": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ], "current_alerts_provider": null }'{ "id": "aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a", "object": "alert_enrollment", "created_at": "2026-08-12T09:30:00Z", "updated_at": "2026-08-12T09:30:00Z", "livemode": false, "psp": "stripe", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "descriptor": "PAYRA*MO", "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": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ]}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
application/json
Which of your merchants every item belongs to.
The enrollments to create, 1 to 25. Each item takes the same fields as Create an alert enrollment except chargeflow_id. Resending an item that was already created returns 422 enrollment_exists for that item and processes the rest.
application/json
application/json
application/json
curl -X POST "https://example.com/v3/alert_enrollments/bulk" \ -H "Content-Type: application/json" \ -d '{ "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "enrollments": [ { "psp": "stripe", "descriptor": "PAYRA*MO", "providers": [ "ethoca" ], "card_acceptor_id": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ], "current_alerts_provider": null } ] }'{ "results": [ { "index": 0, "status": 202, "alert_enrollment": { "id": "aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a", "object": "alert_enrollment", "created_at": "2026-08-12T09:30:00Z", "updated_at": "2026-08-12T09:30:00Z", "livemode": false, "psp": "stripe", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "descriptor": "PAYRA*MO", "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": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ] } } ]}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
The alert enrollment this call acts on. An id that is malformed or names no enrollment is 404 alert_enrollment_not_found.
application/json
application/json
application/json
curl -X GET "https://example.com/v3/alert_enrollments/aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a"{ "id": "aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a", "object": "alert_enrollment", "created_at": "2026-08-12T09:30:00Z", "updated_at": "2026-08-12T09:30:00Z", "livemode": false, "psp": "stripe", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "descriptor": "PAYRA*MO", "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": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ]}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
The alert enrollment this call acts on. An id that is malformed or names no enrollment is 404 alert_enrollment_not_found.
application/json
Disenroll only these programs and leave the others enrolled. Omit it to disenroll every program on the enrollment. At least one, each named once; a program the enrollment does not have is 422 provider_not_enrolled and nothing is stopped.
Free text recorded with the disenrollment. Optional.
length <= 1024application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v3/alert_enrollments/aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a/disenrollments" \ -H "Content-Type: application/json" \ -d '{ "providers": [ "ethoca" ], "reason": "fraudulent" }'{ "id": "aen_68ce8d25b5438c0a1b2c3d4e-2b6f28f2-3ac7-46f4-85aa-501203dba38a", "object": "alert_enrollment", "created_at": "2026-08-12T09:30:00Z", "updated_at": "2026-08-12T09:30:00Z", "livemode": false, "psp": "stripe", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "descriptor": "PAYRA*MO", "providers": [ { "provider": "ethoca", "status": "in_process_of_disenrollment", "status_reason": null, "retryable": null, "enrolled_at": null, "alerts_stopped_at": null, "updated_at": "2026-08-12T09:30:00Z" } ], "card_acceptor_id": "000445566778899", "bin": "411111", "arns": [ "74537604221431003881223" ]}bearerAuth Your secret key, sent as Authorization: Bearer cf_live_<key_id>_<secret>.
In: header
The merchant this call acts on.
^[0-9a-f]{24}$application/json
application/json
application/json
curl -X GET "https://example.com/v3/merchants/66f1a2b3c4d5e6f708192a3b/alert_account"{ "object": "alert_account", "chargeflow_id": "68ce8d25b5438c0a1b2c3d4e", "created_at": "2026-08-12T09:30:00Z", "settings": { "alerts_only": false, "manual_billing": false, "transaction_linking_disabled": false, "payment_method_authorized": false }, "payment_method_authorized_at": null, "last_disenrollment_requested_at": null, "enrollment_count": 1, "provider_status_counts": { "active": 3, "in_progress": 1 }, "livemode": false}