> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.recurrente.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server. # Primer pago de prueba > Abre tu Sandbox, crea un checkout y verifica el webhook de tu primer pago 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](https://app.recurrente.com). 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 ```bash curl https://app.recurrente.com/api/test \ -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY" ``` La respuesta identifica el ambiente: ```json { "message": "Hello Mi negocio — Pruebas 🌎", "account_id": "ac_ejemplo", "environment": "sandbox", "sandbox_id": "sbx_ejemplo" } ``` `environment` debe ser `sandbox`. Si es `live`, estás usando una llave de producción. 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: ```bash 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 | Resultado | Tarjeta | | --------- | --------------------- | | Éxito | `4242 4242 4242 4242` | | Rechazo | `4000 0000 0000 0002` | 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: ```bash 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. ```bash 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](../assets/sandbox/webhook-server.mjs). En una carpeta local con ese archivo, instala la biblioteca oficial de Svix y ejecútalo: ```bash 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 `intent.succeeded` con el `sandbox_id` esperado. Su `id` es el identificador unificado `in_…`. 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: ```bash 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. Las cuentas anteriores al cambio conservan además el evento legacy `payment_intent.succeeded`: elige un solo contrato para no procesar dos veces el pago. Consulta [Webhooks](/guias-espanol/comenzar/webhooks) para firmas, formatos y buenas prácticas. ## Más escenarios | Necesitas probar | Qué hacer | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Rechazo | Crea otro checkout y usa la tarjeta de rechazo; espera `intent.failed`. | | Reembolso | Usa el ID real del payment intent exitoso en `POST /refunds`; verifica `refund.create`. | | Renovación y recuperación | Sigue la [guía de suscripciones y Test Clocks](/guias-espanol/guias/sandboxes-y-test-clocks). | | Firma, routing o duplicados de un evento específico | Usa `/test_helpers/webhook_events` o Testing en el panel. Es un fixture del webhook; no crea el pago, disputa o retiro correspondiente. | [Descarga la colección de primer pago para Postman](../assets/sandbox/first-payment.postman_collection.json). 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 | Síntoma | Siguiente paso | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No puedes abrir Sandbox | El administrador de tu cuenta debe abrirlo o invitarte directamente al ambiente. | | Llave enmascarada o incompleta | Copia la llave completa cuando la creas. Si la perdiste, crea una nueva; rota la anterior solo cuando quieras revocarla. | | La llave TEST "no existe" | Era la llave TEST de tu cuenta principal, que ya se retiró. Crea una en el Sandbox. Consulta [llaves TEST retiradas](/guias-espanol/guias/test-legacy). | | Un ID devuelve 404 | Confirma el ambiente y usa los IDs de esa misma cuenta. No reutilices IDs de producción. | | `sandbox_unsupported` | Esa operación está bloqueada; consulta las limitaciones de su endpoint. | | No llega el webhook | Confirma URL pública, misma llave/Sandbox, firma y entrega en el panel. Los endpoints registrados después del pago no reciben automáticamente ese pago anterior. | | No abre el panel de webhooks | Vuelve a intentarlo desde la guía rápida; tus datos y tu Sandbox se conservan. | ## 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.