Skip to main content
Esta guía es SOLO para el programa de partners de Confío. Si solo necesitas consumir la API de Confío o recibir webhooks, esta guía NO aplica para ti. Consulta la sección “Cuándo usar esta guía” a continuación.

​
¿Cuándo usar esta guía?

​
Integración Estándar (NO requiere esta guía)

Si tu caso de uso es:
  • Consumir la API de Confío para crear pagos desde tu aplicación
  • Recibir webhooks de Confío sobre cambios de estado de pagos
  • Usar una cuenta centralizada de Confío para procesar pagos de todos tus usuarios
Entonces NO necesitas esta guía. Simplemente:
  1. Contacta a tu gerente de cuenta de Confío para obtener tu CONFIO_ACCESS_TOKEN
  2. Proporciona la URL de tu endpoint de webhooks para recibir notificaciones
  3. Comienza a usar la API siguiendo la guía de creación de pagos

​
Programa de Partners (SÍ requiere esta guía)

Esta guía aplica únicamente si:
  • Eres una plataforma (ej. Shopify, Dropi, WooCommerce)
  • Cada usuario de tu plataforma tiene su propia cuenta de Confío
  • Necesitas que tus usuarios vinculen sus cuentas de Confío con tu plataforma
  • Requieres autenticación bidireccional (handshake) entre sistemas
Ejemplos: Shopify, Dropi, plataformas de e-commerce donde cada comercio gestiona sus propios pagos.

​
Autenticación de Webhooks

Cuando Confío envía webhooks a tu plataforma, se autentica usando el PARTNER_ACCESS_TOKEN. Este token es diferente del CONFIO_ACCESS_TOKEN que tú usas para consumir la API de Confío:
  • CONFIO_ACCESS_TOKEN: Token que tú usas para autenticarte cuando llamas a la API de Confío
  • PARTNER_ACCESS_TOKEN: Token que Confío usa para autenticarse cuando envía webhooks a tu plataforma
Tu gerente de cuenta de Confío coordinará la configuración de webhooks y te proporcionará el PARTNER_ACCESS_TOKEN que debes validar en tus endpoints. Ejemplo de webhook recibido: 
curl -X POST "https://tu-api.com/confio/notifications" \
  -H "Authorization: Bearer PARTNER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Confio-Event: payment.statusChanged" \
  -d '{
    "event": "payment.statusChanged",
    "data": {
      "name": "stores/01JNRRDZDPH40DB2YRW329BFXM/payments/01JNRVWWHH68E76V3TMFFT6GHJ",
      "status": "DELIVERING",
      "amountCents": 5000000,
      "currencyCode": "COP",
      "correlationId": "order-123"
    },
    "timestamp": 1710345600,
    "signature": {
      "properties": ["name", "status", "amountCents", "currencyCode", "correlationId"],
      "checksum": "sha256=..."
    }
  }'
Esta guía está dirigida a desarrolladores que desean convertirse en partners de Confío. Explica el flujo de autenticación mutua (handshake) entre tu plataforma y Confío para que los comercios conecten sus cuentas de forma segura.

​
Descripción general del proceso

La integración sigue un flujo simple con intercambio de tokens y verificación de firmas:
  1. Tu plataforma genera un token de conexión único y temporal para el comercio (recomendado: JWT firmado o token opaco con TTL)
  2. El usuario copia ese token y lo introduce en Confío
  3. Confío valida el token llamando a tu API
  4. Si es válido, Confío crea un access token para tu plataforma y lo envía mediante un webhook “handshake”
  5. Ahora ambas plataformas pueden comunicarse de forma segura usando tokens válidos y firmas HMAC

​
Requisitos previos

Para implementar la integración, necesitas:
  1. Un endpoint para validar el token y devolver datos del comercio: GET /confio/merchant
  2. Un endpoint para recibir webhooks de Confío: POST /confio/notifications
  3. Capacidad para generar/verificar tokens seguros (JWT o tokens opacos con TTL)
  4. Secret compartido para firmas HMAC de webhooks (suministrado por Confío)
  5. Registro como proveedor oficial (contacta a nuestro equipo: +57 304 671 7568)

​
Paso 1: Generar token de conexión

Tu plataforma debe proporcionar una interfaz gráfica o API donde los usuarios puedan generar un token de conexión para Confio. Este token debe:
  • Ser único para cada comercio
  • Contener información suficiente para identificar al comercio en tu plataforma

​
Ejemplo de implementación

function generateConnectionToken(organizationId) {
  // Genera un token único y seguro para el comercio
  // Asocia el token con el id del comercio en tu sistema
  const token = generateSecureToken();

  // Almacena la relación entre el token y el comercio
  storeTokenForOrganization(organizationId, token, {
    purpose: "confio_connection",
    created_at: new Date(),
  });

  return token;
}

// Muestra este token al usuario en tu interfaz
const connectionToken = generateConnectionToken("organizations/abc123");

​
Paso 2: Implementar endpoint de información del comerciante

Debes crear un endpoint en tu API que Confio utilizará para autenticar al comercio mediante el token y obtener información completa del comerciante: GET /confio/merchant. Este endpoint recibe el token en el encabezado de autorización Authorization: Bearer <token>. El endpoint debe:
  1. Verificar que el token es válido
  2. Obtener la información del comerciante
  3. Devolver la información del comerciante; en caso de error, usar códigos adecuados

​
Solicitud

curl -X GET "https://tu-api.com/confio/merchant" \
  -H "Authorization: Bearer CONNECTION_TOKEN"
Donde CONNECTION_TOKEN es el token que el usuario ingresó en Confio.

​
Respuesta 200 (ejemplo)

{
  "id": "platform_merchant_12345",
  "name": "Tienda Ejemplo"
}

​
Errores comunes

  • 400 Invalid token or purpose
  • 401 Unauthorized: Bearer token required
  • 403 Token expired or revoked
  • 404 Organization not found
  • 429 Too Many Requests
  • 5xx Internal server errors

​
Ejemplo de implementación

app.get("/confio/merchant", (req, res) => {
  // Extraer el token del encabezado de autorización
  const authHeader = req.headers.authorization;

  // Verificar que el encabezado existe y tiene el formato correcto
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return res
      .status(401)
      .json({ error: "Unauthorized: Bearer token required" });
  }

  const token = authHeader.substring(7); // Eliminar 'Bearer ' del inicio

  try {
    // Verificar el token en tu sistema
    const tokenData = verifyAndGetTokenData(token);

    // Verificar que el token es válido y su propósito es correcto
    if (!tokenData || tokenData.purpose !== "confio_connection") {
      return res.status(400).json({ error: "Invalid token or purpose" });
    }

    // Obtener la información del comercio asociado al token
    const organizationInfo = getOrganizationInfo(tokenData.organizationId);
    if (!organizationInfo) {
      return res.status(404).json({ error: "Organization not found" });
    }

    // Responder con éxito e información del comerciante
    return res.json({
      id: organizationInfo.storeId,
      name: organizationInfo.storeName,
    });
  } catch (error) {
    return res.status(400).json({ error: error.message });
  }
});

​
Paso 3: Recibir webhooks de Confío (handshake y otros)

Confio enviará notificaciones a tu plataforma a través del endpoint que proporcionaste. Para el proceso de conexión inicial, Confio enviará una notificación de tipo handshake que incluye información de la organización.

​
Encabezados

  • Authorization: Bearer PARTNER_ACCESS_TOKEN - Este es el token que TÚ generaste en el Paso 1 y que Confío usa para autenticarse contigo
  • X-Confio-Event: handshake | teardown | ... - Tipo de evento

​
Ejemplo (curl)

curl -X POST "https://tu-api.com/confio/notifications" \\
  -H "Authorization: Bearer PARTNER_ACCESS_TOKEN" \\
  -H "Content-Type: application/json" \\
  -H "X-Confio-Event: handshake" \\
  -d '{
    "event": "handshake",
    "data": {
      "organization": "an29fjw9",
      "store": "es54jhi3",
      "token": "CONFIO_ACCESS_TOKEN"
    },
    "timestamp": 1710345600,
    "signature": {
      "properties": ["organization", "store", "token"],
      "checksum": "sha256=..."
    }
  }'
IMPORTANTE: El CONFIO_ACCESS_TOKEN en el body es el token que Confío genera para que TÚ lo uses en futuras llamadas a la API de Confío. Debes almacenar este token de forma segura.

​
Validación del tipo de notificación

El endpoint /confio/notifications recibe notificaciones identificadas por el encabezado X-Confio-Event. Es crucial que verifiques este encabezado antes de procesar cualquier notificación, ya que en el futuro Confio podría enviar diferentes tipos de eventos a este mismo endpoint. Para el proceso de conexión inicial, el valor del encabezado será handshake. Este tipo de notificación incluye:
  • organization: ID de la organización en tu sistema
  • store: ID de la tienda en tu sistema
  • token: El CONFIO_ACCESS_TOKEN que debes almacenar para hacer llamadas a la API de Confío

​
Ejemplo de implementación

app.post("/confio/notifications", (req, res) => {
  // Extraer el token del encabezado de autorización
  const authHeader = req.headers.authorization;

  // Verificar que el encabezado existe y tiene el formato correcto
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return res
      .status(401)
      .json({ error: "Unauthorized: Bearer token required" });
  }

  const token = authHeader.substring(7); // Eliminar 'Bearer ' del inicio

  // Obtener y validar el tipo de notificación del encabezado
  const topic = req.headers["x-confio-event"];

  // Es crucial validar el tipo de notificación antes de procesar
  if (!topic) {
    return res.status(400).json({
      success: false,
      error: "Missing X-Confio-Event header",
    });
  }

  // Manejar diferentes tipos de notificaciones
  switch (topic) {
    case "handshake":
      const payload = req.body.data;
      // Procesar la notificación de handshake
      storeConfioToken(payload, token);
      break;

    // Otros tipos de notificaciones pueden ser procesados aquí a medida que
    // se implementen nuevas características
    default:
      // Registrar la notificación para futuras implementaciones
      // pero seguimos aceptando el webhook para no romper la integración
      logUnknownNotification(topic, req.body);
      break;
  }

  // Responder con éxito
  return res.json({ success: true });
});

​
Paso 4: Utilizar los tokens para comunicación API

Una vez completado el intercambio de tokens, ambas plataformas pueden comunicarse entre sí utilizando los tokens de acceso.

​
Llamadas desde tu plataforma a Confio

Utiliza el CONFIO_ACCESS_TOKEN que recibiste en el webhook de handshake para autenticar tus llamadas a la API de Confío. Ejemplo de llamada a la API de Confio para obtener el estado de un pago: 
curl -X GET "https://api.confiopagos.com/v1/stores/{store}/payments/{payment}" \\
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \\
  -H "Content-Type: application/json"

​
Recibir llamadas de Confio

Confio utilizará el PARTNER_ACCESS_TOKEN (que tú generaste) para autenticar sus solicitudes a tu API mediante webhooks.

​
Eliminar integración

El usuario tendrá la opción de eliminar la integración una vez vinculada. Para esto, Confio emitirá una notificación a tu plataforma a través de un webhook con el tipo de evento teardown. Este evento incluirá la información de la organización y la tienda en el payload.

​
Especificación del webhook

curl -X POST "https://tu-api.com/confio/notifications" \
  -H "Authorization: Bearer PARTNER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Confio-Event: teardown" \
  -d '{
    "event": "teardown",
    "data": {
      "organization": "an29fjw9",
      "store": "es54jhi3"
    },
    "timestamp": 1710345600,
    "signature": {
      "properties": ["organization", "store"],
      "checksum": "sha256=..."
    }
  }'

​
Ejemplo de implementación

app.post("/confio/notifications", (req, res) => {
  // Extraer el token del encabezado de autorización
  const authHeader = req.headers.authorization;

  // Verificar que el encabezado existe y tiene el formato correcto
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return res
      .status(401)
      .json({ error: "Unauthorized: Bearer token required" });
  }

  const token = authHeader.substring(7); // Eliminar 'Bearer ' del inicio

  // Obtener y validar el tipo de notificación del encabezado
  const topic = req.headers["x-confio-event"];

  // Es crucial validar el tipo de notificación antes de procesar
  if (!topic) {
    return res.status(400).json({
      success: false,
      error: "Missing X-Confio-Event header",
    });
  }

  // Manejar diferentes tipos de notificaciones
  switch (topic) {
    case "handshake":
      // Procesar la notificación de handshake
      storeConfioToken(req.body.data, token);
      break;

    case "teardown":
      // Procesar la notificación de eliminación de integración
      const organization = req.body.data.organization;
      // Eliminar la información de la organización en tu sistema
      removeOrganizationData(organization);
      break;

    // Otros tipos de notificaciones pueden ser procesados aquí a medida que
    // se implementen nuevas características
    default:
      // Registrar la notificación para futuras implementaciones
      // pero seguimos aceptando el webhook para no romper la integración
      logUnknownNotification(topic, req.body);
      break;
  }

  // Responder con éxito
  return res.json({ success: true });
});

​
Seguridad y mejores prácticas

  1. Utiliza HTTPS: Todas las comunicaciones deben realizarse a través de HTTPS.
  2. Valida los tokens: Siempre verifica la autenticidad de los tokens recibidos.
  3. Almacenamiento seguro: Guarda los tokens en un almacenamiento seguro y cifrado.

​
Pruebas de integración

Confio proporciona un entorno de sandbox para probar tu integración antes de pasar a producción. Contacta a nuestro equipo para obtener credenciales de sandbox.

​
Flujo de prueba recomendado

  1. Genera un token de conexión en tu entorno de desarrollo
  2. Utiliza la interfaz de sandbox de Confio para introducir el token
  3. Verifica que tu endpoint de validación recibe y procesa correctamente la solicitud
  4. Confirma que tu endpoint de webhook recibe el token de Confio
  5. Prueba las llamadas API en ambas direcciones

​
Soporte y recursos adicionales

Si encuentras problemas durante la integración, puedes: