# API Directa (Transferencias Inteligentes)

No hay entorno Sandbox
Smart Transfers no está disponible en Sandbox en este momento. Para probar tu integración, utiliza Producción con cuentas reales.

Con las Transferencias Inteligentes, tu usuario aprueba una Autorización de Pago una vez en su banco, y luego puedes activar transferencias Pix a otra cuenta que posean, cuando lo necesites, dentro de los límites que aprobaron. En esta guía, te mostraremos:

- el flujo general de datos
- cómo crear una Autorización de Pago y sus límites
- cómo activar un Cargo contra una Autorización de Pago autorizada
- cómo seguir las autorizaciones y Cargos con webhooks
- cómo cancelar un Cargo programado o una autorización, y cómo cambiar la cuenta beneficiaria


Requisitos previos
Por favor, asegúrate de haber completado todos los pasos en nuestro artículo dedicado a los requisitos previos antes de continuar con esta guía.

Encabezado de versión requerido
Cada solicitud en esta guía debe incluir el encabezado `X-Belvo-API-Resource-Version: Payments-BR.V2`. Sin él, Belvo responde con `404 - Not Found`.

## Descripción general del flujo de datos

Como puedes ver en el diagrama a continuación, el flujo involucra:

1. Crear una Autorización de Pago y redirigir a tu usuario a su banco para aprobarla.
2. Esperar a que la autorización se convierta en `AUTHORIZED`.
3. Crear un Cargo cada vez que quieras mover fondos.
4. Seguir cada Cargo hasta que esté `SETTLED` (o `FAILED`).



```mermaid
sequenceDiagram
    autonumber
    participant App as Your application
    participant Belvo as Belvo
    participant Bank as User's bank

    App->>Belvo: POST /payments/br/payment-authorizations/
    Belvo-->>App: 201 - Created (authorization_url)
    App->>Bank: Redirect the user to authorization_url
    Note over Bank: The user reviews and approves the limits
    Bank-->>App: User returns to your return_url
    Belvo-->>App: WEBHOOK PAYMENT_AUTHORIZATION
    App->>Belvo: GET /payments/br/payment-authorizations/{id}/
    Belvo-->>App: 200 - OK (status: AUTHORIZED)

    rect rgba(0, 100, 255, .05)
        Note over App,Bank: Repeat whenever you need to move funds
        App->>Belvo: POST /payments/br/payment-authorizations/{id}/charges/
        Belvo->>Bank: Pix transfer request
        Belvo-->>App: 201 - Created
        Belvo-->>App: WEBHOOK CHARGE
        App->>Belvo: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/
        Belvo-->>App: 200 - OK (status: SETTLED)
    end
```

## Crear una Autorización de Pago

La Autorización de Pago es el consentimiento que tu usuario otorga en su banco. Define la cuenta que recibe los fondos y los límites que cada Cargo debe respetar.

Puedes crear la Autorización de Pago de dos maneras:

- **Con un cliente y cuenta bancaria existentes:** envía el `id` de un cliente y de una cuenta bancaria que ya hayas creado en Belvo, en `payer.customer` y `beneficiary.target`.
- **Con un nuevo cliente y cuenta bancaria:** envía sus detalles en la misma solicitud: `payer.customer` con el `identifier` y `name` del pagador, y `beneficiary.target` con el `holder` y `details` de la cuenta. Belvo crea el cliente y la cuenta bancaria junto con la Autorización de Pago.


Para crear una, realiza una solicitud POST Crear una Autorización de Pago:

Con cliente y cuenta bancaria existentes

```shell Crear una Autorización de Pago
curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'Content-Type: application/json' \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \
  --data '{
    "payment_method": "PIX_OF_SMART_TRANSFERS",
    "description": "Recarga de tu cuenta Acme",
    "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
    "return_url": "https://www.acmecorp.com/smart-transfers/return",
    "expiration_date_time": "2027-10-16T23:59:59Z",
    "payer": {
      "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6",
      "institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"
    },
    "beneficiary": {
      "type": "BANK_ACCOUNT",
      "target": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
    },
    "payment_method_configuration": {
      "total_allowed_amount": "5000.00",
      "payment_transaction_limit": "500.00",
      "periodic_limits": {
        "day": {
          "quantity_limit": 2,
          "transaction_limit": "500.00"
        },
        "month": {
          "transaction_limit": "2000.00"
        }
      },
      "start_date_time": "2026-10-16T14:30:00Z"
    },
    "metadata": {
      "internal_reference_id": "GGq73487w2"
    }
  }'
```

Con nuevo cliente y cuenta bancaria

```shell Crear una Autorización de Pago
curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'Content-Type: application/json' \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \
  --data '{
    "payment_method": "PIX_OF_SMART_TRANSFERS",
    "description": "Recarga de tu cuenta Acme",
    "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
    "return_url": "https://www.acmecorp.com/smart-transfers/return",
    "expiration_date_time": "2027-10-16T23:59:59Z",
    "payer": {
      "customer": {
        "identifier": "12345678909",
        "name": "Caetano Veloso"
      },
      "institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"
    },
    "beneficiary": {
      "type": "BANK_ACCOUNT",
      "target": {
        "holder": {
          "identifier": "12345678909",
          "name": "Caetano Veloso"
        },
        "details": {
          "account_type": "CHECKINGS",
          "agency": "0001",
          "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
          "number": "457220"
        }
      }
    },
    "payment_method_configuration": {
      "total_allowed_amount": "5000.00",
      "payment_transaction_limit": "500.00",
      "periodic_limits": {
        "day": {
          "quantity_limit": 2,
          "transaction_limit": "500.00"
        },
        "month": {
          "transaction_limit": "2000.00"
        }
      },
      "start_date_time": "2026-10-16T14:30:00Z"
    },
    "metadata": {
      "internal_reference_id": "GGq73487w2"
    }
  }'
```

El beneficiario debe ser la propia cuenta del pagador
Smart Transfers solo mueve dinero entre cuentas pertenecientes a la misma persona o empresa. Para un pagador individual, `beneficiary.target.holder.identifier` debe ser el CPF del pagador (`payer.customer.identifier`). Para un pagador empresarial, el CNPJ del beneficiario debe compartir la raíz del CNPJ del pagador (los primeros ocho dígitos).

Si envías un titular diferente, la autorización se crea con el estado `FAILED` y la solicitud devuelve un error. Si usas un `id` de cuenta bancaria existente como objetivo, asegúrate de que pertenezca al pagador.

| Parámetro | Requerido | Descripción |
|  --- | --- | --- |
| `payment_method` | true | Debe ser `PIX_OF_SMART_TRANSFERS`. |
| `description` | true | Una descripción para tu referencia interna. Mantenla en 128 caracteres o menos. |
| `external_id` | opcional (altamente recomendado) | Tu propio identificador para esta autorización, como un **UUID**. Belvo no impone unicidad, así que úsalo para correlacionar la autorización con tus registros, no para prevenir duplicados. |
| `return_url` | true | La URL a la que se envía a tu usuario después de aprobar (o rechazar) la autorización en su banco. En caso de fallo, Belvo añade los parámetros de consulta `error` y `error_description`. |
| `expiration_date_time` | opcional | Cuando la autorización deja de aceptar Cargos, en formato ISO 8601. Debe estar en el futuro y después de `start_date_time`. El consentimiento expira a las 23:59:59 UTC de esa fecha. Si lo omites, la autorización no expira en una fecha (aún puede ser consumida o revocada). |
| `payer.customer` | true | La persona o empresa que paga. Ya sea un `id` de cliente existente en Belvo, o un objeto con el `identifier` (CPF o CNPJ) y `name` del pagador. Si el cliente aún no existe, Belvo lo crea. |
| `payer.institution` | true | El `id` de Belvo del banco del pagador. Usa el endpoint Listar todas las instituciones de pago para obtenerlo. |
| `payer.account_details` | opcional | La cuenta específica a debitar. Si lo omites, el usuario elige la cuenta en su banco. Ver Debitar una cuenta específica abajo. |
| `beneficiary.type` | true | Debe ser `BANK_ACCOUNT`. |
| `beneficiary.target` | true | La cuenta que recibe los fondos. Ya sea un `id` de cuenta bancaria existente, o un objeto de cuenta bancaria con `holder` (`identifier`, `name`) y `details` (`account_type`: `CHECKINGS`, `SAVINGS`, o `PAYMENTS`; `agency`; `institution`; `number`). Debe ser propiedad del pagador (ver la advertencia arriba). |
| `payment_method_configuration` | true | Los límites para esta autorización. El objeto es requerido, pero cada campo dentro de él es opcional. Ver Límites de autorización abajo. |
| `metadata` | opcional | Hasta 50 pares clave-valor para tu propio uso. Claves de hasta 40 caracteres, valores de cadena de hasta 500 caracteres, sin anidamiento. |


### Debitar una cuenta específica

Por defecto, tu usuario elige desde cuál de sus cuentas pagar cuando aprueba la autorización en su banco. Si ya conoces la cuenta a debitar, por ejemplo, porque monitoreas su saldo con Banking Aggregation, envía sus detalles en `payer.account_details`. El usuario solo podrá aprobar la autorización para esa cuenta, y cada Cargo la debitará.


```json payer with account_details
"payer": {
  "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6",
  "institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
  "account_details": {
    "account_type": "CACC",
    "ispb": "12345678",
    "issuer": "6272",
    "number": "11188222"
  }
}
```

| Campo  | Descripción |
|  --- | --- |
| `account_type` | El tipo de cuenta: `CACC` (corriente), `SVGS` (ahorros), `SLRY` (nómina) o `TRAN` (cuenta de pago). |
| `ispb` | El código ISPB de 8 dígitos del banco del pagador. |
| `issuer` | El código de la sucursal (agencia) de la cuenta, hasta 4 dígitos. En Banking Aggregation, este es el `agency` de la cuenta. |
| `number` | El número de cuenta, hasta 20 dígitos. En Banking Aggregation, este es el `number` de la cuenta. |


Si envías `account_details`, incluye los cuatro campos. `payer.institution` sigue siendo requerido, y debe ser la institución de pagos del mismo banco que `ispb`.

### Límites de autorización

Los límites en `payment_method_configuration` son lo que tu usuario ve y aprueba en su banco, así que configúralos para cubrir las transferencias que esperas realizar, y no más.

| Campo | Descripción |
|  --- | --- |
| `total_allowed_amount` | El total máximo de todos los Cargos durante la vigencia de la autorización, como una cadena de texto (mínimo `0.01`). Cuando se agota, la autorización se convierte en `CONSUMED`. |
| `payment_transaction_limit` | El monto máximo de un solo Cargo, como una cadena de texto. No debe ser mayor que `total_allowed_amount`. |
| `periodic_limits` | Límites por ventana de calendario. Incluye cualquiera de `day`, `week`, `month` o `year`. Cada ventana que incluyas debe establecer **al menos uno** de `quantity_limit` (el número máximo de Cargos exitosos en esa ventana, mínimo `1`) y `transaction_limit` (el monto total máximo cargado en esa ventana, como una cadena de texto). Alcanzar el límite de una ventana solo bloquea los Cargos hasta que la ventana se reinicia; no consume la autorización. |
| `start_date_time` | Cuando la autorización comienza a aceptar Cargos, en formato ISO 8601. Puede ser inmediato, pero no en el pasado. Si lo omites, los Cargos pueden comenzar desde el día en que se crea la autorización. |


Quién verifica los límites
Cuando creas un Cargo, Belvo lo rechaza de inmediato si su monto supera `payment_transaction_limit` o `total_allowed_amount`. Los totales acumulados y los `periodic_limits` son aplicados por el banco del usuario, por lo que un Cargo que los infringe se crea y luego pasa a `FAILED` con un `status_reason_code` como `CHARGE_PERIOD_LIMIT_REACHED`.

La respuesta contiene el `id` de la autorización y el `authorization_url`:


```json Response: 201 - Created
{
  "id": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432", // [!code highlight]
  "created_at": "2026-10-16T14:30:02Z",
  "updated_at": "2026-10-16T14:30:02Z",
  "authorized_at": null,
  "status": "AWAITING_AUTHORIZATION",
  "status_reason_code": null,
  "status_reason_message": null,
  "status_updated_at": "2026-10-16T14:30:02Z",
  "payment_method": "PIX_OF_SMART_TRANSFERS",
  "description": "Recarga de tu cuenta Acme",
  "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
  "return_url": "https://www.acmecorp.com/smart-transfers/return",
  "expiration_date_time": "2027-10-16T23:59:59Z",
  "payer": {
    "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6",
    "institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
    "representative_identifier": null,
    "bank_account": null
  },
  "beneficiary": {
    "type": "BANK_ACCOUNT",
    "target": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
  },
  "payment_method_configuration": {
    "total_allowed_amount": "5000.00",
    "payment_transaction_limit": "500.00",
    "periodic_limits": {
      "day": {
        "quantity_limit": 2,
        "transaction_limit": "500.00"
      },
      "month": {
        "transaction_limit": "2000.00"
      }
    },
    "start_date_time": "2026-10-16T14:30:00Z",
    "authorization_url": "https://institution.example.com/authorize?client_id=..." // [!code highlight]
  },
  "charges": [],
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}
```

Asegúrate de guardar el `id`: lo necesitas para crear Cargos. Luego redirige a tu usuario a `payment_method_configuration.authorization_url`.

Expiración de la URL de autorización
Cada banco establece cuánto tiempo su `authorization_url` permanece válida, lo cual puede ser tan corto como unos pocos minutos y hasta alrededor de 60 minutos. Si expira antes de que tu usuario apruebe, crea una nueva Autorización de Pago. Una autorización no puede ser renovada.

## Espera a que se apruebe la autorización

Tu usuario aprueba (o rechaza) la autorización en su banco y luego es redirigido a tu `return_url`. Cada vez que cambia el estado de la autorización, Belvo envía un webhook `PAYMENT_AUTHORIZATION`. Los webhooks de la versión 2 no incluyen el estado, por lo que debes obtener la autorización para leerlo:


```json PAYMENT_AUTHORIZATION webhook
{
  "schema_version": "2.0.0",
  "resource": "PAYMENT_AUTHORIZATION", // [!code highlight]
  "resource_id": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432", // [!code highlight]
  "resource_version": "V2",
  "timestamp": "2026-10-16T14:33:10Z"
}
```


```shell Obtener la Autorización de Pago
curl --request GET 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2'
```

Una vez que el `status` es `AUTHORIZED`, puedes crear Cargos. `payer.bank_account` mostrará entonces la cuenta (enmascarada) que el usuario eligió para pagar. Si el estado es `FAILED`, revisa `status_reason_code`; por ejemplo, `USER_REJECTED` significa que tu usuario rechazó en su banco. Consulta la Referencia de estados para cada estado.

## Crear un Cargo

Cada Cargo mueve un monto de la cuenta del pagador a la cuenta del beneficiario en la autorización. Realiza una solicitud POST Crear un Cargo al endpoint de Cargos de la autorización:


```shell Create a charge
curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/charges/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'Content-Type: application/json' \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \
  --data '{
    "amount": "150.50",
    "date": "2026-10-16",
    "statement_description": "Acme top-up",
    "external_id": "5f0b8f3e-3c1a-4a7e-9d61-1d2b7a1e9c42",
    "metadata": {
      "internal_reference_id": "GGq73487w2"
    }
  }'
```

| Parámetro | Requerido | Descripción |
|  --- | --- | --- |
| `amount` | true | El monto a transferir, como una cadena con dos decimales (mínimo `0.01`). No debe ser mayor que el `payment_transaction_limit` o `total_allowed_amount` de la autorización. |
| `date` | true | La fecha en que debe realizarse la transferencia, en formato `YYYY-MM-DD`. Puede ser hoy. Debe ser en o después de la fecha `start_date_time` de la autorización (o su fecha de creación, si no estableciste una), comparada en UTC: tarde en la noche en Brasilia, "hoy" ya puede ser mañana en UTC. Una fecha futura crea un Cargo `SCHEDULED`. |
| `statement_description` | true | La descripción que se muestra en el estado de cuenta bancario de tu usuario (1 a 140 caracteres). |
| `external_id` | opcional (altamente recomendado) | Tu propio identificador para este Cargo, como un **UUID**. Belvo no impone unicidad. |
| `metadata` | opcional | Pares clave-valor para tu propio uso, con las mismas reglas que en la autorización. |


Los Cargos siempre pagan al beneficiario de la autorización
No puedes enviar un beneficiario diferente en un Cargo. Cada Cargo paga a la cuenta establecida en la Autorización de Pago.


```json Response: 201 - Created
{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", // [!code highlight]
  "created_at": "2026-10-16T15:00:01Z",
  "status": "PENDING",
  "status_reason_code": null,
  "status_reason_message": null,
  "status_updated_at": "2026-10-16T15:00:01Z",
  "payment_authorization": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432",
  "payment_method": "PIX_OF_SMART_TRANSFERS",
  "amount": "150.50",
  "date": "2026-10-16",
  "statement_description": "Acme top-up",
  "end_to_end_id": "E12345678202610161500abcDEF12345",
  "beneficiary": {
    "bank_account": {
      "id": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "details": {
        "account_type": "CHECKINGS",
        "agency": "0001",
        "code": "260",
        "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
        "number": "**7220"
      },
      "holder": {
        "identifier": "12345678909",
        "name": "Caetano Veloso"
      }
    }
  },
  "payer": {},
  "external_id": "5f0b8f3e-3c1a-4a7e-9d61-1d2b7a1e9c42",
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  },
  "previous": null,
  "next": null
}
```

Asegúrate de guardar el `id` del Cargo. El `end_to_end_id` es el identificador de extremo a extremo de Pix para la transferencia; úsalo para conciliar el pago. `payer` permanece vacío hasta que el banco devuelve la cuenta debitada.

Un 201 no significa que el Cargo fue exitoso
Si el banco rechaza el Cargo inmediatamente, Belvo aún responde con `201 - Created`, pero el `status` del Cargo ya es `FAILED`, y **no se envía un webhook** para esa transición. Siempre verifica el `status` en la respuesta antes de esperar un webhook.

## Escuchar los webhooks de Charge

Belvo envía un webhook `CHARGE` cada vez que cambia el estado de un Charge. Al igual que con la autorización, obtén el Charge para leer su estado:


```json CHARGE webhook
{
  "schema_version": "2.0.0",
  "resource": "CHARGE", // [!code highlight]
  "resource_id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", // [!code highlight]
  "resource_version": "V2",
  "timestamp": "2026-10-16T15:00:07Z"
}
```


```shell Obtener el charge
curl --request GET 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2'
```

Un Charge es exitoso cuando su `status` es `SETTLED`. Para el formato del webhook, la entrega y la política de reintentos, consulta Webhooks de Pagos (Brasil).

Lo que confirma SETTLED
`SETTLED` confirma que los fondos **salieron de la cuenta del pagador**. Belvo trabaja con el banco del pagador a través de Open Finance, por lo que no ve el lado del beneficiario. Confirma el crédito en la cuenta receptora por tu cuenta.

¡Hecho!
Has creado una Autorización de Pago, esperado a que tu usuario la apruebe y movido fondos con un Charge. Crea más Charges contra la misma autorización siempre que lo necesites, dentro de sus límites.

## Cancelar un Cargo o una autorización

| Acción | Endpoint | Cuándo está permitido |
|  --- | --- | --- |
| Cancelar un Cargo programado | `POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/` | El Cargo está `PENDING` o `SCHEDULED`, su `date` es posterior a hoy (hora de Brasilia, límite 23:59), y la autorización está `AUTHORIZED`. El Cargo se convierte en `CANCELED`. |
| Cancelar la autorización | `POST /payments/br/payment-authorizations/{payment_authorization_id}/cancel/` | La autorización está `AUTHORIZED`. Se convierte en `REVOKED`, y no se pueden crear más Cargos. |


Ambos devuelven `204 - No Content`. El cambio de estado ocurre de manera asincrónica, y recibes un webhook cuando sucede. No puedes reintentar un Cargo de Smart Transfers fallido: crea un nuevo Cargo en su lugar.

## Cambiar la cuenta beneficiaria

Mientras una Autorización de Pago está `AUTHORIZED`, puedes cambiar la cuenta que recibe los fondos a otra cuenta bancaria que ya hayas registrado, sin pedirle a tu usuario que apruebe una nueva autorización. Realiza una solicitud PATCH Cambiar el beneficiario de una Autorización de Pago:


```shell Cambiar la cuenta beneficiaria
curl --request PATCH 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'Content-Type: application/json' \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \
  --data '{
    "beneficiary": {
      "type": "BANK_ACCOUNT",
      "target": "b6278377-f710-4d1a-a026-7bab757256d0"
    }
  }'
```

`target` debe ser el `id` de una cuenta bancaria existente perteneciente a la **misma persona o empresa** que el beneficiario actual. Belvo responde con `200 - OK` y la Autorización de Pago actualizada, y los Cargos posteriores se pagan a la nueva cuenta. Si la autorización no está `AUTHORIZED`, Belvo responde con `400 - Bad Request`.

## Referencia de estados

### Autorización de Pago

| Estado  | Significado |
|  --- | --- |
| `AWAITING_AUTHORIZATION` | Creado. Esperando que el usuario lo apruebe en su banco. |
| `PARTIALLY_ACCEPTED` | Esperando más aprobaciones en el banco (por ejemplo, una cuenta empresarial que necesita varias firmas). |
| `AUTHORIZED` | Aprobado. Puedes crear Cargos. |
| `FAILED` | No aprobado, o no se pudo crear. Consulta `status_reason_code`. |
| `CONSUMED` | El `total_allowed_amount` se agotó, o la autorización expiró. No se pueden crear más Cargos. (Alcanzar un límite de `periodic_limits` no consume la autorización.) |
| `REVOKED` | Cancelado por ti, el usuario, o el banco. No se pueden crear más Cargos. |


### Cargo

| Estado  | Significado |
|  --- | --- |
| `PENDING` | Creado y en proceso. |
| `SCHEDULED` | Aceptado por el banco para una `date` futura. |
| `SETTLED` | Los fondos salieron de la cuenta del pagador. Final. |
| `FAILED` | La transferencia no se realizó. Ver `status_reason_code`. Final. |
| `CANCELED` | Cancelaste el Cargo antes de su fecha. Final. |


Para la lista completa de valores de `status_reason_code`, consulta Códigos y Mensajes de Pagos Brasil.

## Errores y casos límite

| Situación | Qué sucede |
|  --- | --- |
| Falta el encabezado `X-Belvo-API-Resource-Version`, o Smart Transfers no está habilitado para tu organización. | `404 - Not Found`. |
| Cuerpo de solicitud inválido. | `400 - Bad Request` con una lista de errores `{field, code, message, request_id}`. |
| El banco o la red de Open Finance rechaza la autorización durante la creación (por ejemplo, el beneficiario no es titular del pagador). | La autorización se guarda como `FAILED`, y la solicitud actualmente devuelve `500 - Internal Server Error` con una lista de errores `{code, message}`, sin el `id` de la autorización. Para encontrarlo, lista las autorizaciones del cliente (`GET /payments/br/payment-authorizations/?customer={customer_id}`). |
| Creas un Cargo en una autorización que no está `AUTHORIZED`. | `400 - Bad Request`: `Payment Authorization is not AUTHORIZED.` |
| El banco rechaza un Cargo inmediatamente. | `201 - Created` con `status: FAILED`, y sin webhook. |


Aún no hay idempotencia
Estos endpoints aún no soportan claves de idempotencia, y `external_id` no previene duplicados. Si una solicitud se agota, busca los Cargos de la autorización (`GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/`) y verifica tu `external_id` antes de reintentar, para no transferir dos veces.