Casos mínimos de prueba

Estado documental: Contrato propuesto. El sandbox y sus rutas pasan a estado implementado o verificado únicamente cuando el ambiente esté disponible y las pruebas hayan sido ejecutadas.

Objetivo

El sandbox permite que la empresa pruebe su integración con YUPY sin mover dinero real ni conectar una cuenta bancaria productiva.

Producción
→ credenciales productivas
→ operaciones reales
→ cuentas autorizadas reales
→ conciliación real

Sandbox
→ credenciales de prueba
→ operaciones ficticias
→ resultados simulados
→ sin dinero real

El objetivo no es reproducir internamente un banco. El objetivo es comprobar que el sistema del cliente puede crear operaciones, consultar estados, recibir webhooks y manejar correctamente los resultados que YUPY puede producir.

Principios mínimos

• Sandbox y producción utilizan credenciales independientes.
• Una credencial de sandbox no funciona en producción.
• Las operaciones de sandbox no representan dinero real.
• Las rutas, payloads y estados deben ser equivalentes a los de producción.
• El cambio a producción debe requerir principalmente otra base URL, otras credenciales y la configuración productiva correspondiente.
• Los datos simulados deben identificarse claramente como datos de prueba.

Base URL y credenciales

Sandbox:
<YUPY_SANDBOX_API_BASE_URL>

Producción:
<YUPY_PRODUCTION_API_BASE_URL>

Sandbox:
YUPY_SANDBOX_CLIENT_ID
YUPY_SANDBOX_CLIENT_SECRET

Producción:
YUPY_PRODUCTION_CLIENT_ID
YUPY_PRODUCTION_CLIENT_SECRET

Rutas mínimas de simulación

La biblioteca de endpoints propone las siguientes rutas para pruebas controladas:

Estas rutas son propuestas. El ambiente inicial puede implementar únicamente los escenarios incluidos en la certificación mínima.

Flujo mínimo de prueba

1. Obtener un token

POST /v1/auth/token

La empresa debe comprobar que:

• puede autenticarse con credenciales de sandbox;
• envía el token como Bearer;
• rechaza credenciales inválidas;
• no expone el secreto en el frontend.

2. Crear una orden

POST /v1/payment-orders
Idempotency-Key: 929d954a-9017-4e7b-b918-b5a8ed9c78d1

{
  "external_transaction_id": "SANDBOX-ORDER-001",
  "amount": "85.50",
  "buyer_name": "Comprador de prueba",
  "integration_experience": "web_checkout"
}

La misma prueba puede realizarse con chat_pos cuando la empresa integre POS vía chat.

3. Repetir de forma idempotente

La empresa debe repetir la creación con el mismo ID externo, la misma clave y el mismo payload.

Resultado esperado:
la misma operación
sin crear un duplicado

También debe comprobar que reutilizar la misma clave con datos distintos genera:

409 idempotency_conflict

4. Simular un pago exacto

POST /v1/sandbox/payment-orders/ypt_test_001/simulate-payment

{
  "detected_amount": "85.50",
  "currency": "PEN"
}

Resultado esperado:

payment.detected
payment.reconciled

5. Recibir el webhook

El receptor del cliente debe recibir el mismo sobre canónico utilizado por producción:

{
  "event_id": "evt_test_001",
  "event_type": "payment.reconciled",
  "event_version": "1.0",
  "created_at": "2026-07-20T18:00:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_test_001",
    "external_transaction_id": "SANDBOX-ORDER-001",
    "amount": "85.50",
    "currency": "PEN",
    "state": {
      "operational": "active",
      "financial": "reconciled"
    }
  }
}

El cliente debe validar la firma, registrar el event_id, responder rápidamente con HTTP 200 y procesar el efecto comercial de manera idempotente.

Matriz mínima de certificación

Cómo se evalúa

La primera versión de la certificación puede ser un checklist gestionado por YUPY. No requiere un motor automático de puntajes.

Cada prueba puede quedar con uno de estos resultados:

PASS
FAIL
NOT_APPLICABLE
PASS_WITH_OBSERVATIONS

La evidencia mínima puede incluir:

• request_id;
• ID de la operación;
• respuesta HTTP;
• evento recibido;
• fecha de ejecución;
• observaciones;
• captura o log redactado cuando corresponda.

Criterio mínimo de aprobación

La integración puede pasar a producción cuando:

1. todas las pruebas obligatorias aplicables estén en PASS o PASS_WITH_OBSERVATIONS aceptado;
2. los secretos no estén expuestos;
3. la creación sea idempotente;
4. el cliente distinga payment_reported de reconciled;
5. el receptor valide la firma y deduplique eventos;
6. los errores no provoquen duplicados ni confirmaciones incorrectas;
7. exista un responsable técnico para la activación.

Paso controlado a producción

1. YUPY genera credenciales de producción.
2. La empresa registra su webhook productivo.
3. YUPY entrega el secreto de firma.
4. Se configura el perfil de cobro.
5. La empresa autoriza la cuenta receptora.
6. Se ejecuta una operación real controlada.
7. Se verifica la conciliación y el webhook.
8. Se activa la operación regular.
9. Se observa el inicio productivo.

La prueba productiva controlada utiliza un monto y una operación acordados. No debe ejecutarse con información improvisada ni sin responsables disponibles.

Qué no requiere el sandbox mínimo

• un banco ficticio completo;
• saldos simulados;
• cuentas bancarias sintéticas complejas;
• una réplica de los conectores financieros;
• certificación automática con puntajes;
• pruebas de carga avanzadas;
• simulación de todos los errores posibles;
• un portal independiente para sandbox.

Criterios de aceptación documental

1. Sandbox y producción permanecen separados.
2. El sandbox no mueve dinero real.
3. La API del cliente conserva rutas y payloads equivalentes.
4. Las simulaciones producen estados y eventos canónicos.
5. La certificación inicial puede ser manual.
6. Las pruebas obligatorias cubren autenticación, órdenes, idempotencia, conciliación simulada y webhooks.
7. Las pruebas opcionales dependen de las capacidades utilizadas.
8. No se necesita reproducir un banco.
9. El paso a producción incluye una operación controlada.
10. Todo el contenido permanece como contrato propuesto hasta implementación y verificación.