cs-payu-sapi

(0 reviews)

Solución de integración para gestionar pagos con tarjeta de crédito, PSE, tokens de tarjetas, reembolsos, devoluciones parciales y pagos en efectivo. Incluye consulta de bancos disponibles, métodos de pago y generación de reportes de transacciones.

🛡️ cs-payu-sapi

Solución integral de gestión de pagos electrónicos que permite procesar transacciones con tarjeta de crédito, PSE y métodos alternativos. Incluye endpoints para:

Procesamiento de pagos con tarjeta de crédito y débito
Transacciones PSE (Pagos Seguros en Línea) con bancos colombianos
Gestión completa de tokens de tarjetas (creación, consulta, eliminación)
Procesamiento masivo de pagos mediante archivos CSV/JSON
Reembolsos totales y parciales de transacciones
Consulta de métodos de pago disponibles
Generación de reportes de transacciones y conciliaciones
Registro y eliminación masiva de tokens de tarjetas

Todos los servicios exponen operaciones REST con soporte multi-formato (JSON, CSV, Octet-Stream) y proporcionan integración robusta con pasarela de pagos para transacciones seguras de alto volumen.

🌐 Información Base

Título de la API: cs-payu-sapi
Versión: 1.0.0-SNAPSHOT
Plataforma: MuleSoft Anypoint Platform
Runtime: Mule 4.4.0
URL Base Producción: https://cs-payu-sapi-prod.us-e1.cloudhub.io/api/
URL Base QA: https://cs-payu-sapi-qa.us-e1.cloudhub.io/api/
Protocolo: REST
Formato de Datos: JSON, CSV, Octet-Stream
Autenticación: OAuth 2.0 + Client ID

🚀 Cómo Comenzar

Autenticación: Asegúrate de tener el client_id requerido y el token Bearer OAuth 2.0 para acceso seguro.
URL Base: Usa la URL Base proporcionada como prefijo para todos los endpoints de la API.
Encabezados: Agrega los siguientes encabezados en tus solicitudes de API:

-H "Content-Type: application/json"
-H "client_id: TU_CLIENT_ID"
-H "Authorization: Bearer TU_ACCESS_TOKEN"
-H "X-Correlation-ID: TU_CORRELATION_ID"  # Opcional pero recomendado para trazabilidad

🚀 Cómo Consumir

Puedes acceder y consumir esta API a través de las siguientes plataformas:

🔗 MuleSoft Exchange (PayU Services API)
🔗 Portal Público FGS

📍 Endpoints Disponibles

Método	Endpoint	Content-Type	Descripción
GET	`/api/PSE/banks`	-	Obtener lista de bancos disponibles para pagos PSE
GET	`/api/reports`	-	Consultar reportes y estados de transacciones
POST	`/api/payments/cash-or-referenced`	`application/json`	Generar referencia de pago en efectivo (puntos físicos)
DELETE	`/api/credit-card/tokens/{tokenId}`	-	Eliminar un token específico de tarjeta de crédito
GET	`/api/credit-card/tokens`	-	Consultar tokens de tarjetas de crédito existentes
POST	`/api/payments/credit-card`	`application/json`	Procesar pago con tarjeta de crédito o débito en tiempo real
POST	`/api/credit-card/tokens`	`application/json`	Crear token de tarjeta de crédito para pagos recurrentes
POST	`/api/payments/PSE`	`application/json`	Procesar pago mediante PSE con bancos colombianos
GET	`/api/payments/available-methods`	-	Consultar métodos de pago disponibles según configuración
POST	`/api/partial-refunds`	`application/json`	Procesar reembolso parcial de una transacción
POST	`/api/refunds`	`application/json`	Procesar reembolso completo de una transacción
POST	`/api/payments/webcheckout-form`	`application/json`	Procesar transacciones usando formulario HTML de PayU
POST	`/api/credit-card/tokens/bulk/registration`	`application/json`	Registro masivo de tokens de tarjetas de crédito (JSON)
POST	`/api/credit-card/tokens/bulk/registration`	`application/octet-stream`	Registro masivo de tokens mediante archivo binario
POST	`/api/credit-card/tokens/bulk/registration`	`text/csv`	Registro masivo de tokens mediante archivo CSV
DELETE	`/api/credit-card/tokens/bulk`	`application/json`	Eliminación masiva de tokens de tarjetas de crédito (JSON)
DELETE	`/api/credit-card/tokens/bulk`	`application/octet-stream`	Eliminación masiva de tokens mediante archivo binario
DELETE	`/api/credit-card/tokens/bulk`	`text/csv`	Eliminación masiva de tokens mediante archivo CSV
POST	`/api/payments/bulk-tokens`	`application/octet-stream`	Procesamiento masivo de pagos mediante archivo binario
POST	`/api/payments/bulk-tokens`	`application/json`	Procesamiento masivo de pagos usando tokens (JSON)
POST	`/api/payments/bulk-tokens`	`text/csv`	Procesamiento masivo de pagos mediante archivo CSV

⚠️ Manejo de Errores

Se utilizan códigos de estado HTTP estándar para el manejo de errores:

📊 Códigos de Respuesta

Código	Estado	Descripción	Causa Común	Acción Recomendada
`200`	✅ OK	Transacción procesada exitosamente	Pago aprobado por la pasarela	Continuar con el flujo de negocio
`400`	❌ Bad Request	Parámetros faltantes o inválidos	Datos de tarjeta incorrectos, montos negativos	Revisar estructura del JSON y validar campos requeridos
`401`	🔒 Unauthorized	Autenticación fallida	Token expirado o client_id inválido	Renovar token de autenticación OAuth
`403`	🚫 Forbidden	Sin permisos suficientes	Client_id sin permisos para procesar pagos	Verificar permisos y configuración del comercio
`404`	🔍 Not Found	Recurso no encontrado	Token de tarjeta inexistente, transacción no encontrada	Verificar IDs y referencias de transacciones
`422`	⚠️ Unprocessable Entity	Transacción rechazada por la pasarela	Fondos insuficientes, tarjeta bloqueada	Notificar al usuario y solicitar otro método de pago
`429`	⏰ Rate Limited	Demasiadas solicitudes	Exceso de requests por minuto	Implementar retry con exponential backoff
`500`	💥 Internal Server Error	Error inesperado en el servidor	Fallo interno del sistema	Contactar soporte técnico con correlation ID
`503`	🛠️ Service Unavailable	Servicio temporalmente no disponible	Mantenimiento programado, pasarela caída	Reintentar más tarde, notificar al usuario
`504`	⏱️ Gateway Timeout	Timeout en la pasarela de pagos	Respuesta lenta del banco o pasarela	Consultar estado de transacción antes de reintentar

Estructura de Error Estándar

{
  "code": "400",
  "message": "Bad request: Invalid credit card number",
  "transactionId": "abc123-def456-ghi789",
  "timestamp": "2025-11-14T10:30:45.123Z",
  "details": {
    "field": "creditCard.number",
    "error": "Card number must be between 13-19 digits"
  }
}

❓ Preguntas Frecuentes

💳 Error 422 - Transacción Rechazada

Síntomas: "Transaction declined by payment gateway"
Causas: Fondos insuficientes, tarjeta vencida, límite de crédito excedido, tarjeta bloqueada por el banco
Solución: Verificar con el usuario el estado de su tarjeta, solicitar método de pago alternativo

🔐 Error 401 - Unauthorized

Síntomas: Respuesta "Authentication failed"
Causas: Token expirado, client_id incorrecto, headers malformados
Solución: Verificar y renovar credenciales OAuth, validar formato de headers

⏰ Error 504 - Gateway Timeout

Síntomas: Timeout después de 60 segundos sin respuesta
Causas: Servicios de pasarela lentos, sobrecarga del sistema, problemas de conectividad bancaria
Solución: Consultar estado de la transacción usando referenceCode antes de reintentar, evitar duplicados

📊 Error 429 - Rate Limiting

Síntomas: "Too Many Requests"
Causas: Exceso de requests por minuto (límite: 100/min por client_id)
Solución: Implementar queue con rate limiting, espaciar requests, usar bulk endpoints para procesamiento masivo

🏦 Bancos PSE No Disponibles

Síntomas: Listado de bancos vacío o incompleto
Causas: Problemas de conectividad con ACH Colombia, mantenimiento de bancos
Solución: Reintentar consulta, verificar horarios de disponibilidad PSE (24/7 excepto mantenimientos programados)

📄 Error en Procesamiento Masivo

Síntomas: Algunos registros del CSV fallan
Causas: Formato incorrecto, tokens inválidos, datos incompletos
Solución: Revisar formato CSV, validar tokens previamente, procesar respuesta para identificar registros fallidos

📞 Soporte

Para asistencia, contacta al equipo de Coordinación de Servicios de Integración y Aplicaciones.

Correo electrónico: epalma@fgs.co

📅 Información Adicional

Documentación generada y actualizada en Noviembre 2025 por epalma@fgs.co - Edna Nayibe Palma

📋 Nota Importante: Esta documentación se actualiza continuamente. Para la versión más reciente y cambios en tiempo real, consulta siempre el Portal de Exchange oficial.

🔒 Aviso de Seguridad: Nunca compartas credenciales de API en repositorios públicos o documentación. Usa siempre variables de entorno para información sensible. Cumple con PCI-DSS al manejar datos de tarjetas.

💳 Aviso Legal: El procesamiento de pagos está sujeto a términos y condiciones de la pasarela de pagos. Las transacciones pueden estar sujetas a comisiones según el método de pago y configuración del comercio.

home