Ambiente sandbox

El ambiente sandbox de la API de Pagos a Terceros es un entorno de pruebas diseñado para que desarrolladores e integradores puedan simular transacciones y validar sus integraciones de forma segura, sin procesar pagos reales. Este entorno replica el comportamiento del ambiente de producción, permitiendo probar flujos de pago, validaciones de seguridad, respuestas del API y manejo de errores sin afectar a usuarios finales ni generar cargos reales.

En esta documentación encontrarás todo lo necesario para comenzar a trabajar con el sandbox: cómo obtener credenciales de prueba, ejemplos de peticiones, escenarios simulables y buenas prácticas para asegurar una integración exitosa antes del paso a producción.

Importante

Aunque los datos y comportamientos en sandbox imitan el entorno de producción, pueden existir ligeras diferencias. Asegúrate de realizar pruebas completas antes de lanzar tu integración al público.

Llaves de sandbox

Las llaves de sandbox se obtienen de la misma manera que las llaves productivas, con la particularidad de que el ingresar a la página de programadores se debe cambiar al modo normal, como se muestra a continuación:

Desde el modo sandbox también se permite:

• Ver llaves
• Regenerar llaves
• Configurar URL de eventos
• Ver secreto para la integración de eventos

URL Base de Sandbox

Todos los endpoints productivo estan disponible en el ambiente sandbox

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

Recuerda usar las cabeceras (headers) de todas las solicitudes que se realicen tambien en la API de sandbox. Ejemplo:

user-principal-id: {ID_Usuario_Principal}
x-api-key: {API_Key}

Simular estado de transacciones

En sandbox la solicitud de creación de pago manual (en formato JSON) o por archivo son iguales, la única diferencia es que desde sandbox se permite definir el estado final de las transacciones, para que estas queden aprobadas (APPROVED) o fallidas (FAILED)

Nota

Este campo es opcional; si no se envía, por defecto las transacciones quedan aprobadas (APPROVED)

Pago manual

Para simular el estado final de las transacciones, se debe enviar la propiedad transactionStatus (ver línea 5) con el valor APPROVED o FAILED.

{
  "reference": "payment-reference",
  "accountId": "account-id",
  "paymentType": "PAYROLL",
  "transactionStatus": "FAILED",
  "transactions": [
    {
      "legalIdType": "CC",
      "legalId": "1000000000",
      "bankId": "00000000-0000-0000-0000-000000000000",
      "accountType": "AHORROS",
      "accountNumber": "00000000",
      "name": "John Doe",
      "email": "email@example.com",
      "amount": 1000000,
      "reference": "custom-transaction-reference"
    }
  ]
}

Pago por archivo

Se debe agregar la propiedad transactionStatus al form-data.

Recargar saldo de una cuenta

El entorno sandbox de Wompi incluye un endpoint exclusivo para recargar saldo en cuentas de prueba, permitiendo simular operaciones que requieren fondos disponibles.

Importante

Esta funcionalidad solo está disponible en sandbox y no afecta cuentas reales.

La URL del endpoint para recargar cuenta es:

POST /accounts/balance-recharge

Se debe enviar en el body de la petición los campos de accountId (id de la cuenta a recargar) y amount (cantidad a recargar en centavos). Debe ser minimo $1000,00 y maximo $50.000.000,00

Nota

El accoutId se obtiene al consultar las cuentas. VerConsultar cuentas y saldos

{
  "accountId": "account-id",
  "amountInCents": 340000000
}