Introducción

La API de **Checkout SaaS** te permite integrar cobros digitales avanzados en tu e-commerce o aplicación en cuestión de minutos. Ruteamos transacciones dinámicamente entre las mejores pasarelas de pago de Colombia (Wompi, PayU, Mercado Pago y ePayco) para reducir comisiones, mitigar caídas mediante Smart Failover y conciliar todo bajo un panel administrativo unificado.

Integración Sencilla

Llama a nuestra API REST en formato JSON y obtén una URL única (`checkoutUrl`) lista para redirigir al comprador de forma totalmente segura.

Seguridad Garantizada

Cero responsabilidades de PCI. Cifrado simétrico AES-256-GCM para tus credenciales y Webhooks firmados criptográficamente.

Cómo Obtener tu API Key

Para poder interactuar con los endpoints del backend, necesitas generar un **Token de Integración (API Key)** privado que asocie las llamadas a tu comercio.

Paso a paso visual:

Inicia sesión en el Panel de Control del Comercio (`https://panel.checkoutsaas.com`).
Ve a la barra lateral izquierda y haz clic en la sección Configuración > Claves de API (Settings > API Keys).
Haz clic en el botón superior derecho Generar Nueva Clave.
Completa los detalles:
- Nombre: Ej. "Servidor Tienda WooCommerce".
- Entorno: Elige test para hacer pruebas sin dinero real (usando tarjetas ficticias) o live para transacciones en producción.
Haz clic en Generar.
Importante: Copia la clave secreta completa (`sk_test_...` o `sk_live_...`) inmediatamente. Por motivos de alta seguridad, la guardamos cifrada con hash en la base de datos y **nunca más podrás volver a visualizarla**.

Autenticación

Todas las llamadas a nuestra API se autentican enviando tu API Key en la cabecera HTTP Authorization como un **Bearer token**.

EJEMPLO DE CABECERA HTTP

Authorization: Bearer sk_live_your_secret_key_abcdef12345
Content-Type: application/json

1. Crear Enlace de Pago (POST)

Crea una orden en nuestro sistema enviando la referencia externa, el valor a cobrar y los datos del cliente. Te devolveremos un `checkoutUrl` único al que debes redirigir al comprador.

POST/v1/orders

PAYLOAD SOLICITUD (JSON)

{
  "externalReference": "orden_9023",
  "description": "Zapatillas Nike Air Zoom",
  "currency": "COP",
  "amount": {
    "subtotalCents": 380000,  // Monto en centavos (ej: $380,000 COP)
    "taxCents": 0,
    "discountCents": 0,
    "totalCents": 380000
  },
  "customer": {
    "email": "comprador@correo.com",
    "firstName": "Alejandro",
    "lastName": "Gómez"
  },
  "successRedirectUrl": "https://mitienda.com/exito",
  "expiresInMinutes": 60  // Duración de validez del link de pago
}

RESPUESTA EXITOSA (201 CREATED)

{
  "id": "65b90f4e4f8d2b2f8a1a2b3c",  // ID interno de base de datos
  "publicId": "01HSHJG5H39HGH8JG385GH3G38",  // ID público de la orden (ULID)
  "externalReference": "orden_9023",
  "status": "created",
  "checkoutUrl": "https://pay.checkoutsaas.com/c/01HSHJG5H39HGH8JG385GH3G38" // URL de Redirección
}

2. Consultar Estado del Pago (GET)

Consulta de forma directa y en tiempo real el estado de una orden. El endpoint acepta tanto el ID único de la base de datos como el ID público de la orden (`publicId`).

GET/v1/orders/:id

Reemplaza :id por el ID de MongoDB (ej. 65b90f...) o el ULID de la orden (ej. 01HSH...).

PETICIÓN cURL

curl -X GET https://api.checkoutsaas.com/v1/orders/01HSHJG5H39HGH8JG385GH3G38 \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json"

RESPUESTA EXITOSA (200 OK)

{
  "id": "65b90f4e4f8d2b2f8a1a2b3c",
  "publicId": "01HSHJG5H39HGH8JG385GH3G38",
  "externalReference": "orden_9023",
  "status": "paid",              // Estado de conciliación actual
  "paidAt": "2026-05-23T18:29:45.000Z", // Fecha de pago (null si no está pagado)
  "transactions": [              // Historial de intentos de transacciones
    {
      "gatewayCode": "mercadopago",
      "status": "approved",
      "amountCents": 380000,
      "gatewayTransactionId": "872635418"
    }
  ]
}

Valores de Estados Disponibles (`status`):

Estado	Significado
`created`	La orden se creó y está lista, esperando que el comprador abra la URL de checkout.
`pending`	El comprador está llenando los datos o la pasarela está procesando el cobro de forma asíncrona.
`paid`	¡Éxito! El pago ya fue conciliado y confirmado por la pasarela de pagos.
`cancelled`	La orden fue cancelada manualmente por el comercio.
`expired`	El tiempo límite establecido en `expiresInMinutes` venció sin completarse la transacción.

3. Webhooks (Notificaciones Automáticas)

Para evitar hacer peticiones constantes (*polling*) sobre el estado de un cobro (especialmente en métodos asíncronos como PSE), debes registrar un **Webhook de Salida** en nuestro panel para que tu servidor sea notificado al instante.

Cómo configurar tu Webhook:

Ve a tu **Panel de Comercio** -> pestaña **Configuración > Webhooks** (Settings > Webhooks).
Activa la casilla **Habilitar Webhook**.
Ingresa la **URL de destino** de tu servidor (ej. https://tutienda.com/api/webhooks/checkoutsaas).
Haz clic en **Guardar**.
Copia el **Secret de Firma (HMAC Secret)** generado, el cual es necesario para el paso de validación y seguridad.

Payload enviado a tu servidor (POST JSON):

ESTRUCTURA DEL WEBHOOK (`order.paid`)

{
  "eventType": "order.paid",
  "timestamp": "2026-05-23T18:30:00.123Z",
  "data": {
    "id": "65b90f4e4f8d2b2f8a1a2b3c",
    "publicId": "01HSHJG5H39HGH8JG385GH3G38",
    "externalReference": "orden_9023", // Referencia de tu e-commerce
    "status": "paid",
    "paidAt": "2026-05-23T18:29:45.000Z"
  }
}

Verificación de Firmas de Webhooks

Para garantizar que los webhooks que recibe tu servidor proceden legítimamente de Checkout SaaS (y no de un hacker enviando falsas solicitudes de pago aprobado), firmamos criptográficamente cada petición con el algoritmo **HMAC-SHA256**.

Busca en las cabeceras HTTP la propiedad X-Signature-256. Contiene la firma calculada con tu *Secret de Firma* sobre el cuerpo en formato texto de la petición.

Código de validación listo para producción (NodeJS + Express):

EXPRESS + CRYTPO SIGNATURE VALIDATION

const crypto = require('crypto');

app.post('/api/webhooks/checkoutsaas', (req, res) => {
  const signatureReceived = req.headers['x-signature-256'];
  const webhookSecret = process.env.CHECKOUT_SAAS_WEBHOOK_SECRET;
  
  // Convertir el body JSON a string plano
  const rawBody = JSON.stringify(req.body);
  
  // Calcular firma HMAC SHA-256 localmente
  const calculatedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');
    
  // Comparar de forma segura contra ataques de tiempo
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signatureReceived, 'utf-8'),
    Buffer.from(calculatedSignature, 'utf-8')
  );
  
  if (!isValid) {
    return res.status(401).send('Firma inválida');
  }
  
  // Firma legítima: despachar producto
  const { eventType, data } = req.body;
  if (eventType === 'order.paid') {
    // data.externalReference
  }
  res.status(200).send('OK');
});

Manejo de Errores

La API utiliza respuestas estructuradas en cumplimiento de la especificación estándar **RFC 7807 (Problem Details)** en formato JSON.

EJEMPLO DE ERROR (401 UNAUTHORIZED)

{
  "type": "https://docs.checkoutsaas.com/errors/UNAUTHORIZED",
  "title": "Unauthorized access",
  "status": 401,
  "detail": "API Key is missing or invalid in headers.",
  "instance": "/v1/orders/01HSHJG5H39HGH8JG385GH3G38",
  "code": "UNAUTHORIZED",
  "requestId": "req-9b8a2c3d"
}

Listado de Códigos de Error Comunes (`code`):

Código de Error	HTTP Status	Descripción
`UNAUTHORIZED`	`401`	La clave de API provista es inválida, expiró o no cuenta con los permisos requeridos.
`RESOURCE_NOT_FOUND`	`404`	La orden especificada en la URL no existe en el catálogo de tu comercio.
`VALIDATION_ERROR`	`400`	Los datos enviados no superaron las reglas (ej: montos menores a 0, correos inválidos, etc.).
`CONFLICT_ERROR`	`409`	Operación inválida para el estado actual de la orden (ej: intentar cancelar una orden ya pagada).
`INTERNAL_SERVER_ERROR`	`500`	Hubo un error inesperado al procesar la comunicación con el adquirente de la pasarela.