Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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.

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

CampoTipoObrigatórioRegra
merchant_idstring (UUID)Um dos doisO id do merchant
merchant_refstring (até 100)Um dos doisO ID do vendedor no seu sistema (ver Criar ou atualizar merchant)
enrollment_typeenumSimdescriptor ou bin_caid, sem diferenciar maiúsculas
descriptor_valuestring (até 255)Em descriptorO nome na fatura do portador
descriptor_ruleenumEm descriptorexact (igual) ou startswith (começa com, pelo menos 5 caracteres)
binstringEm bin_caidSó dígitos, de 6 a 10
caidstring (até 50)Em bin_caidO identificador da loja no adquirente
arnstring (até 100)NãoAcquirer Reference Number de uma transação da loja, quando você tiver
productsarraySimalert, prevention ou os dois, sem repetir
retry_rejectedbooleanNãotrue para pedir de novo um identificador que a equipe recusou (ver 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.

SituaçãoResposta
O identificador já está em uso no mesmo merchant, com o mesmo tipo, a mesma regra e todos os produtos pedidos200, 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 empresa409 ENROLLMENT_DUPLICATE, só com o identificador
Recusado antes pela equipe409 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 *.

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.


Janela do terminal
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" }
}
CampoDescrição
idID do enrollment. É o merchant_enrollment_id dos alertas que casarem com ele
merchant_id, merchant_refO merchant do enrollment (merchant_ref é null se o merchant não tem referência)
enrollment_typedescriptor ou bin_caid
descriptor_value, descriptor_ruleEm descriptor. O valor sai gravado em minúsculas
bin, caidEm bin_caid
arnO ARN informado, ou null
products.alert, products.preventionnull se o produto não foi pedido; senão status, rejection_reason (motivo da recusa) e approved_at (quando foi aprovado)
created_at, updated_atQuando foi pedido e quando mudou pela última vez

Os status estão em Status de cada produto.

200 OK, com o enrollment existente e "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 não encontrado nas transações da loja"
}
}
}
HTTPCódigoQuando
404MERCHANT_NOT_FOUNDO merchant não existe na sua empresa
409ENROLLMENT_DUPLICATEIdentificador em uso (params.identifier; enrollment_id e merchant_id quando é da sua empresa)
409ENROLLMENT_PREVIOUSLY_REJECTEDRecusado antes; mande retry_rejected: true para pedir de novo
409MERCHANT_REF_CONFLICTO merchant_ref só difere do gravado em maiúsculas ou acentos (params.merchant_id, params.merchant_ref)
422FIELD_REQUIREDCampo obrigatório faltando (params.field)
422FIELD_TOO_LONGCampo acima do limite (params.field, params.max)
422FIELD_INVALID_OPTIONValor fora da lista (params.field, params.options)
422FIELD_INVALIDValor inválido, como produto repetido (params.field)
422BIN_INVALIDbin fora de 6 a 10 dígitos
422VALIDATION_ERRORCampo desconhecido, merchant_id e merchant_ref juntos ou nenhum dos dois (params.field)
422DESCRIPTOR_LOOKS_LIKE_BIN_CAIDO descriptor parece um BIN/CAID: peça como bin_caid
422DESCRIPTOR_PREFIX_TOO_SHORTstartswith com menos de 5 caracteres (params.min)
422ENROLLMENT_NO_PRODUCTproducts vazio
422PROVIDER_UNAVAILABLEO produto não aceita esse tipo de enrollment (params.product, params.type)
422MERCHANT_INCOMPLETE_FOR_PREVENTIONFalta cadastro no merchant para a Prevenção (params.fields)
422ENROLLMENT_PENDING_LIMITA sua empresa já tem 20.000 enrollments esperando aprovação (params.limit)
403PRODUCT_NOT_ACTIVEA sua empresa não tem o produto ativo (params.product)
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDEmpresa sem cadastro aprovado, inativa ou bloqueada
429RATE_LIMIT_EXCEEDEDMais de 60 escritas por minuto
503SERVICE_UNAVAILABLEIndisponibilidade temporária: repita depois do Retry-After

  • 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.
  • Atividade: cada pedido aparece na Atividade do painel como feito pela integração.