Crea un pago en Confío

​

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 de tu sistema para conciliar el pago con tu orden interna
• Datos mínimos del pago: amountCents, currencyCode, title, y datos del comprador

​

Obtener la tienda antes de crear el pago

curl -X GET "https://api.confiopagos.com/v1/stores" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN"

{
  "stores": [
    {
      "name": "stores/01JNRRDZDPH40DB2YRW329BFXM",
      "displayName": "Mi Tienda"
    }
  ]
}

​

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

​

Respuesta 200 (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

​

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

​

Webhooks a escuchar

• paymentAttempt.statusChanged: cambios de intentos (aprobado, rechazado)
• payment.statusChanged: cambios del estado principal (AWAITING_PAYMENT, FUNDED, …)

​

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 o timeout

​

Mejores prácticas

1. Usa correlationId para mapear el pago con tu orden interna.
2. Valida y sanitiza todos los datos antes de llamar a la API.
3. Registra name, url y estados recibidos por webhooks.

​

Recursos adicionales

• Referencia del endpoint
• Listar tiendas
• Webhooks
• Flujo logístico (actualizar estados)

​

Idempotencia con Idempotency-Key

curl -X POST "https://api.confiopagos.com/v1/stores/{store}/payments" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: f47ac10b-58cc-4372-8567-0e02b2c3d479" \
  -d '{
    "correlationId": "order-12345",
    "amountCents": 5000000,
    "currencyCode": "COP",
    "title": "Pago de prueba",
    "description": "Descripción detallada del producto o servicio (mínimo 24 caracteres)",
    "buyer": {
      "firstName": "Juan",
      "phoneNumber": "+573215786325"
    }
  }'

• Genera una clave nueva y aleatoria para cada operación lógica de creación de pago; UUID v4 es una buena opción.
• Guarda la clave junto con tu orden interna antes de llamar a Confío.
• Si envías de nuevo la misma operación, usa la misma clave y el mismo cuerpo de solicitud.
• Reutilizar la misma clave con la misma solicitud devuelve el pago existente, en vez de crear otro pago.
• Reutilizar la misma clave con una solicitud diferente responde con conflicto (409).
• Confío recuerda las claves por 30 días.