Solicitar enrollment
Solicita un enrollment para un merchant de tu empresa (ver Enrollments: visión general). Todo producto solicitado nace pending y pasa por la aprobación del equipo de Rapid. Solicitar de nuevo el mismo enrollment devuelve el que ya existe, sin crear otro.
Para varios a la vez, incluso de merchants distintos, usa el Lote de enrollments.
Endpoint
Sección titulada «Endpoint»https://api.rapidchargeback.com/api/v1/enrollmentsAutenticación
Sección titulada «Autenticación»Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonCuerpo de la solicitud
Sección titulada «Cuerpo de la solicitud»| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
merchant_id | string (UUID) | Uno de los dos | El id del merchant |
merchant_ref | string (hasta 100) | Uno de los dos | El ID del vendedor en tu sistema (ver Crear o actualizar merchant) |
enrollment_type | enum | Sí | descriptor o bin_caid, sin distinguir mayúsculas |
descriptor_value | string (hasta 255) | En descriptor | El nombre en el resumen del titular |
descriptor_rule | enum | En descriptor | exact (igual) o startswith (empieza con, al menos 5 caracteres) |
bin | string | En bin_caid | Solo dígitos, de 6 a 10 |
caid | string (hasta 50) | En bin_caid | El identificador de la tienda en el adquirente |
arn | string (hasta 100) | No | Acquirer Reference Number de una transacción de la tienda, cuando lo tengas |
products | array | Sí | alert, prevention o los dos, sin repetir |
retry_rejected | boolean | No | true para solicitar de nuevo un identificador que el equipo rechazó (ver Rechazado antes). Por defecto false |
- Envía
merchant_idomerchant_ref, nunca los dos. - El texto se recorta. Un campo fuera de la tabla se rechaza con
422 VALIDATION_ERROR(Unknown field: <nombre>). preventionexige el merchant constore_name,merchant_urlycontact_phoney, según el caso, dirección completa y los datos de la tienda (descripción, logo, MCC, términos, política de reembolso y atención). Si falta algo,422 MERCHANT_INCOMPLETE_FOR_PREVENTIONlo indica enparams.fields.
Solicitud repetida y conflictos
Sección titulada «Solicitud repetida y conflictos»| Situación | Respuesta |
|---|---|
| El identificador ya está en uso en el mismo merchant, con el mismo tipo, la misma regla y todos los productos solicitados | 200, meta.result: "existing", con el enrollment que ya existe. No se guarda nada |
| En uso en tu empresa fuera de ese caso (otro merchant, otra regla, falta un producto) | 409 ENROLLMENT_DUPLICATE, con enrollment_id y merchant_id del enrollment en uso |
| En uso por otra empresa | 409 ENROLLMENT_DUPLICATE, solo con el identificador |
| Rechazado antes por el equipo | 409 ENROLLMENT_PREVIOUSLY_REJECTED (ver abajo) |
“En uso” es pending, active o deactivation_requested. La comparación del descriptor ignora mayúsculas, espacios repetidos y espacios alrededor del *.
Rechazado antes
Sección titulada «Rechazado antes»Si el equipo rechazó la última solicitud de ese identificador para el mismo merchant y tipo, y no hay nada en uso para él, solicitarlo de nuevo responde 409 ENROLLMENT_PREVIOUSLY_REJECTED, con el enrollment_id de la solicitud rechazada y el rejection_reason, cuando el equipo escribió el motivo. Así un reenvío automático no vuelve a poner en la cola una solicitud ya rechazada.
Corrige lo que motivó el rechazo y envíala con retry_rejected: true para solicitarla de nuevo. Un identificador desactivado a tu pedido (inactive) no bloquea: el vendedor que vuelve se puede solicitar normalmente.
Ejemplo de solicitud
Sección titulada «Ejemplo de solicitud»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"] }'Respuesta
Sección titulada «Respuesta»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 | Descripción |
|---|---|
id | ID del enrollment. Es el merchant_enrollment_id de las alertas que coincidan con él |
merchant_id, merchant_ref | El merchant del enrollment (merchant_ref es null si el merchant no tiene referencia) |
enrollment_type | descriptor o bin_caid |
descriptor_value, descriptor_rule | En descriptor. El valor sale guardado en minúsculas |
bin, caid | En bin_caid |
arn | El ARN informado, o null |
products.alert, products.prevention | null si el producto no se solicitó; si no, status, rejection_reason (motivo del rechazo) y approved_at (cuándo se aprobó) |
created_at, updated_at | Cuándo se solicitó y cuándo cambió por última vez |
Los estados están en Estado de cada producto.
Ya existía
Sección titulada «Ya existía»200 OK, con el enrollment existente y "meta": { "result": "existing" }.
Identificador en uso
Sección titulada «Identificador en 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\"" } }}Rechazado antes
Sección titulada «Rechazado 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 no encontrado en las transacciones de la tienda" } }}Errores
Sección titulada «Errores»| HTTP | Código | Cuándo |
|---|---|---|
| 404 | MERCHANT_NOT_FOUND | El merchant no existe en tu empresa |
| 409 | ENROLLMENT_DUPLICATE | Identificador en uso (params.identifier; enrollment_id y merchant_id cuando es de tu empresa) |
| 409 | ENROLLMENT_PREVIOUSLY_REJECTED | Rechazado antes; envía retry_rejected: true para solicitarlo de nuevo |
| 409 | MERCHANT_REF_CONFLICT | El merchant_ref solo difiere del guardado en mayúsculas o acentos (params.merchant_id, params.merchant_ref) |
| 422 | FIELD_REQUIRED | Falta un campo obligatorio (params.field) |
| 422 | FIELD_TOO_LONG | Campo por encima del límite (params.field, params.max) |
| 422 | FIELD_INVALID_OPTION | Valor fuera de la lista (params.field, params.options) |
| 422 | FIELD_INVALID | Valor inválido, como un producto repetido (params.field) |
| 422 | BIN_INVALID | bin fuera de 6 a 10 dígitos |
| 422 | VALIDATION_ERROR | Campo desconocido, merchant_id y merchant_ref juntos o ninguno de los dos (params.field) |
| 422 | DESCRIPTOR_LOOKS_LIKE_BIN_CAID | El descriptor parece un BIN/CAID: solicítalo como bin_caid |
| 422 | DESCRIPTOR_PREFIX_TOO_SHORT | startswith con menos de 5 caracteres (params.min) |
| 422 | ENROLLMENT_NO_PRODUCT | products vacío |
| 422 | PROVIDER_UNAVAILABLE | El producto no acepta ese tipo de enrollment (params.product, params.type) |
| 422 | MERCHANT_INCOMPLETE_FOR_PREVENTION | Faltan datos de registro del merchant para la Prevención (params.fields) |
| 422 | ENROLLMENT_PENDING_LIMIT | Tu empresa ya tiene 20.000 enrollments esperando aprobación (params.limit) |
| 403 | PRODUCT_NOT_ACTIVE | Tu empresa no tiene el producto activo (params.product) |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Empresa sin registro aprobado, inactiva o bloqueada |
| 429 | RATE_LIMIT_EXCEEDED | Más de 60 escrituras por minuto |
| 503 | SERVICE_UNAVAILABLE | No disponible temporalmente: repite después del Retry-After |
- Repetir es seguro. Después de un
503o de una caída de conexión, envía la misma solicitud: si ya se guardó, vuelveexisting. - Las solicitudes sueltas durante un lote de tu empresa esperan a que el lote termine y pueden recibir
503. Envía las sueltas después del lote. - La API no aprueba ni elige nada más allá de la solicitud: la aprobación es siempre del equipo de Rapid. La respuesta llega al responsable de tu cuenta en el panel y por correo, y la ves en la lista de enrollments.
- Actividad: cada solicitud aparece en la Actividad del panel como hecha por la integración.