# Fase 2: Creación de Pagos (API Directa)

Beta
Smart Collections está actualmente en Beta. Algunos contratos en esta página aún están siendo confirmados con nuestro equipo de ingeniería, por lo que deben considerarse provisionales y se esperan refinamientos antes de la disponibilidad general, incluyendo:

- Cargas útiles de webhook y códigos de eventos
- Actualizaciones de referencia de la API para los endpoints de Collection Instructions, Payment Authorization y Charge
- Nombres de campos y mejoras en la documentación (terminología, diagramas)


Contacta a tu gerente de cuenta de Belvo para unirte al programa Beta.

En la Fase 2 de Smart Collections, recolectas los fondos con **Smart Transfers**, el producto de Pagos de Belvo para mover dinero entre cuentas del mismo usuario. Creas una **Autorización de Pago** de Smart Transfers una vez, y luego activas un **Cargo** cada vez que la Fase 1 te indica que hay suficientes fondos.

La integración completa paso a paso, con cada campo, respuesta y estado, se encuentra en la guía API Directa (Smart Transfers). Esta página solo cubre lo específico de usar Smart Transfers junto con Fase 1: Verificación de Saldo.


```mermaid
sequenceDiagram
    participant Client as Your application
    participant Aggregation as Belvo Aggregation API
    participant Payments as Belvo Payments API

    Client->>Payments: POST /payments/br/payment-authorizations/
    Note over Client, Payments: Your user approves it at their bank
    Payments->>Client: Webhook: PAYMENT_AUTHORIZATION
    Client->>Payments: GET /payments/br/payment-authorizations/{id}/
    Payments-->>Client: 200 OK (status: AUTHORIZED)

    Aggregation->>Client: Webhook: item_ready_to_charge (data.amount)
    Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/
    Payments-->>Client: 201 Created
    Payments->>Client: Webhook: CHARGE
    Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/
    Payments-->>Client: 200 OK (status: SETTLED or FAILED)
```

## 1. Crear la Autorización de Pago anticipadamente

Crea la Autorización de Pago de Smart Transfers **en paralelo** con tu Instrucción de Cobro de la Fase 1, para que ya esté `AUTHORIZED` cuando llegue `item_ready_to_charge`. Sigue Crear una Autorización de Pago, y ten en cuenta estos puntos:

- **Una autorización, muchos Cargos.** Crea una autorización por usuario y reutilízala para cada Cargo. Dimensiona `total_allowed_amount`, `payment_transaction_limit` y `periodic_limits` para cubrir los ítems que esperas cobrar.
- **El beneficiario debe ser el usuario.** Smart Transfers solo mueve fondos entre cuentas que pertenecen a la misma persona (mismo CPF) o empresa (misma raíz de CNPJ).
- **Usa el mismo banco que el Link.** Establece `payer.institution` a la institución de pagos que coincide con el banco del Link que monitoreas en la Fase 1. Belvo no puede verificar esto por ti, porque la autorización no hace referencia al Link.


### Cargar la cuenta que monitoreas

En la Fase 1, Belvo verifica el saldo de **cada** cuenta que el usuario compartió en su consentimiento de datos y envía `item_ready_to_charge` tan pronto como **cualquiera** de ellas tenga fondos suficientes. El webhook no indica cuál fue la cuenta.

Para asegurarte de que los Cargos debiten la cuenta que monitoreas, crea la autorización con los detalles de esa cuenta en `payer.account_details` (`account_type`, `ispb`, `issuer`, `number`). Puedes tomar `issuer` y `number` de la `agency` y `number` de la cuenta en Banking Aggregation. Consulta Debitar una cuenta específica. De lo contrario, tu usuario elige la cuenta en su banco, y puede que no sea la que se verificó el saldo.

## 2. Cobrar cuando llegue `item_ready_to_charge`

Cuando recibas `item_ready_to_charge`, verifica que la autorización esté `AUTHORIZED`, y luego crea un Cargo contra ella:

- Establece `amount` al `data.amount` del webhook.
- Establece `date` a hoy, para que los fondos se recojan mientras estén disponibles.
- Establece `external_id` a un UUID que almacenes junto al ítem. Belvo no vincula Instrucciones de Cobro, autorizaciones y Cargos entre sí, y el `external_id` de un Cargo debe ser un UUID, por lo que el propio `external_id` del ítem solo puede reutilizarse si también es un UUID.


La Fase 1 es opcional
No necesitas una Instrucción de Cobro para realizar un cargo. Con una Autorización de Pago `AUTHORIZED` puedes crear un Cargo en cualquier momento. La Fase 1 solo es necesaria cuando deseas que Belvo te informe cuando la cuenta tenga suficientes fondos.

## 3. Sigue el Cargo

Belvo envía un webhook `CHARGE` cada vez que cambia el estado del Cargo. Obtén el Cargo para leerlo: `SETTLED` significa que los fondos salieron de la cuenta del usuario; `FAILED` significa que no lo hicieron, y `status_reason_code` te indica por qué (por ejemplo, `INSUFFICIENT_FUNDS` si el saldo disminuyó después de que la Fase 1 lo verificó).

Un Cargo fallido no reinicia la Fase 1
Una vez que un ítem alcanza `item_ready_to_charge`, Belvo deja de monitorearlo, incluso si el Cargo que creas posteriormente falla. Para intentarlo de nuevo, crea una **nueva** Instrucción de Cobro por esa cantidad. Reutilizar el mismo `external_id` del ítem está bien.

## Mejores prácticas

**Correlaciona todo con tus propios IDs.** Almacena el `id` del ítem, el `id` de la autorización y el `id` del Cargo (y tus `external_id`s) juntos, para que puedas reconstruir qué ítem liquidó cada Cargo.

**Devuelve `2XX` rápidamente desde tus endpoints de webhook.** Procesa la lógica de negocio de manera asíncrona para no agotar el tiempo de espera y evitar reintentos.

**Conciliar ítems que nunca producen un Cargo.** La Fase 1 no envía un webhook cuando las ventanas de un ítem terminan sin fondos suficientes. Haz un seguimiento de tus ítems y da seguimiento a aquellos que se queden obsoletos. Puedes verificar el estado de cada ítem para ver cómo terminó.

**Evita Cargos duplicados.** Smart Transfers aún no soporta claves de idempotencia. Si una solicitud de Cargo agota el tiempo de espera, lista los Cargos de la autorización y busca tu `external_id` antes de reintentar.