Requisitos previos#
Entorno de ejecución compatible (aplicaciones .NET 8 o servicios que consumen la API de MyPay).
Acceso a tu repositorio de artefactos (p. ej., NuGet privado/empresa) donde se publica el SDK.
Hosts definidos para QA/Staging/Producción.
Acceso a tu gestor de secretos (recomendado: AWS Secrets Manager) para la security_key por terminal y las API Keys por tenant.
Descarga del SDK#
El SDK se distribuye como paquete interno en el repositorio de artefactos de tu organización. Localiza la entrada de MyPay SDK (nombre y versión aprobados por tu equipo).
Revisa el changelog del SDK para confirmar compatibilidad con tu versión de API y de .NET.
Versionado y compatibilidad#
Selecciona la última versión estable compatible con tu entorno (evita snapshots a menos que soporte te lo indique).
Verifica notas de ruptura (breaking changes) y el periodo de deprecación si migras desde una versión anterior.
Seguridad de la cadena de suministro#
Asegúrate de que la descarga provenga del repositorio oficial y que cuente con la firma/verificación que usa tu organización.
No uses espejos no oficiales ni paquetes “republicados”.
Preparación del ambiente local#
Define un perfil de configuración para desarrollo con:Host de QA o un mock/sandbox que se te provee para pruebas locales.
Ningún secreto en texto plano: todos deben resolverse desde el gestor de secretos o variables de entorno.
Validación de salud#
Asegúrate de que la API que vas a consumir (local o remota) esté accesible y con CORS/TLS configurados para tu entorno de pruebas.
Confirma que tus credenciales de prueba (API Key y security_key) estén activas y asociadas al tenant/terminal esperado.
Primer uso del SDK#
Configura el cliente del SDK con:Base URL del ambiente (QA para desarrollo).
Resolver de API Key y security_key desde el gestor de secretos (no hardcodear).
Timeouts razonables y políticas de reintento con backoff.
Verifica que las llamadas de prueba retornen respuestas con Trace Id y que el SDK propague ese identificador en las excepciones/errores para facilitar el soporte.
Integración del SDK en un sistema nuevo#
Mantén todo el flujo de pago en servidor. Nunca expongas security_key ni API Keys en aplicaciones cliente (web/móvil).
Crea un módulo/servicio de pagos dedicado que encapsule el SDK y las reglas de negocio (idempotencia, validaciones, retries).
Separa la configuración del código: cada ambiente (Dev/QA/Staging/Prod) tiene su propio archivo de configuración/secretos.
Pasos recomendados#
1.
Define las claves de configuración para: Base URL, tenant/terminal, políticas de reintento/timeout, y límites (rate limiting).
Integra la resolución segura de API Key y security_key desde tu gestor de secretos.
2.
Inicializa el cliente del SDKRegistra el SDK como dependencia compartida en tu contenedor de IoC (si aplica).
Activa telemetría (logs, métricas, trazas) y añade el Trace Id a cada interacción.
3.
Modela los flujos de negocioDefine operaciones para cobros, consultas de transacción, lookup de BIN y reportes paginados.
Implementa idempotencia para cobros: cada orden debe tener una clave única para evitar duplicados ante reintentos.
4.
Mapea los errores del SDK/API a tu modelo interno (validación → 4xx, upstream → 5xx) y construye mensajes sin filtrar secretos ni datos sensibles.
Implementa circuit breakers frente a fallas del procesador o latencias elevadas.
5.
Aplica TLS en todos los hops.
Restringe CORS a orígenes permitidos en producción.
Enmascara PAN/CVV y tokens en logs; no persistas datos que no necesitas.
Alinea la integración con las políticas de PCI DSS y auditorías internas.
6.
Registra métricas clave: tasa de aprobación, rechazo por emisor, latencia por endpoint, errores por categoría.
En cada respuesta, conserva el Trace Id para diagnósticos y tickets.
7.
Crea escenarios de smoke (felices), borde (límites de monto, expiraciones), errores (rechazos 402, validaciones 400/422) y resiliencia (timeouts, 5xx).
Verifica paginación y filtros en reportes con volúmenes realistas.
Pitfalls frecuentes#
Confundir JWT (administración) con X-Api-Key (pagos/consulta).
Ejecutar pruebas contra Producción sin datos ni llaves controladas.
Desplegar con Swagger público habilitado o CORS abierto en Prod.
Omitir rotación de secretos y alertas por uso anómalo.
Recap#
Ya sabes dónde obtener el SDK, cómo ejecutar la API y probar localmente, y cómo integrar el SDK en un sistema nuevo con seguridad, resiliencia y observabilidad.Siguientes pasos#
1.
Revisa Setup para afinar autenticación, secretos y manejo de errores.
2.
Consulta Endpoints para los comportamientos esperados y matrices de errores simulados.
Modificado en 2025-10-29 15:40:17
