Primera integración

El camino más corto hasta la integración funcionando. Al final de esta guía tu aplicación recibe alertas con la firma validada, envía transacciones y responde alertas por la API. Cada paso apunta a la página con el detalle completo.

¿Usas un asistente de IA? Conecta el MCP de la documentación antes de empezar: el asistente pasa a consultar estas páginas en lugar de deducir campos y códigos.

1. Obtén las credenciales

En el panel de Rapid, en Configuración › API, genera el client_id y el client_secret. El secreto aparece una sola vez: cópialo en el momento. Si lo pierdes, genéralo de nuevo en el mismo lugar (las credenciales anteriores dejan de valer en ese mismo instante).

Guarda las dos en variables de entorno, nunca en el código:

export RAPID_CLIENT_ID="tu_client_id"
export RAPID_CLIENT_SECRET="tu_client_secret"

Detalles en Autenticación.

2. Confirma que la credencial funciona

Lista la alerta más reciente de tu empresa:

curl -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts?per_page=1"

Respuesta	Qué significa
`200` con `data` y `meta`	Credencial correcta. `data` puede venir vacío si todavía no llegó ninguna alerta
`401 UNAUTHORIZED`	`client_id` o `client_secret` incorrecto
`403 COMPANY_BLOCKED`	La empresa está bloqueada en Rapid: habla con soporte

3. Registra el webhook

En Configuración › Webhook, registra la URL que va a recibir los eventos. Tiene que ser HTTPS y una dirección pública de internet: el panel rechaza http://, localhost e IPs de red local.

Al guardar, Rapid genera la clave de firma y la muestra una sola vez. Guárdala en RAPID_WEBHOOK_SECRET.

Para recibir en tu máquina durante el desarrollo, expón el servidor local con un túnel HTTPS (ver Buenas prácticas).

4. Valida la firma

Toda entrega trae X-Webhook-Signature y X-Webhook-Timestamp. Tu endpoint verifica la firma antes de procesar cualquier cosa.

Copia el endpoint listo de tu lenguaje (Node.js, Python o PHP) en Autenticación del webhook. Los tres siguen las mismas reglas:

la firma se calcula sobre el cuerpo crudo: no lo leas como JSON antes de validar
una entrega con más de 5 minutos se rechaza (protección contra reenvío)
toda entrega que no pase recibe 401

Responde 2xx rápido y procesa después, en una cola: Rapid espera hasta 30 segundos y, sin respuesta, lo intenta de nuevo. Usa el alert_id para no procesar la misma alerta dos veces. Ver Buenas prácticas.

5. Envía la primera transacción

Si usas Prevención o Disputa, trabajan con las transacciones de venta que envías. Cada transacción indica de qué merchant (tienda, marca o vendedor) es, por el merchant_id. Mira los tuyos:

curl -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  "https://api.rapidchargeback.com/api/v1/merchants"

El id de cada ítem de la respuesta es el merchant_id (ver Listar merchants). Con él, la transacción mínima:

curl -X POST https://api.rapidchargeback.com/api/v1/transactions \
  -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "external_id": "TXN-2026-001",
    "transaction_id": "cob_8f2a91c4",
    "transaction_date": "2026-04-01T15:30:00Z",
    "amount": 150.00,
    "currency": "USD",
    "card_bin": "424242",
    "card_last4": "4242",
    "items": [
      { "product_description": "Assinatura Premium - Mensal", "unit_price": 150.00 }
    ]
  }'

El transaction_id es el identificador del cobro en tu gateway de pago. Es por él que un contracargo futuro encuentra la transacción: sin él la defensa sale sin historial.
La respuesta es 201 con el id de la transacción en Rapid: guárdalo. Si lo pierdes, puedes encontrar la transacción por el external_id.
Si viene la clave warnings, la transacción se creó, pero faltan campos que mejoran la protección.

Todos los campos en Crear transacción. Para volumen, usa el envío por lotes.

6. Responde la primera alerta

Cuando llega una alerta de Mastercard, tienes 24 horas para responder. Con el alert_id recibido en el webhook:

curl -X PATCH https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/00000000-0000-0000-0000-000000000099/status \
  -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "account_suspended" }'

Estado	Cuándo usarlo
`notfound`	La transacción no existe en tu sistema
`account_suspended`	La transacción existe y ya está resuelta (reembolso hecho, acceso cortado)
`other`	La transacción existe, pero todavía no está resuelta

Una alerta de Visa llega con el reembolso ya hecho y no tiene plazo. Ver Reglas y plazos.

Antes de ir a producción

Credenciales y clave de firma en variables de entorno o en un gestor de secretos
El webhook valida la firma y la ventana de 5 minutos, y rechaza con 401
El webhook responde 2xx en menos de 30 segundos y procesa en cola
El mismo alert_id procesado dos veces no genera efecto duplicado
Alerta de Mastercard respondida en hasta 24 horas, de forma automática o por alguien de guardia
Transacciones con transaction_id completo, si usas Disputa
429 manejado esperando el Retry-After (ver Códigos de respuesta)

Próximos pasos

Payload del webhook: todos los campos de cada evento.
Problemas comunes: qué hacer cuando algo no funciona.
Herramientas para devs: la documentación en tu asistente de IA y la colección de Postman.