> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quentli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entorno sandbox

> Valida tarjetas, pagos asíncronos y webhooks de Quentli en un entorno no productivo.

Usa el ambiente de staging para validar tu integración antes de cambiar a producción.

| Ambiente   | API base                          |
| ---------- | --------------------------------- |
| Staging    | `https://api.staging.quentli.com` |
| Producción | `https://api.quentli.com`         |

Solicita una organización y una API key de staging a [soporte@quentli.com](mailto:soporte@quentli.com). No reutilices credenciales, clientes ni métodos de pago de producción.

## Prepara un receptor de webhooks

Antes de probar pagos, registra un endpoint HTTPS que responda `2xx` rápidamente. Conserva `eventId` y procesa los eventos de forma idempotente.

Para una integración de adeudos, registra al menos:

* `PAYMENT_METHOD_CREATED`
* `INVOICE_PAID`
* `PAYMENT_COMPLETED`

```json POST /v1/webhooks theme={null}
{
  "input": {
    "url": "https://staging.miapp.com/webhooks/quentli",
    "description": "Receptor de pruebas",
    "enabledEvents": [
      "PAYMENT_METHOD_CREATED",
      "PAYMENT_ATTEMPT_SUCCEEDED",
      "PAYMENT_ATTEMPT_FAILED",
      "INVOICE_PAID",
      "PAYMENT_COMPLETED"
    ]
  }
}
```

## Prueba pagos con tarjeta

Completa el formulario de tarjeta del Portal de Clientes con los siguientes datos de prueba:

| Escenario                             | Número             | Titular      | Vencimiento | CVV   |
| ------------------------------------- | ------------------ | ------------ | ----------- | ----- |
| Pago exitoso                          | `4265880000000007` | `Juan Perez` | `12/33`     | `123` |
| Rechazo durante tokenización          | `4004430000000007` | `Juan Perez` | `12/33`     | `123` |
| Tokenización exitosa y pago rechazado | `4349003000047015` | `Juan Perez` | `12/33`     | `123` |
| Desafío 3DS en iframe                 | `5204740000002760` | `Juan Perez` | `12/33`     | `123` |

## Simula pagos de efectivo y transferencia

En staging, obtén el pago que quieres probar mediante la API REST. Primero solicita las instrucciones de efectivo o transferencia para una factura pendiente y conserva el `payment.id` de la respuesta:

```json POST /v1/invoices/{invoiceId}/payments theme={null}
{
  "input": {
    "paymentType": "TRANSFER"
  }
}
```

Usa `CASH` en lugar de `TRANSFER` para probar efectivo. Consulta [Sincroniza facturas en Quentli](/api/guias/sincroniza-facturas-en-quentli) para ver el formato de las instrucciones.

Después simula una liquidación exitosa con la siguiente solicitud. Usa la URL base de staging:

```json POST /v1/sandbox/payments/{paymentId}/complete theme={null}
{
  "input": {
    "outcome": "SUCCEEDED"
  }
}
```

Esta ruta solo acepta pagos pendientes de tipo `CASH` o `TRANSFER` y está bloqueada en producción. Verifica que tu endpoint reciba `INVOICE_PAID` y `PAYMENT_COMPLETED` cuando la factura quede liquidada.

## Prueba un pago recibido fuera de Quentli

Para probar cómo procesa tu sistema un pago que se recibió por otro proveedor, marca una factura como pagada:

```text theme={null}
POST /v1/invoices/{invoiceId}/mark-paid
```

Este flujo genera un pago de tipo `OTHER` (pagado por medios externos) y permite validar `INVOICE_PAID_OTHER` y `PAYMENT_COMPLETED`.

## Checklist antes de producción

1. Crea clientes de prueba con identificadores externos únicos.
2. Valida un pago exitoso, un rechazo y, cuando aplique, 3DS.
3. Valida efectivo, transferencia y pagos externos si los usarás.
4. Confirma que tu receptor tolera reintentos, eventos duplicados y entregas fuera de orden.
5. Reemplaza la URL base y API key de staging por las de producción.