Sandbox para dispersiones BRE-B

El ambiente sandbox permite probar el flujo completo de dispersiones BRE-B sin procesar pagos reales. Puedes simular la previsualización de llaves, la creación de dispersiones y la recepción de eventos, validando tu integración antes de pasar a producción.

URL Base de Sandbox

https://api.sandbox.payouts.wompi.co/v2

Usa las llaves de sandbox en las cabeceras de todas las solicitudes:

x-api-key: {API_Key_Sandbox}
user-principal-id: {ID_Usuario_Principal_Sandbox}

Obtener llaves de sandbox

Las llaves de sandbox se obtienen desde el dashboard de Wompi:

1. Inicia sesión en tu cuenta principal en el dashboard de comercios.
2. Ve a Desarrollo > Programadores.
3. En la parte superior izquierda, selecciona Pagos a Terceros.
4. Cambia al modo Sandbox.

Desde el modo sandbox puedes:

• Ver y regenerar llaves
• Configurar URL de eventos
• Ver el secreto para verificación de eventos

Llaves BRE-B de prueba

En sandbox, las siguientes llaves BRE-B están disponibles para simular resoluciones exitosas:

Resoluciones exitosas (200 OK)

Tipo	Valor de prueba	Titular simulado	Entidad
MAIL	ecolon@wompi.com	Joh*** Car*** Per*** Gom***	BANCOLOMBIA (007)
PHONE	3001234567	Mar*** Lop*** Rui***	BANCO POPULAR (002)
IDENTIFICATION	1020304050	And*** Fel*** Gar*** Rod***	BANCO POPULAR (002)
ALPHANUMERIC	@elias123	Eli*** Can*** Mor***	BANCO DAVIVIENDA (051)
ESTABLISHMENT_CODE	B00012345	Tie*** Wom***	BANCOLOMBIA (007)
IDENTIFICATION (NIT)	900123456	Acm*** Sol***	BANCO DAVIVIENDA (051)

Simulación de errores

Valor de prueba	Error simulado	Código
noexiste@test.com	Llave no encontrada (404)	EXC_034
12345	Formato de llave inválido (400)	EXC_033
inactiva@test.com	Llave inactiva (400)	EXC_035
timeout@test.com	Timeout del servicio (503)	EXC_037
error@test.com	Servicio no disponible (503)	EXC_036

info

Cualquier llave BRE-B diferente a las listadas retornará un error EXC_034 (llave no encontrada) en sandbox.

Previsualizar una llave en sandbox

GET https://api.sandbox.payouts.wompi.co/v2/breb/keys/resolve/@elias123?keyType=ALPHANUMERIC

Headers:

x-api-key: {API_Key_Sandbox}
user-principal-id: {ID_Usuario_Principal_Sandbox}

Respuesta:

{
  "status": 200,
  "meta": {
    "trace_id": "76470560-65e8-11f1-a897-a36bb8b3a60b"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "Eli*** Can*** Mor***",
    "financialEntity": {
      "name": "BANCO DAVIVIENDA",
      "code": "051"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@ELIAS123"
  }
}

Crear una dispersión BRE-B en sandbox

La creación de dispersiones en sandbox funciona igual que en producción, con la adición del campo opcional transactionStatus para simular el estado final de las transacciones.

Simular estado de transacciones

Agrega el campo transactionStatus al body para definir el resultado simulado:

Valor	Comportamiento
APPROVED	Todas las transacciones del lote quedan aprobadas (valor por defecto)
FAILED	Todas las transacciones del lote quedan fallidas

nota

Si no se envía transactionStatus, por defecto las transacciones quedan aprobadas (APPROVED).

Ejemplo: dispersión aprobada

{
  "reference": "sandbox-breb-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactions": [
    {
      "amount": 150000,
      "name": "Test User",
      "email": "test@example.com",
      "key": "@elias123"
    }
  ]
}

Ejemplo: dispersión fallida

{
  "reference": "sandbox-breb-002",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactionStatus": "FAILED",
  "transactions": [
    {
      "amount": 150000,
      "name": "Test User",
      "email": "test@example.com",
      "key": "@elias123"
    }
  ]
}

Recargar saldo en sandbox

Para tener saldo disponible en la cuenta origen, puedes recargar usando el endpoint de recarga disponible en sandbox.

📖 Ver cómo recargar saldo en sandbox

Eventos en sandbox

Los eventos (webhooks) se disparan en sandbox de la misma manera que en producción. Para recibirlos:

1. Configura la URL de eventos en modo sandbox desde el dashboard.
2. Crea una dispersión BRE-B.
3. Recibirás los eventos payout.updated y transaction.updated en la URL configurada.

La verificación de firma funciona igual que en producción, usando el secreto de sandbox visible en el dashboard.

Flujo completo de prueba

1. Obtener credenciales sandbox desde el dashboard (modo sandbox).
2. Recargar saldo con POST /accounts/balance-recharge.
3. Previsualizar llave con GET /breb/keys/resolve/@TESTUSER.
4. Crear dispersión con POST /payouts usando la llave de prueba.
5. Recibir evento en la URL configurada con el estado final.
6. Consultar estado con GET /payouts/{payoutId} para verificar.

Diferencias entre sandbox y producción

Aspecto	Sandbox	Producción
Llaves BRE-B	Solo las de prueba listadas arriba	Cualquier llave activa en el directorio BRE-B
Estado de transacción	Controlable con transactionStatus	Determinado por el procesamiento real
Saldo de cuenta	Recargable libremente	Saldo real de la cuenta bancaria
Tiempo de procesamiento	Inmediato	Sujeto a ciclos ACH y horarios bancarios
Eventos	Se disparan inmediatamente	Se disparan según el ciclo de procesamiento
Dinero real	No se mueve dinero	Se ejecutan transferencias reales

Importante

Aunque el sandbox replica el comportamiento de producción, pueden existir diferencias menores. Realiza pruebas completas antes de pasar a producción.