Modo Sandbox

El modo Sandbox es un entorno de pruebas por cliente que permite hacer llamadas reales a la API, recibir respuestas con formato real, y probar el flujo completo de webhooks — sin mover dinero real ni crear transacciones.

Cómo activarlo

Un administrador de Rivopay establece tu status de cliente a SANDBOX. Para pasar a producción, deberás completar un conjunto de pruebas que validen tu integración antes de que tu status cambie a ACTIVE.

Qué ocurre en cada request

Cada vez que haces un request, la API detecta que tu cuenta está en modo de pruebas y redirige la operación a un proveedor simulado en lugar del proveedor de pagos real.

Tu request llega a la API
        │
        ▼
La API verifica que tu cuenta está en modo Sandbox
  → La solicitud se identifica como operación de prueba
        │
        ▼
En lugar de conectarse al proveedor de pagos real,
se genera una respuesta simulada con el mismo formato que producción:
  { txId, qrCode, copiaECola, estimatedFees, ... }
        │
        ▼
La transacción se guarda en la base de datos marcada como simulada
  Estado: PENDING — espera activación manual vía endpoint de simulación

Datos mock por operación

Operación	Mock devuelto
`POST /v1/br/payin/pix/instant`	QR code fake con formato real, `expiresAt` en 30 min
`GET /v1/br/payin/pix/{txId}`	`status: PENDING`
`POST /v1/br/payout/pix/key`	`id: mock-payout-{timestamp}`, `status: PROCESSING`
`GET /v1/br/payout/pix/{txId}`	`status: PROCESSING`

Simular la confirmación del pago

Como no existe una transacción real, el webhook de confirmación nunca llega automáticamente. Para completar el flujo usa el endpoint de simulación:

POST /v1/sandbox/simulate/{txId}

{ "outcome": "completed" }

{ "outcome": "failed" }

El campo outcome es opcional — por defecto es "completed".

Lo que hace internamente:

1. Busca la transacción por su txId
2. Verifica que sea una transacción de prueba  →  si es real, responde 400
3. Verifica que aún esté pendiente o en proceso  →  si ya terminó, responde 409
4. Cambia el estado a COMPLETED o FAILED según el outcome
5. Si el outcome es "completed" y es un Pay-In:
   → Acredita el monto en el saldo de tu cuenta
   → Registra el movimiento en el historial contable
6. Envía el webhook a la URL configurada en tu cuenta:
   → payin.completed / payin.failed
   → payout.completed / payout.failed
   → El payload indica que es una operación simulada
7. Responde: { simulated: true, txId, outcome, status }

Flujo completo de integración

1. POST /v1/br/payin/pix/instant
   ← { txId: "abc123", qrCode: "00020126...", status: "PENDING" }

2. (muestras el QR — nadie paga en realidad)

3. POST /v1/sandbox/simulate/abc123
   Body: { "outcome": "completed" }
   ← { simulated: true, status: "COMPLETED" }

4. → Tu webhookUrl recibe:
   {
     "eventType": "payin.completed",
     "txId": "abc123",
     "amount": 10000,
     "feeCharged": 300,
     "netAmount": 9700,
     "sandbox": true
   }

5. GET /v1/br/payin/pix/abc123
   ← { status: "COMPLETED", feeClient: 300, ... }

Restricciones

Situación	Comportamiento
Intentar simular una transacción real (no de prueba)	`400 Only sandbox transactions can be simulated`
Intentar simular una transacción que ya finalizó	`409 Cannot simulate: transaction is already COMPLETED`
Tu cuenta está suspendida	`401` — la API rechaza el request antes de procesarlo
Tu cuenta pasa a producción	Las transacciones se procesan con dinero real — el modo de prueba se desactiva automáticamente
Entorno de staging global de Rivopay	Todos los clientes operan en modo simulado sin importar el estado de su cuenta