> ## Documentation Index
> Fetch the complete documentation index at: https://developers.confiopagos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crea un pago en Confío

> Guía paso a paso para crear pagos mediante la API de Confío

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

```mermaid theme={null}
sequenceDiagram
    participant TuPlataforma as "Tu Plataforma"
    participant Confio as "Confío"
    participant Comprador

    TuPlataforma->>Confio: POST /v1/stores/{store}/payments
    Confio-->>TuPlataforma: 201 Pago creado (name, url, status)
    TuPlataforma->>Comprador: Comparte URL del pago
    Comprador->>Confio: Abre checkout y paga
    Confio-->>TuPlataforma: Webhooks (paymentAttempt.statusChanged, payment.statusChanged)
```

## Requisitos previos

* Un token de acceso válido a la API de Confío
  <Note>
    Debes contactarnos para generar el token. Una vez generado, te recomendamos
    almacenarlo en un lugar seguro y no compartirlo
  </Note>
* 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.

```bash theme={null}
curl -X GET "https://api.confiopagos.com/v1/stores" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN"
```

Ejemplo de respuesta (parcial):

```json theme={null}
{
  "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)

```bash theme={null}
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"`

<Note>
  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**.
</Note>

### Respuesta 201 (ejemplo)

```json theme={null}
{
  "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:

| Campo       | Valor              |
| ----------- | ------------------ |
| Número      | `4018810000190011` |
| CVV         | `123`              |
| Vencimiento | `12/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

* [Referencia del endpoint](/api-reference/create-payment)
* [Listar tiendas](/api-reference/list-stores)
* [Webhooks](/cookbooks/webhooks)
* [Flujo logístico (actualizar estados)](/cookbooks/logistics)