Skip to main content
POST
Enroll Descriptors for Dispute Alerts
A requested descriptor or bin/caid that is Disabled or Rejected is re-enrolled: it is reset to Pending and sent to the provider again. One that is Pending and has no provider id yet is sent again without a status change, so a retried request reaches the provider. Descriptors that are Pending with a provider id, Processing, InReview, Enrolled or Surpressed keep their status and are not sent, unless unenrolRequestedAt is 2 hours or older. Such a row is reset to Pending and sent again. A missing bin or caid on a row that keeps its status is filled in. If a requested descriptor or bin/caid has unenrolRequestedAt set less than 2 hours ago and is not Disabled or Rejected, the whole request is rejected with 409 and nothing is changed. Retry after its status changes to Disabled, or after 2 hours. providerId and providerConfigId are optional. When providerConfigId is omitted, the merchant’s single active dispute-alert provider config is used. When none or several match, the request is rejected with 422.

Authorizations

Authorization
string
header
required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.

Scopes

disputes:update

Headers

x-idempotency-key
string<uuid>
required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Body

application/json
workspaceId
string<uuid>
required

The workspace the enrollment belongs to.

program
enum<string>
required

The network program to enroll in. Ethoca, CDRN, and RDR are actionable pre-chargeback alert programmes. Ethoca and CDRN enroll by descriptors; RDR enrolls by bins/caids. VerifiINFORM is Visa's account-level fraud-reporting feed (covering TC40, TC15, and future Verifi INFORM feeds) — it requires externalReference instead of descriptors, and a merchant enrolls once to receive all Verifi INFORM alert types. SAFE (Mastercard fraud feed) is implicit on any Ethoca-enrolled merchant; enroll it explicitly only for a fraud-report-only merchant with a dedicated SAFE merchant reference — like VerifiINFORM, it requires externalReference instead of descriptors. TC40 enrolls Visa TC40 fraud reports only, by bins/caids, for a merchant that needs fraud reports without alerts. The provider assigns its merchant reference, so omit externalReference.

Available options:
Ethoca,
CDRN,
RDR,
VerifiINFORM,
SAFE,
TC40
providerId
string<uuid> | null

Optional. The dispute-alert provider. When providerConfigId is omitted, it narrows the lookup of the active provider config. When providerConfigId is sent without providerId and a new enrollment is created, the provider is read from that config. On a new enrollment a sent providerId is stored as given and is not checked against providerConfigId; on an existing enrollment it is not used. Omit it or send null; an empty string is rejected.

providerConfigId
string<uuid> | null

Optional. The dispute-alert provider config to enroll against. When omitted, the merchant's single active dispute-alert provider config is used; the request is rejected when there is none or more than one. Omit it or send null; an empty string is rejected.

descriptors
string[]

The merchant descriptors to enroll for alerts. Required for Ethoca and CDRN. RDR and TC40 enroll by bins/caids instead of descriptors. Must be empty or omitted for account-level programs (VerifiINFORM, SAFE).

bins
string[]

RDR and TC40 only. Card BINs to enroll, paired 1:1 with caids (bins[i] is confirmed against caids[i]). Required for RDR and TC40; omit for other programmes.

caids
string[]

RDR and TC40 only. Card Acceptor IDs, paired 1:1 with bins. Required for RDR and TC40.

ruleset
string

Optional provider ruleset to apply.

externalReference
string

The provider merchant ID for an account-level program. Required for VerifiINFORM (the Verifi INFORM merchant ID) and SAFE (the dedicated SAFE merchant reference); Chargeblast uses this ID as the merchantId on the program's alert webhooks (TC40, TC15, SAFE, …), so it must be stored for ingestion to resolve incoming alerts. Omit for actionable programs (Ethoca, CDRN, RDR) and TC40, where the connector assigns the reference at enrollment time.

Response

Enrollment created.