Request enrollment
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.
Endpoint
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/enrollmentsAuthentication
Section titled “Authentication”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonRequest body
Section titled “Request body”| Field | Type | Required | Rule |
|---|---|---|---|
merchant_id | string (UUID) | One of the two | The merchant id |
merchant_ref | string (up to 100) | One of the two | The seller ID in your system (see Create or update merchant) |
enrollment_type | enum | Yes | descriptor or bin_caid, case-insensitive |
descriptor_value | string (up to 255) | For descriptor | The name on the cardholder’s statement |
descriptor_rule | enum | For descriptor | exact (equal) or startswith (starts with, at least 5 characters) |
bin | string | For bin_caid | Digits only, from 6 to 10 |
caid | string (up to 50) | For bin_caid | The store’s identifier at the acquirer |
arn | string (up to 100) | No | Acquirer Reference Number of a store transaction, when you have one |
products | array | Yes | alert, prevention or both, without repeating |
retry_rejected | boolean | No | true to request again an identifier the team rejected (see Rejected before). Default false |
- Send
merchant_idormerchant_ref, never both. - Text is trimmed. A field outside the table is rejected with
422 VALIDATION_ERROR(Unknown field: <name>). preventionrequires the merchant to havestore_name,merchant_urlandcontact_phoneand, 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_PREVENTIONlists it inparams.fields.
Repeated request and conflicts
Section titled “Repeated request and conflicts”| Situation | Response |
|---|---|
| The identifier is already in use on the same merchant, with the same type, the same rule and all requested products | 200, 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 company | 409 ENROLLMENT_DUPLICATE, with the identifier only |
| Rejected before by the team | 409 ENROLLMENT_PREVIOUSLY_REJECTED (see below) |
“In use” means pending, active or deactivation_requested. The descriptor comparison ignores case, repeated spaces and spaces around *.
Rejected before
Section titled “Rejected before”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.
Request example
Section titled “Request example”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"] }'Response
Section titled “Response”Created
Section titled “Created”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" }}| Field | Description |
|---|---|
id | Enrollment ID. It is the merchant_enrollment_id of the alerts that match it |
merchant_id, merchant_ref | The enrollment’s merchant (merchant_ref is null if the merchant has no reference) |
enrollment_type | descriptor or bin_caid |
descriptor_value, descriptor_rule | For descriptor. The value comes back saved in lowercase |
bin, caid | For bin_caid |
arn | The ARN provided, or null |
products.alert, products.prevention | null if the product was not requested; otherwise status, rejection_reason (rejection reason) and approved_at (when it was approved) |
created_at, updated_at | When it was requested and when it last changed |
The statuses are in Status of each product.
Already existed
Section titled “Already existed”200 OK, with the existing enrollment and "meta": { "result": "existing" }.
Identifier in use
Section titled “Identifier in use”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\"" } }}Rejected before
Section titled “Rejected before”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" } }}Errors
Section titled “Errors”| HTTP | Code | When |
|---|---|---|
| 404 | MERCHANT_NOT_FOUND | The merchant does not exist in your company |
| 409 | ENROLLMENT_DUPLICATE | Identifier in use (params.identifier; enrollment_id and merchant_id when it is your company’s) |
| 409 | ENROLLMENT_PREVIOUSLY_REJECTED | Rejected before; send retry_rejected: true to request it again |
| 409 | MERCHANT_REF_CONFLICT | The merchant_ref differs from the saved one only in case or accents (params.merchant_id, params.merchant_ref) |
| 422 | FIELD_REQUIRED | Required field missing (params.field) |
| 422 | FIELD_TOO_LONG | Field above the limit (params.field, params.max) |
| 422 | FIELD_INVALID_OPTION | Value outside the list (params.field, params.options) |
| 422 | FIELD_INVALID | Invalid value, such as a repeated product (params.field) |
| 422 | BIN_INVALID | bin outside 6 to 10 digits |
| 422 | VALIDATION_ERROR | Unknown field, merchant_id and merchant_ref together or neither (params.field) |
| 422 | DESCRIPTOR_LOOKS_LIKE_BIN_CAID | The descriptor looks like a BIN/CAID: request it as bin_caid |
| 422 | DESCRIPTOR_PREFIX_TOO_SHORT | startswith with fewer than 5 characters (params.min) |
| 422 | ENROLLMENT_NO_PRODUCT | Empty products |
| 422 | PROVIDER_UNAVAILABLE | The product does not accept this enrollment type (params.product, params.type) |
| 422 | MERCHANT_INCOMPLETE_FOR_PREVENTION | The merchant is missing registration data for Prevention (params.fields) |
| 422 | ENROLLMENT_PENDING_LIMIT | Your company already has 20,000 enrollments waiting for approval (params.limit) |
| 403 | PRODUCT_NOT_ACTIVE | Your company does not have the product active (params.product) |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Company without an approved registration, inactive or blocked |
| 429 | RATE_LIMIT_EXCEEDED | More than 60 writes per minute |
| 503 | SERVICE_UNAVAILABLE | Temporarily unavailable: repeat after Retry-After |
- Repeating is safe. After a
503or a dropped connection, send the same request: if it was already saved, it comes backexisting. - 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.