Autenticación
Esta página es la referencia técnica de todos los mecanismos de autenticación de Rapid.
Tu aplicación llamando a Rapid
Sección titulada «Tu aplicación llamando a Rapid»Usa Basic Auth con client_id como usuario y client_secret como contraseña.
Authorization: Basic base64(client_id:client_secret)Endpoints que usan este método:
- API de Transacciones: crear, consultar y actualizar transacciones
- Merchants: listar, consultar, crear o actualizar (uno a uno o por lotes), editar y eliminar los merchants de la empresa
- Enrollments: solicitar (uno a uno o por lotes), listar, consultar y solicitar la desactivación
- Uso por merchant: alertas facturables por merchant en el ciclo
- Consulta de alertas y callback de estado
- API de Evidencias y captura del lado del servidor (producto Disputa)
Credenciales
Sección titulada «Credenciales»| Credencial | Descripción |
|---|---|
client_id | ID de tu empresa (generado en el panel) |
client_secret | Clave secreta (generada en el panel, trátala como una contraseña) |
Ejemplo de header
Sección titulada «Ejemplo de header»Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=Donde el valor base64 se decodifica como client_id:client_secret.
Seguridad
Sección titulada «Seguridad»- Usa siempre HTTPS
- No incluyas el
client_secreten código frontend, repositorios públicos ni logs - Si sospechas que se expuso, genera un
client_secretnuevo y revoca el anterior en el momento (ver abajo)
Cambio del client_secret
Sección titulada «Cambio del client_secret»Genera un secreto nuevo en Configuración › API. El client_id no cambia. El secreto anterior sigue valiendo 24 horas desde el cambio, y el panel muestra hasta cuándo. En ese plazo Rapid acepta los dos, así que puedes actualizar sistema por sistema sin interrupción:
- Genera el secreto nuevo en el panel y guárdalo en tu bóveda de secretos (aparece una sola vez).
- Actualiza cada sistema que llama a la API.
- Listo: el anterior deja de valer solo al final de las 24 horas. Si el cambio fue por una filtración, no esperes: haz clic en Revocar la clave anterior ahora y deja de valer al instante.
Generar otro secreto dentro de las 24 horas descarta el anterior: junto con el nuevo, solo sigue valiendo el que estaba vigente hasta ese segundo cambio.
Rapid llamando a tu aplicación (webhook)
Sección titulada «Rapid llamando a tu aplicación (webhook)»En el formato v2, Rapid firma cada webhook con HMAC-SHA256 y envía la firma y el timestamp en los headers:
X-Webhook-Signature: sha256=<hmac_hex>X-Webhook-Timestamp: 1790000000El contenido firmado no es solo el cuerpo: es ${X-Webhook-Timestamp}.${cuerpo_crudo}, el timestamp, un punto y el cuerpo exactamente como llegó. Calcular el HMAC solo sobre el cuerpo da un valor distinto y toda solicitud se rechaza. El timestamp entra en el cálculo para impedir que un POST capturado se reenvíe después (rechaza los que estén fuera de una ventana de 5 minutos).
La clave de firma (secret) la genera Rapid cuando registras el webhook y aparece una sola vez en el panel, en Configuración › Webhook. No la eliges tú y no hay forma de consultarla después: si la pierdes, genera otra en Configuración › API (la anterior deja de valer al instante).
El paso a paso de la validación, con ejemplos en Node.js, Python y PHP, está en Autenticación del webhook.
Formato legacy
Sección titulada «Formato legacy»Las cuentas migradas del sistema anterior reciben los webhooks en el formato legacy, que no está firmado. En él, la autenticación son los headers que el sistema antiguo ya enviaba:
clientid: <client_id>clientkey: <client_secret>Estos dos headers existen solo en legacy. En v2 no se envían: clientkey es tu credencial de acceso a la API, y enviarla en cada entrega la expondría en tu endpoint y en tus logs sin necesidad, ya que en v2 la autenticación la hace la firma. Para saber en qué formato está tu cuenta, ver Payload. Después de un cambio del client_secret, el clientkey de las entregas ya sale con el secreto nuevo.