# Pedir enrollment

> Pede o enrollment de um descriptor ou BIN + CAID para um merchant. O pedido passa pela aprovação da equipe da Rapid; repetir devolve o mesmo enrollment.

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

Pede um enrollment para um merchant da sua empresa (ver [Enrollments: visão geral](https://doc.rapidchargeback.com/canais/enrollments/visao-geral/)). Todo produto pedido nasce `pending` e passa pela aprovação da equipe da Rapid. Pedir de novo o mesmo enrollment devolve o que já existe, sem criar outro.

Para vários de uma vez, inclusive de merchants diferentes, use o [Lote de enrollments](https://doc.rapidchargeback.com/canais/enrollments/lote-de-enrollments/).

## Endpoint

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

## Autenticação

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

---

## Corpo da requisição

| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
| `merchant_id` | string (UUID) | Um dos dois | O `id` do merchant |
| `merchant_ref` | string (até 100) | Um dos dois | O ID do vendedor no seu sistema (ver [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/)) |
| `enrollment_type` | enum | Sim | `descriptor` ou `bin_caid`, sem diferenciar maiúsculas |
| `descriptor_value` | string (até 255) | Em `descriptor` | O nome na fatura do portador |
| `descriptor_rule` | enum | Em `descriptor` | `exact` (igual) ou `startswith` (começa com, pelo menos 5 caracteres) |
| `bin` | string | Em `bin_caid` | Só dígitos, de 6 a 10 |
| `caid` | string (até 50) | Em `bin_caid` | O identificador da loja no adquirente |
| `arn` | string (até 100) | Não | Acquirer Reference Number de uma transação da loja, quando você tiver |
| `products` | array | Sim | `alert`, `prevention` ou os dois, sem repetir |
| `retry_rejected` | boolean | Não | `true` para pedir de novo um identificador que a equipe recusou (ver [Recusado antes](#recusado-antes)). Padrão `false` |

- Mande `merchant_id` **ou** `merchant_ref`, nunca os dois.
- Texto aparado. Campo fora da tabela é recusado com `422 VALIDATION_ERROR` (`Unknown field: <nome>`).
- `prevention` exige o merchant com `store_name`, `merchant_url` e `contact_phone` e, conforme o caso, endereço completo e os dados da loja (descrição, logo, MCC, termos, política de reembolso e atendimento). Faltando algo, `422 MERCHANT_INCOMPLETE_FOR_PREVENTION` diz o quê em `params.fields`.

---

## Pedido repetido e conflitos

| Situação | Resposta |
|---|---|
| O identificador já está em uso **no mesmo merchant**, com o mesmo tipo, a mesma regra e todos os produtos pedidos | `200`, `meta.result: "existing"`, com o enrollment que já existe. Nada é gravado |
| Em uso na sua empresa fora desse caso (outro merchant, outra regra, produto faltando) | `409 ENROLLMENT_DUPLICATE`, com `enrollment_id` e `merchant_id` do enrollment em uso |
| Em uso por outra empresa | `409 ENROLLMENT_DUPLICATE`, só com o identificador |
| Recusado antes pela equipe | `409 ENROLLMENT_PREVIOUSLY_REJECTED` (ver abaixo) |

"Em uso" é `pending`, `active` ou `deactivation_requested`. A comparação do descriptor ignora maiúsculas, espaços repetidos e espaços em volta do `*`.

### Recusado antes

Se a equipe recusou o último pedido desse identificador para o mesmo merchant e tipo, e nada está em uso para ele, pedir de novo responde `409 ENROLLMENT_PREVIOUSLY_REJECTED`, com o `enrollment_id` do pedido recusado e o `rejection_reason`, quando a equipe escreveu o motivo. Assim um reenvio automático não volta a pôr na fila um pedido já recusado.

Corrija o que motivou a recusa e mande com `retry_rejected: true` para pedir de novo. Identificador desativado a seu pedido (`inactive`) não trava: o vendedor que volta pode ser pedido normalmente.

---

## Exemplo de requisição

```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"]
  }'
```

---

## Resposta

### Criado

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

| Campo | Descrição |
|---|---|
| `id` | ID do enrollment. É o `merchant_enrollment_id` dos alertas que casarem com ele |
| `merchant_id`, `merchant_ref` | O merchant do enrollment (`merchant_ref` é `null` se o merchant não tem referência) |
| `enrollment_type` | `descriptor` ou `bin_caid` |
| `descriptor_value`, `descriptor_rule` | Em `descriptor`. O valor sai gravado em minúsculas |
| `bin`, `caid` | Em `bin_caid` |
| `arn` | O ARN informado, ou `null` |
| `products.alert`, `products.prevention` | `null` se o produto não foi pedido; senão `status`, `rejection_reason` (motivo da recusa) e `approved_at` (quando foi aprovado) |
| `created_at`, `updated_at` | Quando foi pedido e quando mudou pela última vez |

Os status estão em [Status de cada produto](https://doc.rapidchargeback.com/canais/enrollments/visao-geral/#status-de-cada-produto).

### Já existia

`200 OK`, com o enrollment existente e `"meta": { "result": "existing" }`.

### Identificador em uso

```
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\"" }
  }
}
```

### Recusado antes

```
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 não encontrado nas transações da loja"
    }
  }
}
```

### Erros

| HTTP | Código | Quando |
|---|---|---|
| 404 | `MERCHANT_NOT_FOUND` | O merchant não existe na sua empresa |
| 409 | `ENROLLMENT_DUPLICATE` | Identificador em uso (`params.identifier`; `enrollment_id` e `merchant_id` quando é da sua empresa) |
| 409 | `ENROLLMENT_PREVIOUSLY_REJECTED` | Recusado antes; mande `retry_rejected: true` para pedir de novo |
| 409 | `MERCHANT_REF_CONFLICT` | O `merchant_ref` só difere do gravado em maiúsculas ou acentos (`params.merchant_id`, `params.merchant_ref`) |
| 422 | `FIELD_REQUIRED` | Campo obrigatório faltando (`params.field`) |
| 422 | `FIELD_TOO_LONG` | Campo acima do limite (`params.field`, `params.max`) |
| 422 | `FIELD_INVALID_OPTION` | Valor fora da lista (`params.field`, `params.options`) |
| 422 | `FIELD_INVALID` | Valor inválido, como produto repetido (`params.field`) |
| 422 | `BIN_INVALID` | `bin` fora de 6 a 10 dígitos |
| 422 | `VALIDATION_ERROR` | Campo desconhecido, `merchant_id` e `merchant_ref` juntos ou nenhum dos dois (`params.field`) |
| 422 | `DESCRIPTOR_LOOKS_LIKE_BIN_CAID` | O descriptor parece um BIN/CAID: peça como `bin_caid` |
| 422 | `DESCRIPTOR_PREFIX_TOO_SHORT` | `startswith` com menos de 5 caracteres (`params.min`) |
| 422 | `ENROLLMENT_NO_PRODUCT` | `products` vazio |
| 422 | `PROVIDER_UNAVAILABLE` | O produto não aceita esse tipo de enrollment (`params.product`, `params.type`) |
| 422 | `MERCHANT_INCOMPLETE_FOR_PREVENTION` | Falta cadastro no merchant para a Prevenção (`params.fields`) |
| 422 | `ENROLLMENT_PENDING_LIMIT` | A sua empresa já tem 20.000 enrollments esperando aprovação (`params.limit`) |
| 403 | `PRODUCT_NOT_ACTIVE` | A sua empresa não tem o produto ativo (`params.product`) |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Empresa sem cadastro aprovado, inativa ou bloqueada |
| 429 | `RATE_LIMIT_EXCEEDED` | Mais de 60 escritas por minuto |
| 503 | `SERVICE_UNAVAILABLE` | Indisponibilidade temporária: repita depois do `Retry-After` |

---

## Notas

- **Repetir é seguro.** Depois de um `503` ou de uma queda de conexão, mande o mesmo pedido: se ele já foi gravado, volta `existing`.
- **Pedidos avulsos durante um lote** da sua empresa esperam o lote terminar e podem receber `503`. Mande os avulsos depois do lote.
- **A API não aprova** nem escolhe nada além do pedido: a aprovação é sempre da equipe da Rapid. A resposta da aprovação chega ao responsável pela sua conta no painel e por e-mail, e você a vê pela [lista de enrollments](https://doc.rapidchargeback.com/canais/enrollments/listar-enrollments/).
- **Atividade:** cada pedido aparece na Atividade do painel como feito pela integração.
