Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

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.

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

CampoTipoObligatorioRegla
merchant_idstring (UUID)Uno de los dosEl id del merchant
merchant_refstring (hasta 100)Uno de los dosEl ID del vendedor en tu sistema (ver Crear o actualizar merchant)
enrollment_typeenumSídescriptor o bin_caid, sin distinguir mayúsculas
descriptor_valuestring (hasta 255)En descriptorEl nombre en el resumen del titular
descriptor_ruleenumEn descriptorexact (igual) o startswith (empieza con, al menos 5 caracteres)
binstringEn bin_caidSolo dígitos, de 6 a 10
caidstring (hasta 50)En bin_caidEl identificador de la tienda en el adquirente
arnstring (hasta 100)NoAcquirer Reference Number de una transacción de la tienda, cuando lo tengas
productsarraySíalert, prevention o los dos, sin repetir
retry_rejectedbooleanNotrue para solicitar de nuevo un identificador que el equipo rechazó (ver Rechazado antes). Por defecto false
  • Envía merchant_id o merchant_ref, nunca los dos.
  • El texto se recorta. Un campo fuera de la tabla se rechaza con 422 VALIDATION_ERROR (Unknown field: <nombre>).
  • prevention exige el merchant con store_name, merchant_url y contact_phone y, 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_PREVENTION lo indica en params.fields.

SituaciónRespuesta
El identificador ya está en uso en el mismo merchant, con el mismo tipo, la misma regla y todos los productos solicitados200, 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 empresa409 ENROLLMENT_DUPLICATE, solo con el identificador
Rechazado antes por el equipo409 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 *.

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.


Ventana de 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" }
}
CampoDescripción
idID del enrollment. Es el merchant_enrollment_id de las alertas que coincidan con él
merchant_id, merchant_refEl merchant del enrollment (merchant_ref es null si el merchant no tiene referencia)
enrollment_typedescriptor o bin_caid
descriptor_value, descriptor_ruleEn descriptor. El valor sale guardado en minúsculas
bin, caidEn bin_caid
arnEl ARN informado, o null
products.alert, products.preventionnull si el producto no se solicitó; si no, status, rejection_reason (motivo del rechazo) y approved_at (cuándo se aprobó)
created_at, updated_atCuándo se solicitó y cuándo cambió por última vez

Los estados están en Estado de cada producto.

200 OK, con el enrollment existente y "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 no encontrado en las transacciones de la tienda"
}
}
}
HTTPCódigoCuándo
404MERCHANT_NOT_FOUNDEl merchant no existe en tu empresa
409ENROLLMENT_DUPLICATEIdentificador en uso (params.identifier; enrollment_id y merchant_id cuando es de tu empresa)
409ENROLLMENT_PREVIOUSLY_REJECTEDRechazado antes; envía retry_rejected: true para solicitarlo de nuevo
409MERCHANT_REF_CONFLICTEl merchant_ref solo difiere del guardado en mayúsculas o acentos (params.merchant_id, params.merchant_ref)
422FIELD_REQUIREDFalta un campo obligatorio (params.field)
422FIELD_TOO_LONGCampo por encima del límite (params.field, params.max)
422FIELD_INVALID_OPTIONValor fuera de la lista (params.field, params.options)
422FIELD_INVALIDValor inválido, como un producto repetido (params.field)
422BIN_INVALIDbin fuera de 6 a 10 dígitos
422VALIDATION_ERRORCampo desconocido, merchant_id y merchant_ref juntos o ninguno de los dos (params.field)
422DESCRIPTOR_LOOKS_LIKE_BIN_CAIDEl descriptor parece un BIN/CAID: solicítalo como bin_caid
422DESCRIPTOR_PREFIX_TOO_SHORTstartswith con menos de 5 caracteres (params.min)
422ENROLLMENT_NO_PRODUCTproducts vacío
422PROVIDER_UNAVAILABLEEl producto no acepta ese tipo de enrollment (params.product, params.type)
422MERCHANT_INCOMPLETE_FOR_PREVENTIONFaltan datos de registro del merchant para la Prevención (params.fields)
422ENROLLMENT_PENDING_LIMITTu empresa ya tiene 20.000 enrollments esperando aprobación (params.limit)
403PRODUCT_NOT_ACTIVETu empresa no tiene el producto activo (params.product)
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDEmpresa sin registro aprobado, inactiva o bloqueada
429RATE_LIMIT_EXCEEDEDMás de 60 escrituras por minuto
503SERVICE_UNAVAILABLENo disponible temporalmente: repite después del Retry-After

  • Repetir es seguro. Después de un 503 o de una caída de conexión, envía la misma solicitud: si ya se guardó, vuelve existing.
  • 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.