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

Cliente con status SANDBOX
        │
        ▼
Authorizer lee client.status === 'SANDBOX'
  → isSandbox: true  (pasa en el contexto del request)
        │
        ▼
Handler (payin/payout)
  → getProvider(cuenta, isSandbox=true)
  → El provider usa mockRequest() internamente
        │
        ▼
Respuesta idéntica a producción:
  { txId, qrCode, copiaECola, estimatedFees, ... }
  (datos simulados pero con formato real)
        │
        ▼
TX guardada en la DB con sandbox: true
  Status: PENDING — queda esperando 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 TX en la base de datos
2. Verifica que sandbox: true  →  si no, 400
3. Verifica que status sea PENDING o PROCESSING  →  si no, 409
4. Actualiza TX → COMPLETED o FAILED
5. Si outcome=completed y tipo=PAYIN:
   → Acredita el saldo y registra el movimiento contable
   → Acredita el balance del cliente en el ledger
6. Dispara webhook al webhookUrl del cliente:
   → payin.completed / payin.failed
   → payout.completed / payout.failed
   → Payload incluye sandbox: true
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
Simular TX de producción (sandbox: false)	400 Only sandbox transactions can be simulated
Simular TX ya COMPLETED	409 Cannot simulate: transaction is already COMPLETED
Cliente con status SUSPENDED	401 — el authorizer rechaza el request
Cliente pasa a status ACTIVE	isSandbox = false automáticamente — transacciones reales
Variable MOCK=true en el entorno (staging global)	Todos los clientes usan mock independientemente de su status