Pruebas en Sandbox

¿Qué es el Sandbox?

El sandbox es un modo de prueba de su cuenta — no un entorno separado. Utiliza la misma API, misma URL base y mismos endpoints que producción. La diferencia es que su cuenta sandbox está conectada a un proveedor bancario simulado: las transacciones se procesan instantáneamente, sin transferencia real de fondos y sin PIX enviado al BACEN.

Sandbox y producción son cuentas separadas, cada una con sus propias credenciales (certificado, clientId, clientSecret). Su certificado puede ser compartido entre ambas cuentas dependiendo de la configuración — consulte con su gerente de cuenta.

Su código no cambia entre sandbox y producción. Cuando esté listo para salir a producción, simplemente cambie a las credenciales de su cuenta de producción. Sin cambios de endpoints, sin cambios de código.

Sandbox vs Producción

	Sandbox	Producción
URL Base	Misma (`https://api.avista.global`)	Misma
Cuenta	Cuenta sandbox dedicada	Cuenta producción dedicada
Credenciales	Certificado + clientId/clientSecret propios	Certificado + clientId/clientSecret propios
Saldo	Simulado (ficticio)	Fondos reales
Transacciones	Simuladas (persistidas — consultables vía API)	PIX real vía BACEN
Webhooks	Simulados (~1s entrega), misma estructura de payload	Reales, entrega depende del proveedor
X-Sandbox-Scenario	Soportado (controle el resultado de los webhooks)	Retorna `400 Bad Request`
Documentación	Misma que producción — todas las páginas de API Reference aplican	Misma

Comenzando con el Sandbox

Contacte a su gerente de cuenta o suporte@avista.global para solicitar una cuenta sandbox.

Recibirá un certificado y credenciales OAuth (clientId + clientSecret) para la cuenta sandbox.

Registre su URL de webhook vía POST /api/webhooks para recibir los eventos de webhook simulados.

En el dashboard, acceda a Configuración para confirmar que su cuenta está en modo sandbox.

Autentíquese, haga llamadas a la API y use el encabezado X-Sandbox-Scenario para simular diferentes resultados.

Descripción General

El encabezado X-Sandbox-Scenario le permite controlar el resultado del webhook para cualquier transacción. Sin él, el sandbox siempre retorna webhooks de éxito. Úselo para probar manejo de errores, retrasos y casos extremos.

Sin el encabezado X-Sandbox-Scenario, el sandbox siempre retorna webhooks de éxito. Para probar escenarios de error (saldo insuficiente, clave inválida, etc.), usted debe enviar el encabezado explícitamente en cada solicitud.

Esta funcionalidad opera solo en sandbox. En producción, el encabezado es ignorado y el comportamiento está determinado por el resultado real de la transacción.

Cómo Funciona

El X-Sandbox-Scenario no altera la respuesta HTTP -- la API siempre retorna 201 Created con status: "PENDING". El escenario simulado afecta únicamente al webhook asíncrono que llega a su URL de callback.

┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│   Su App    │──POST──▶│   API Avista  │──────▶  │  Proveedor Mock │
│             │◀──201───│              │         │                 │
│             │         │              │         │  Procesa el     │
│             │         │              │         │  escenario del  │
│             │         │              │         │  encabezado     │
│             │◀────────│──webhook─────│◀────────│                 │
│             │         │              │         │  ~1s después    │
└─────────────┘         └──────────────┘         └─────────────────┘
      │                                                  │
      │              Respuesta HTTP: siempre 201         │
      │              Webhook: éxito O error              │
      │              (depende del encabezado)             │

Solicitud	Respuesta HTTP	Webhook recibido
Sin `X-Sandbox-Scenario`	`201` PENDING	`CONFIRMED` (éxito)
Con `X-Sandbox-Scenario: success`	`201` PENDING	`CONFIRMED` (éxito)
Con `X-Sandbox-Scenario: error:insufficient-funds`	`201` PENDING	`ERROR` con `errorCode`
Con `X-Sandbox-Scenario: delayed:5s`	`201` PENDING	`CONFIRMED` después de 5s extras

Cómo Usar

Agregue el encabezado X-Sandbox-Scenario a cualquier solicitud de Cash-In, Cash-Out o Refund:

curl -X POST https://api.avista.global/api/pix/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: error:insufficient-funds" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 150.00,
    "details": {
      "key": "recipient@email.com",
      "keyType": "EMAIL",
      "name": "Recipient Name",
      "document": "39284918812"
    },
    "externalId": "test-error-001"
  }'

const response = await axios.post(
  'https://api.avista.global/api/pix/cash-out',
  {
    value: 150.00,
    details: {
      key: 'recipient@email.com',
      keyType: 'EMAIL',
      name: 'Recipient Name',
      document: '39284918812',
    },
    externalId: 'test-error-001',
  },
  {
    headers: {
      Authorization: `Bearer ${token}`,
      'X-Sandbox-Scenario': 'error:insufficient-funds',
    },
  }
);

response = requests.post(
    "https://api.avista.global/api/pix/cash-out",
    json={
        "value": 150.00,
        "details": {
            "key": "recipient@email.com",
            "keyType": "EMAIL",
            "name": "Recipient Name",
            "document": "39284918812",
        },
        "externalId": "test-error-001",
    },
    headers={
        "Authorization": f"Bearer {token}",
        "X-Sandbox-Scenario": "error:insufficient-funds",
    },
)

Escenarios Disponibles

Escenarios de Error

Simule diferentes tipos de fallos en webhooks:

Valor del Encabezado	Descripción	Estado del Webhook
`error:insufficient-funds`	Cuenta sin saldo suficiente	`ERROR`
`error:invalid-pix-key`	La clave PIX no existe en DICT	`ERROR`
`error:document-mismatch`	El documento no coincide con el titular de la clave	`ERROR`
`error:account-blocked`	Cuenta de destino bloqueada o cerrada	`ERROR`
`error:duplicate-id`	ID de envío duplicado	`ERROR`

Escenario de Éxito

Valor del Encabezado	Descripción	Estado del Webhook
`success`	Fuerza éxito (comportamiento predeterminado)	`CONFIRMED`
(sin encabezado)	Comportamiento predeterminado del sandbox	`CONFIRMED`

Escenarios de Retraso

Simule procesamiento lento para probar timeouts y reintentos:

Valor del Encabezado	Descripción	Estado del Webhook
`delayed:5s`	Éxito después de 5 segundos adicionales	`CONFIRMED`
`delayed:30s`	Éxito después de 30 segundos adicionales	`CONFIRMED`
`delayed:60s`	Éxito después de 60 segundos adicionales	`CONFIRMED`

El retraso máximo permitido es de 120 segundos. Los valores superiores serán limitados automáticamente.

Ejemplos de Webhooks Recibidos

Webhook de Éxito (predeterminado)

{
  "event": "CashOut",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "12345",
  "externalId": "test-success-001",
  "endToEndId": "E17745159XI4QA0EGFU",
  "feeAmount": 0.50,
  "originalAmount": 150.00,
  "finalAmount": 150.50,
  "processingDate": "2026-03-26T10:00:00.000Z",
  "errorCode": null,
  "errorMessage": null,
  "counterpart": {
    "name": "Recipient Name",
    "document": "*.284.918-**",
    "bank": {}
  },
  "metadata": {}
}

Webhook de Error (error:insufficient-funds)

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "12345",
  "externalId": "test-error-001",
  "endToEndId": null,
  "feeAmount": 0.50,
  "originalAmount": 150.00,
  "finalAmount": 150.50,
  "processingDate": "2026-03-26T10:00:00.000Z",
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Conta sem saldo",
  "counterpart": {
    "name": null,
    "document": null,
    "bank": {}
  },
  "metadata": {}
}

Cuando el estado es ERROR, el campo endToEndId será null (ya que el PIX nunca fue confirmado por el Banco Central) y los campos errorCode y errorMessage describen la razón del fallo.

Endpoints Compatibles

El encabezado X-Sandbox-Scenario funciona con todos los endpoints transaccionales:

Endpoint	Método	Descripción
`/api/pix/cash-in`	POST	Generar cobro PIX (QR Code)
`/api/pix/cash-out`	POST	Pago PIX por clave
`/api/pix/cash-out/qrcode`	POST	Pago PIX por QR Code
`/api/pix/refund-in`	POST	Solicitud de devolución

Escenarios MED

El módulo MED (Mecanismo Especial de Devolución) no se puede probar directamente vía X-Sandbox-Scenario. Los MEDs dependen de la integración con BACEN y con el proveedor PIX configurado (Woovi, Hyperwallet, etc.), por lo que no pueden ser simulados por el proveedor mock del sandbox.

Para validar su integración con webhooks MED (MedCreated, MedAccepted, MedRejected):

Use POST /api/webhooks/{id}/resend para reenviar un webhook MED existente de su cuenta a la URL configurada. Útil para depurar el handler localmente tras modificaciones.

Use GET /api/med para listar los MEDs asociados a la cuenta, filtrar por estado y conciliarlos con sus transacciones locales.

Si necesita simular un flujo MED de punta a punta (apertura, análisis, aprobación/rechazo), contacte a suporte@avista.global para solicitar acceso al ambiente de homologación.

Los webhooks MED usan la misma estructura de autenticación (Basic Auth) y reintentos que los demás eventos. El payload completo está documentado en MedCreated, MedAccepted y MedRejected.

Comportamiento

La API procesa la solicitud normalmente y retorna 201 Created con estado PENDING. El encabezado no altera la respuesta inmediata -- solo el webhook posterior.

Después de ~1 segundo (o más, si usa delayed:), el webhook se envía a la URL configurada con el escenario simulado.

Su sistema recibe el webhook con el estado correspondiente al escenario (CONFIRMED o ERROR) y debe procesarlo acorde.

Importante: El encabezado X-Sandbox-Scenario controla solo el webhook. La respuesta HTTP del endpoint siempre retorna éxito (201 Created) con status: "PENDING", independientemente del escenario elegido. El resultado final (éxito o error) llega vía webhook.

Restricciones

El encabezado X-Sandbox-Scenario funciona exclusivamente con cuentas configuradas en modo sandbox. Si su cuenta está configurada con un proveedor de producción y envía el encabezado, la API retornará un error:

{
  "statusCode": 400,
  "message": "X-Sandbox-Scenario header is only supported in sandbox mode. This account is not configured with a sandbox provider."
}

Asegúrese de que su cuenta esté en modo sandbox antes de usar esta funcionalidad. Si recibe este error, contacte a suporte@avista.global para verificar la configuración de su cuenta.

Mejores Prácticas

Pruebe todos los escenarios

Implemente manejo para cada estado de webhook (CONFIRMED, PENDING, ERROR) antes de ir a producción.

Valide los campos de error

Cuando status es ERROR, use errorCode y errorMessage para determinar la acción apropiada (reintentar, notificar al usuario, etc.).

Pruebe con retraso

Use escenarios delayed: para verificar que su sistema maneje correctamente webhooks que tardan más en llegar.

Idempotencia

Use transactionId como clave de idempotencia. El mismo webhook puede ser reenviado en caso de fallo en la entrega.

Pruebas en Sandbox

Pruebe todos los escenarios

Valide los campos de error

Pruebe con retraso

Idempotencia

En esta página