Ir al contenido

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

Registra un evento de captura usando el token publicable. Es el endpoint que llama el snippet, y puedes llamarlo directamente si prefieres no cargar el script.

POST https://api.rapidchargeback.com/api/v1/capture/{token}/events

Ninguna. El token publicable en la URL identifica al merchant.

Content-Type: application/json

El snippet envía el mismo JSON como text/plain, que el navegador envía sin consulta previa de CORS. Se aceptan los dos tipos.

El token no es secreto y puede quedar en el HTML de tu tienda. Solo permite escribir, y el evento solo se convierte en evidencia si corresponde a un pedido real tuyo.

CampoTipoDescripción
tokenstringToken publicable del merchant, generado en el panel
CampoTipoDescripciónObligatorio
typestring (enum)checkout, terms_acceptance, access_log o usage_logSí
order_refstring o númeroIdentificador del pedido en tu sistema, hasta 100 caracteresSí
event_idstring o númeroIdentificador del evento, generado por ti, hasta 64 caracteresSí
payloadobjetoDatos del hecho, con campos de lista cerradaNo

La referencia completa de los valores aceptados está en Tipos y payload.

Dos puntos específicos de este canal:

  • event_id es obligatorio aquí. Genera un UUID por evento
  • captured_at enviado en el cuerpo se ignora. Rapid registra la hora de llegada. Para informar la hora del hecho, usa el canal servidor

Los tipos delivery_confirmation, scan y delivery_gps no existen en este canal: son hechos de tu operación, no del navegador del comprador.

120 solicitudes por minuto, por IP de origen y token. Es holgado para un checkout real y limita a quien esté usando el token fuera de tu sitio. Contar también por el token evita que compradores de tiendas distintas detrás de la misma IP (red móvil) compartan el mismo límite.

Además, cada merchant tiene un tope de eventos del navegador esperando a que aparezca la transacción. Por encima de él, el evento responde 429 TOO_MANY_PENDING_EVENTS hasta que la cola avance. El uso normal no se acerca: el tope existe para el caso de que alguien envíe pedidos inventados con tu token. El envío desde el servidor tiene un tope separado, así que ese abuso no bloquea los eventos que envía tu backend.

ReglaRespuesta
Token desconocido, inactivo o sin merchant404 NOT_FOUND
type ausente, o fuera de los cuatro aceptados en este canal422 VALIDATION_ERROR: invalid_type
order_ref ausente, vacío o de más de 100 caracteres422 VALIDATION_ERROR: invalid_order_ref
event_id ausente, vacío o de más de 64 caracteres422 VALIDATION_ERROR: invalid_event_id
device_id de más de 100 caracteres, device_fingerprint de más de 255 u otro campo de texto del payload de más de 512422 VALIDATION_ERROR: payload_too_large
Evento que viene de un sitio que no está entre los sitios en los que vale el token (ver)403 ORIGIN_NOT_ALLOWED
Más de 120 solicitudes por minuto429 Too Many Requests
Merchant con demasiados eventos esperando la transacción429 TOO_MANY_PENDING_EVENTS
Captura temporalmente no disponible503 CAPTURE_TEMPORARILY_UNAVAILABLE, con Retry-After

Ante un 503, reenvía el evento después de los segundos del header Retry-After. Con el mismo event_id, el reenvío nunca duplica la evidencia.

No existe error para un order_ref inexistente. El evento se acepta, queda en la cola y se descarta si ninguna transacción corresponde dentro de la ventana de correlación. Ver Ventana de correlación.

Ventana de terminal
curl -X POST https://api.rapidchargeback.com/api/v1/capture/tu_token_publicable/events \
-H "Content-Type: application/json" \
-d '{
"type": "terms_acceptance",
"order_ref": "TXN-2026-001",
"event_id": "019b0000-1111-7000-8000-000000000001",
"payload": { "url": "https://loja.exemplo.com/checkout" }
}'

Evento de checkout con identificación del dispositivo:

Ventana de terminal
curl -X POST https://api.rapidchargeback.com/api/v1/capture/tu_token_publicable/events \
-H "Content-Type: application/json" \
-d '{
"type": "checkout",
"order_ref": "TXN-2026-001",
"event_id": "019b0000-1111-7000-8000-000000000002",
"payload": {
"device_id": "8kJ2mQvR1nZxYb0T",
"device_fingerprint": "8kJ2mQvR1nZxYb0T",
"fp": "pro",
"fp_request_id": "1712059781234.Xk9Lp2"
}
}'
{ "accepted": true }

202 significa que el evento entró en la cola, no que ya se convirtió en evidencia. La correlación con la transacción ocurre después.

{ "error": { "code": "NOT_FOUND" } }

Error: tipo no disponible en este canal (422)

Sección titulada «Error: tipo no disponible en este canal (422)»
{
"error": {
"code": "VALIDATION_ERROR",
"message": "invalid_type"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "invalid_event_id"
}
}

Error: campo del payload demasiado largo (422)

Sección titulada «Error: campo del payload demasiado largo (422)»
{
"error": {
"code": "VALIDATION_ERROR",
"message": "payload_too_large"
}
}