Skip to main content
Esta guía explica cómo crear un pago en Confío desde tu backend, compartir el enlace de pago con el comprador y recibir notificaciones en tiempo real sobre el estado del pago.

​
Descripción general del proceso

  1. Tu servidor crea el pago mediante la API de Confío
  2. Confío devuelve los datos del pago y una URL lista para compartir
  3. Compartes la URL con el comprador (o la abres en tu app)
  4. El comprador completa el pago en Confío
  5. Recibes webhooks sobre intentos y cambios de estado

​
Requisitos previos

  • Un token de acceso válido a la API de Confío
    Debes contactarnos para generar el token. Una vez generado, te recomendamos almacenarlo en un lugar seguro y no compartirlo
  • IID de la tienda ({store})
  • correlationId único por pago
  • Datos mínimos del pago: amountCents, currencyCode, title, y datos del comprador

​
Obtener la tienda antes de crear el pago

Antes de crear el pago, obtén el identificador de la tienda ejecutando el endpoint de listado de tiendas. 
curl -X GET "https://api.confiopagos.com/v1/stores" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN"
Ejemplo de respuesta (parcial): 
{
  "stores": [
    {
      "name": "stores/01JNRRDZDPH40DB2YRW329BFXM",
      "displayName": "Mi Tienda"
    }
  ]
}
Usa el valor de “name” (o su identificador) como {store} al invocar la creación de pagos.

​
Crear el pago (endpoint)

curl -X POST "https://api.confiopagos.com/v1/stores/{store}/payments" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "correlationId": "order-12345",
    "amountCents": 5000000,
    "currencyCode": "COP",
    "mediaAssets": [
      "https://example.com/images/product1.jpg",
      "https://example.com/images/product2.jpg"
    ],
    "title": "Pago de prueba",
    "description": "Descripción detallada del producto o servicio (mínimo 24 caracteres)",
    "redirectUri": "https://tu-tienda.com/orden-confirmada",
    "buyer": {
      "firstName": "Juan",
      "phoneNumber": "+573215786325"
    }
  }'

​
Parámetros opcionales importantes

​
redirectUri

La URL a la que Confío redireccionará al cliente después de completar el pago exitosamente. Casos de uso:
  • Redirigir al cliente a una página de confirmación en tu sitio web
  • Mostrar detalles de la orden o instrucciones de seguimiento
  • Continuar el flujo de compra en tu aplicación
Comportamiento:
  • Si se proporciona: El cliente será redirigido automáticamente a esta URL después del pago exitoso
  • Si no se proporciona: El cliente permanecerá en la página de confirmación de Confío
Ejemplo: "redirectUri": "https://tu-tienda.com/orden-confirmada?order=12345"
Confío agregará automáticamente los siguientes query parameters a tu redirectUri: status, payment_id y correlation_id. Estos parámetros son meramente cosméticos para dar feedback al usuario y no deben usarse para persistir información en tu sistema.

​
Respuesta 201 (ejemplo)

{
  "name": "stores/01JNRRDZDPH40DB2YRW329BFXM/payments/01JNRVWWHH68E76V3TMFFT6GHJ",
  "url": "https://checkout.confiopagos.com/p/01JNRVWWHH68E76V3TMFFT6GHJ",
  "amountCents": 5000000,
  "currencyCode": "COP",
  "title": "Pago de prueba",
  "status": "AWAITING_PAYMENT"
}

​
Compartir y usar la URL de pago

  • Muestra o envía la url devuelta para que el comprador complete el pago
  • Puedes integrarla en tu app (deep-link / WebView) o compartirla por WhatsApp/Email

​
Pruebas en ambiente de desarrollo

Para probar en desarrollo, te recomendamos probar con PSE o tarjeta.

​
Probar con PSE

En el caso de probar con PSE:
  • Selecciona tipo y número de documento (pueden ser valores falsos)
  • En el banco escoge la opción de Banco Unión Colombiano
  • Da clic en Pay y posteriormente el evento de pago exitoso llegará al webhook

​
Probar con tarjeta

En el caso de probar con tarjeta, utiliza los siguientes datos de prueba:
CampoValor
Número4018810000190011
CVV123
Vencimiento12/34

​
Webhooks a escuchar

  • paymentAttempt.statusChanged: cambios de intentos (aprobado, rechazado)
  • payment.statusChanged: cambios del estado principal (AWAITING_PAYMENT, FUNDED, …)
Consulta la guía de Webhooks para validar el header Authorization: Bearer y el X-Confio-Event.

​
Errores comunes

  • 400 Datos inválidos o falta algún campo requerido
  • 401 Falta o es inválido el Bearer token
  • 404 Tienda no encontrada o sin permisos
  • 429 Demasiadas solicitudes
  • 5xx Error interno (reintentar de forma segura con el mismo correlationId)

​
Mejores prácticas

  1. Genera correlationId únicos y guarda el mapeo interno
  2. Valida y sanitiza todos los datos antes de llamar a la API
  3. Maneja reintentos idempotentes en fallos transitorios
  4. Registra name, url y estados recibidos por webhooks

​
Recursos adicionales