Primer pago de prueba

Prueba tu integración con datos aislados y sin mover dinero real. Usa una llave de un Sandbox para que tus clientes, pagos y webhooks de prueba estén separados de producción.

Abre tu Sandbox

1. Inicia sesión o crea una cuenta.
2. En Configuración → Llaves API, elige Abrir Sandbox. También está en la navegación de tu cuenta.
3. Si todavía estás creando tu cuenta, elige Solo quiero integrar la API. Puedes probar antes de completar la activación de producción.
4. En Pruebas (Sandbox), elige Crear mi llave TEST, ponle un nombre y guarda la llave completa. Solo se muestra una vez.

Necesitas permisos de administrador en esa cuenta o una invitación al Sandbox. El dueño puede elegir Equipo → Añadir desde la guía rápida; recibirás un correo para entrar sin acceso a la cuenta de producción. Abre el enlace y confirma con Abrir mi Sandbox en la página de ingreso.

En Administrar ambientes puedes renombrar, crear o archivar Sandboxes antes de activar producción. Puedes tener hasta cinco activos; archiva uno si necesitas espacio.

Guarda tu llave en el entorno de tu servidor como RECURRENTE_SECRET_KEY. No la incluyas en el navegador ni en tu repositorio. Crear otra llave no invalida las existentes; Rotar invalida inmediatamente la llave anterior.

Confirma el ambiente

curl https://app.recurrente.com/api/test \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY"

La respuesta identifica el ambiente:

{
  "message": "Hello Mi negocio — Pruebas 🌎",
  "account_id": "ac_ejemplo",
  "environment": "sandbox",
  "sandbox_id": "sbx_ejemplo"
}

environment debe ser sandbox. Si es legacy_test, estás usando una llave TEST de tu cuenta principal: crea una llave dentro del Sandbox. Si es live, estás usando una llave de producción. El prefijo sk_test_ por sí solo no distingue los dos modelos de prueba. Conserva el sandbox_id para verificar tus webhooks.

La URL base es siempre https://app.recurrente.com/api. La llave elige el ambiente. Cambiar de pantalla en el dashboard no cambia el ambiente de tu código. No necesitas llave pública.

Crea un checkout

No necesitas crear un producto antes de esta prueba:

curl https://app.recurrente.com/api/checkouts \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "name": "Mi primer pago de prueba",
      "amount_in_cents": 500,
      "currency": "GTQ",
      "quantity": 1
    }]
  }'

Guarda el id y abre el checkout_url que devuelve la API. El monto está en centavos: 500 representa Q5. El mínimo es Q5 para GTQ y $1 para USD.

Completa y verifica el pago

Usa una fecha de expiración futura, un CVC de tres dígitos y datos ficticios. No uses tarjetas reales. Consulta el checkout con el ID devuelto, sin inventar otro:

curl "https://app.recurrente.com/api/checkouts/$CHECKOUT_ID" \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY"

Después del éxito, status es paid. También verás el pago en Actividad dentro del mismo Sandbox. El regreso del navegador a success_url no sustituye verificar el pago en tu servidor. Antes de cada nuevo caso, crea un nuevo checkout.

Recibe el webhook

Tu endpoint necesita una URL pública. Para trabajar localmente, expón el puerto 4242 con un túnel HTTPS y usa esa URL pública; no registres localhost ni una IP privada.

curl https://app.recurrente.com/api/webhook_endpoints \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-dominio.com/webhooks/recurrente",
    "description": "Mi integración Sandbox"
  }'

Guarda el signingSecret como RECURRENTE_WEBHOOK_SECRET y el sandbox_id del paso anterior como RECURRENTE_SANDBOX_ID. El signing secret es distinto de la llave API y se devuelve al crear el endpoint. Si lo pierdes, consulta el secreto del endpoint en el panel de webhooks.

Descarga el servidor de ejemplo. En una carpeta local con ese archivo, instala la biblioteca oficial de Svix y ejecútalo:

npm install svix@2.5.0
node webhook-server.mjs

El servidor escucha en 127.0.0.1:4242/webhooks/recurrente. Verifica la firma sobre el cuerpo original, valida el Sandbox, muestra IDs y nombres de eventos, y responde 200. Paga otro checkout después de registrar el endpoint. Debes recibir payment_intent.succeeded con live_mode: false y el sandbox_id esperado.

Desde Pruebas (Sandbox) → Ver entregas y reintentar, inspecciona el payload, el código HTTP de tu servidor y los reintentos. Un evento creado o enviado a Svix no demuestra que tu servidor lo recibió: verifica una entrega exitosa.

Para ensayar un fallo, reinicia el ejemplo con:

FAIL_FIRST_DELIVERY=true node webhook-server.mjs

La primera entrega válida responde 503. Usa Replay en el panel de webhooks. El siguiente intento responde 200; repetirlo no vuelve a procesar el mismo svix-id. El ejemplo guarda los IDs en memoria para una sesión local: en producción usa un registro persistente y una cola, con unicidad por evento, antes de confirmar la recepción. No proceses dos veces un pago al recibir también un evento unificado intent.succeeded: elige un contrato de eventos para tu flujo.

Consulta Webhooks para firmas, formatos y buenas prácticas.

Más escenarios

Descarga la colección de primer pago para Postman. Define sandboxKey como variable local; los IDs y URLs de respuesta se guardan automáticamente. El pago se completa en el checkout alojado.

Sandbox admite los cobros de tarjeta simulados descritos aquí, suscripciones y reembolsos. No reproduce 3DS, autorizaciones bancarias, liquidación real ni hardware POS. Las transferencias, splits, swaps y retiros están bloqueados. Los catálogos y otros endpoints tienen su contrato documentado en la referencia API; que un endpoint esté disponible no implica que todos sus métodos de pago estén simulados.

Si algo no funciona

Pasa a producción

1. Completa la activación de la cuenta comercial.
2. Usa la llave LIVE en el entorno de producción de tu servidor.
3. Crea los productos/precios necesarios en producción y usa sus nuevos IDs.
4. Registra el endpoint LIVE y configura su propio signing secret.
5. Genera checkouts nuevos con la llave LIVE.

No se trasladan clientes, pagos ni balances simulados. Volver a producción en el dashboard solo cambia la pantalla. Las llaves TEST legacy existentes conservan su routing; abrir un Sandbox no migra tu integración anterior.