Sandbox

El sandbox de Liqfy te permite probar una integración completa (crear un cobro, leer el QR, consultar el estado, probar la idempotencia) sin mover dinero y sin esperar las credenciales del adquirente.

No hay un host aparte. Se usan la misma URL y el mismo contrato que en producción; solo cambia la clave.

#Cómo entrar al sandbox

Genera una clave de prueba en el panel (o mediante el endpoint de claves de API) y úsala como siempre:

Clave	Qué ocurre
`lq_test_...`	El cobro va al simulador. No se le cobra a nadie.
`lq_live_...`	El cobro va al adquirente real.

No existe ningún campo en el cuerpo de la solicitud para elegir el entorno: lo decide la clave, y solo la clave. Enviar manualmente un encabezado de entorno no cambia nada. La pasarela lo descarta y trata la solicitud como un cobro real.

bash

curl -X POST https://api.liqfy.com.br/v1/charges \
  -H "Authorization: Bearer lq_test_YOUR_KEY" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15000, "currency": "BRL", "payment_method": "pix"}'

Respuesta (abreviada):

json

{
  "id": "ch_a4521699-89a6-44a1-adb6-745862875e95",
  "object": "charge",
  "amount": 15000,
  "status": "pending",
  "payment_method": "pix",
  "pix": {
    "br_code": "00020126SANDBOX-PIX-8494424468F862C5DE279BA25204000053039865802BR",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2026-07-30T18:14:12.338Z"
  }
}

#Qué esperar de los artefactos

Todo artefacto del sandbox lleva la marca SANDBOX dentro de su propio valor: BR Code, código de barras, referencia. Es intencionado. Si alguno se filtra a una pantalla, un correo electrónico o un informe, el texto revela su origen. Así no pasa por un cobro real que nadie puede liquidar.

La imagen del QR se genera con normalidad y se muestra bien. Sin embargo, al escanearla con una app bancaria falla, porque el BR Code no es un Pix válido.

Los artefactos son deterministas. El mismo cobro siempre devuelve los mismos valores. Esto es lo que permite probar los reintentos y la idempotencia: repetir el mismo Idempotency-Key devuelve el mismo cobro, no uno nuevo.

#Cómo confirmar un pago en el sandbox

El único resultado que sí puedes forzar es paid. Es la palanca que tiene el comercio para probar por su cuenta los webhooks de extremo a extremo:

text

POST /v1/payments/{id}/confirm-sandbox

Si el cobro se creó con una clave de prueba (un cobro de sandbox), esta llamada lo pasa a PAID y dispara los webhooks normales. Tu endpoint recibe la misma entrega charge.paid que recibiría en producción. Respuesta: { "confirmed": true, "status": "PAID" }. Si el cobro ya está en un estado terminal, responde { "confirmed": false, "status": "…", "reason": "ALREADY_TERMINAL" }. Si no es un cobro de sandbox, se rechaza con 400.

Los SDK lo exponen como payments.confirmSandbox(id) (node client.payments.confirmSandbox(id), python client.payments.confirm_sandbox(id), php $client->payments->confirmSandbox($id), dotnet client.Payments.ConfirmSandboxAsync(id)). La página Test environment del panel hace lo mismo y además simula un payout completado. Esas entregas llevan X-Liqfy-Test: true (consulta Entregas de prueba). El botón Test del endpoint envía una entrega de ejemplo sin tocar ningún cobro.

#Lo que todavía no existe

Pruebes lo que pruebes, ten en cuenta lo siguiente:

El cobro nunca se paga solo. El estado se queda en pending y no avanza con el tiempo. Solo cambia cuando lo confirmas (ver arriba). Es intencionado. Un simulador que "paga" a los N segundos hace que las pruebas dependan del reloj. Además, impide probar el caso más importante: el cobro que nunca se paga y vence.
Solo se puede forzar paid. refused, chargeback y otros resultados negativos no se pueden establecer mediante la API. Están previstos, pero aún no se han implementado.
Solo Pix en la API pública, que hoy está centrada en Pix. Internamente, el simulador también cubre tarjeta, boleto y Multibanco. Aparecerán aquí a medida que el contrato público los exponga.

#Aislamiento

El sandbox comparte la misma cuenta y el mismo libro contable que tu operación real. No es un entorno separado con datos propios. Los cobros de prueba aparecen en tus listados junto a los reales. Se distinguen por la marca SANDBOX del artefacto.

Si esto supone un problema para tu flujo de trabajo, crea una segunda cuenta solo para pruebas.

Filtrar una clave lq_test_ no tiene impacto financiero, porque no puede cobrarle a nadie. Aun así, trátala como una credencial: permite leer los datos de tu cuenta.