Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Requests an enrollment for one of your company’s merchants (see Enrollments: overview). Every requested product starts as pending and goes through approval by the Rapid team. Requesting the same enrollment again returns the one that already exists, without creating another.

For several at once, including from different merchants, use the Enrollment batch.

POST https://api.rapidchargeback.com/api/v1/enrollments
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

FieldTypeRequiredRule
merchant_idstring (UUID)One of the twoThe merchant id
merchant_refstring (up to 100)One of the twoThe seller ID in your system (see Create or update merchant)
enrollment_typeenumYesdescriptor or bin_caid, case-insensitive
descriptor_valuestring (up to 255)For descriptorThe name on the cardholder’s statement
descriptor_ruleenumFor descriptorexact (equal) or startswith (starts with, at least 5 characters)
binstringFor bin_caidDigits only, from 6 to 10
caidstring (up to 50)For bin_caidThe store’s identifier at the acquirer
arnstring (up to 100)NoAcquirer Reference Number of a store transaction, when you have one
productsarrayYesalert, prevention or both, without repeating
retry_rejectedbooleanNotrue to request again an identifier the team rejected (see Rejected before). Default false
  • Send merchant_id or merchant_ref, never both.
  • Text is trimmed. A field outside the table is rejected with 422 VALIDATION_ERROR (Unknown field: <name>).
  • prevention requires the merchant to have store_name, merchant_url and contact_phone and, depending on the case, a full address and the store details (description, logo, MCC, terms, refund policy and customer service). If something is missing, 422 MERCHANT_INCOMPLETE_FOR_PREVENTION lists it in params.fields.

SituationResponse
The identifier is already in use on the same merchant, with the same type, the same rule and all requested products200, meta.result: "existing", with the enrollment that already exists. Nothing is saved
In use in your company outside that case (another merchant, another rule, a product missing)409 ENROLLMENT_DUPLICATE, with enrollment_id and merchant_id of the enrollment in use
In use by another company409 ENROLLMENT_DUPLICATE, with the identifier only
Rejected before by the team409 ENROLLMENT_PREVIOUSLY_REJECTED (see below)

“In use” means pending, active or deactivation_requested. The descriptor comparison ignores case, repeated spaces and spaces around *.

If the team rejected the last request for this identifier for the same merchant and type, and nothing is in use for it, requesting it again responds 409 ENROLLMENT_PREVIOUSLY_REJECTED, with the enrollment_id of the rejected request and the rejection_reason, when the team wrote one. This way an automatic resend does not put an already rejected request back in the queue.

Fix what caused the rejection and send it with retry_rejected: true to request it again. An identifier deactivated at your request (inactive) does not block: a returning seller can be requested normally.


Terminal window
curl -X POST https://api.rapidchargeback.com/api/v1/enrollments \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/json" \
-d '{
"merchant_ref": "PB-1001",
"enrollment_type": "descriptor",
"descriptor_value": "LOJA EXEMPLO",
"descriptor_rule": "exact",
"products": ["alert"]
}'

HTTP/1.1 201 Created
{
"data": {
"id": "00000000-0000-0000-0000-0000000000aa",
"merchant_id": "00000000-0000-0000-0000-000000000001",
"merchant_ref": "PB-1001",
"enrollment_type": "descriptor",
"descriptor_value": "loja exemplo",
"descriptor_rule": "exact",
"bin": null,
"caid": null,
"arn": null,
"products": {
"alert": { "status": "pending", "rejection_reason": null, "approved_at": null },
"prevention": null
},
"created_at": "2026-11-06T12:00:00.000Z",
"updated_at": "2026-11-06T12:00:00.000Z"
},
"meta": { "result": "created" }
}
FieldDescription
idEnrollment ID. It is the merchant_enrollment_id of the alerts that match it
merchant_id, merchant_refThe enrollment’s merchant (merchant_ref is null if the merchant has no reference)
enrollment_typedescriptor or bin_caid
descriptor_value, descriptor_ruleFor descriptor. The value comes back saved in lowercase
bin, caidFor bin_caid
arnThe ARN provided, or null
products.alert, products.preventionnull if the product was not requested; otherwise status, rejection_reason (rejection reason) and approved_at (when it was approved)
created_at, updated_atWhen it was requested and when it last changed

The statuses are in Status of each product.

200 OK, with the existing enrollment and "meta": { "result": "existing" }.

HTTP/1.1 409 Conflict
{
"error": {
"code": "ENROLLMENT_DUPLICATE",
"message": "Descriptor \"LOJA EXEMPLO\" is already in use on the platform",
"params": { "identifier": "Descriptor \"LOJA EXEMPLO\"" }
}
}
HTTP/1.1 409 Conflict
{
"error": {
"code": "ENROLLMENT_PREVIOUSLY_REJECTED",
"message": "This identifier was rejected in a previous request. Send retry_rejected: true to request it again.",
"params": {
"enrollment_id": "00000000-0000-0000-0000-0000000000aa",
"rejection_reason": "Descriptor not found in the store's transactions"
}
}
}
HTTPCodeWhen
404MERCHANT_NOT_FOUNDThe merchant does not exist in your company
409ENROLLMENT_DUPLICATEIdentifier in use (params.identifier; enrollment_id and merchant_id when it is your company’s)
409ENROLLMENT_PREVIOUSLY_REJECTEDRejected before; send retry_rejected: true to request it again
409MERCHANT_REF_CONFLICTThe merchant_ref differs from the saved one only in case or accents (params.merchant_id, params.merchant_ref)
422FIELD_REQUIREDRequired field missing (params.field)
422FIELD_TOO_LONGField above the limit (params.field, params.max)
422FIELD_INVALID_OPTIONValue outside the list (params.field, params.options)
422FIELD_INVALIDInvalid value, such as a repeated product (params.field)
422BIN_INVALIDbin outside 6 to 10 digits
422VALIDATION_ERRORUnknown field, merchant_id and merchant_ref together or neither (params.field)
422DESCRIPTOR_LOOKS_LIKE_BIN_CAIDThe descriptor looks like a BIN/CAID: request it as bin_caid
422DESCRIPTOR_PREFIX_TOO_SHORTstartswith with fewer than 5 characters (params.min)
422ENROLLMENT_NO_PRODUCTEmpty products
422PROVIDER_UNAVAILABLEThe product does not accept this enrollment type (params.product, params.type)
422MERCHANT_INCOMPLETE_FOR_PREVENTIONThe merchant is missing registration data for Prevention (params.fields)
422ENROLLMENT_PENDING_LIMITYour company already has 20,000 enrollments waiting for approval (params.limit)
403PRODUCT_NOT_ACTIVEYour company does not have the product active (params.product)
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDCompany without an approved registration, inactive or blocked
429RATE_LIMIT_EXCEEDEDMore than 60 writes per minute
503SERVICE_UNAVAILABLETemporarily unavailable: repeat after Retry-After

  • Repeating is safe. After a 503 or a dropped connection, send the same request: if it was already saved, it comes back existing.
  • Single requests during a batch from your company wait for the batch to finish and may get a 503. Send single requests after the batch.
  • The API does not approve or choose anything beyond the request: approval is always by the Rapid team. The answer reaches the person in charge of your account in the dashboard and by email, and you see it in the enrollments list.
  • Activity: every request shows up in the dashboard Activity as made by the integration.