Pedir enrollment
Pede um enrollment para um merchant da sua empresa (ver Enrollments: visão 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.
Endpoint
Seção intitulada “Endpoint”https://api.rapidchargeback.com/api/v1/enrollmentsAutenticação
Seção intitulada “Autenticação”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonCorpo da requisição
Seção intitulada “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) |
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). Padrão false |
- Mande
merchant_idoumerchant_ref, nunca os dois. - Texto aparado. Campo fora da tabela é recusado com
422 VALIDATION_ERROR(Unknown field: <nome>). preventionexige o merchant comstore_name,merchant_urlecontact_phonee, 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_PREVENTIONdiz o quê emparams.fields.
Pedido repetido e conflitos
Seção intitulada “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ção intitulada “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
Seção intitulada “Exemplo de requisição”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
Seção intitulada “Resposta”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" }}| 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.
Já existia
Seção intitulada “Já existia”200 OK, com o enrollment existente e "meta": { "result": "existing" }.
Identificador em uso
Seção intitulada “Identificador em uso”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\"" } }}Recusado antes
Seção intitulada “Recusado antes”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 não encontrado nas transações da loja" } }}| 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 |
- Repetir é seguro. Depois de um
503ou de uma queda de conexão, mande o mesmo pedido: se ele já foi gravado, voltaexisting. - 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.
- Atividade: cada pedido aparece na Atividade do painel como feito pela integração.