# Request enrollment

> Requests the enrollment of a descriptor or BIN + CAID for a merchant. The request goes through approval by the Rapid team; repeating it returns the same enrollment.

Página: https://doc.rapidchargeback.com/en/canais/enrollments/pedir-enrollment/

Requests an enrollment for one of your company's merchants (see [Enrollments: overview](https://doc.rapidchargeback.com/en/canais/enrollments/visao-geral/)). 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](https://doc.rapidchargeback.com/en/canais/enrollments/lote-de-enrollments/).

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/enrollments
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## 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](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-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](#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`.

---

## 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

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

```bash
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

### Created

```
HTTP/1.1 201 Created
```

```json
{
  "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](https://doc.rapidchargeback.com/en/canais/enrollments/visao-geral/#status-of-each-product).

### Already existed

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

### Identifier in use

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "ENROLLMENT_DUPLICATE",
    "message": "Descriptor \"LOJA EXEMPLO\" is already in use on the platform",
    "params": { "identifier": "Descriptor \"LOJA EXEMPLO\"" }
  }
}
```

### Rejected before

```
HTTP/1.1 409 Conflict
```

```json
{
  "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

| 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` |

---

## Notes

- **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](https://doc.rapidchargeback.com/en/canais/enrollments/listar-enrollments/).
- **Activity:** every request shows up in the dashboard Activity as made by the integration.
