# Introducción

En este artículo te proporcionamos una visión detallada de los estados de las entidades y sus transiciones dentro del producto de pagos por Débito Directo de Belvo. Cada entidad informa su estado actual en el campo `status`.

## Métodos de pago

Un **método de pago** es la cuenta bancaria (CLABE) o tarjeta de débito que Belvo debita para solicitudes de pago. Su estado inicial depende de tu configuración de pago: `pending_validation` cuando la validación de centavos está habilitada, y `active` de lo contrario.


```mermaid
stateDiagram-v2
    direction LR
    classDef pending fill:#ADD8E6,color:#000,stroke:none
    classDef success fill:#2E8B57,color:#fff,stroke:none
    classDef cancelled fill:#FFA500,color:#fff,stroke:none
    classDef failed fill:#CC3300,color:#fff,stroke:none

    pending_validation --> active
    pending_validation --> error
    pending_validation --> canceled
    active --> error
    active --> inactive
    active --> canceled

    class pending_validation pending
    class active success
    class inactive,canceled cancelled
    class error failed
```

| Estado  | Descripción | Transiciones a  | Disparador/Evento |
|  --- | --- | --- | --- |
| `pending_validation` | La validación de centavos está en progreso. Belvo envió un centavo a través de SPEI a la cuenta y compara los datos del propietario en el CEP (*Comprobante Electrónico de Pago*) con el `documentType` y `documentNumber` del cliente. Para más información, consulta Validación de centavos. | - `active`
- `error`
- `canceled`

 | - La información del propietario en el CEP coincide con el cliente
- La información del propietario en el CEP no coincide con el cliente, o Belvo no puede enviar el centavo (`failedReason`: `account_validation_failed`)
- Belvo cancela el método de pago

 |
| `active` | El método de pago está confirmado y puedes usarlo en solicitudes de pago. Recibes el webhook `payment_method_registration_successful`. | - `error`
- `inactive`
- `canceled`

 | - La institución financiera devuelve una respuesta de débito que invalida la cuenta (por ejemplo, la cuenta está cerrada). Para los códigos que tienen este efecto, consulta Errores bancarios.
- Realizas una llamada Desactivar un método de pago. Esto solo es posible cuando ninguna solicitud de pago para el método de pago está `processing`.
- Belvo cancela el método de pago

 |
| `error` | La validación de centavos no fue exitosa, o la institución financiera invalidó la cuenta. Los campos `failedReason` y `failedMessage` describen la causa. No puedes usar el método de pago, y sus solicitudes de pago `initial` cambian a `canceled`. Recibes el webhook `payment_method_registration_failed`. | (Estado final - sin transiciones adicionales) | Ninguno |
| `inactive` | Desactivaste el método de pago. No puedes usarlo en nuevas solicitudes de pago. Belvo no envía un webhook para este estado. | (Estado final - sin transiciones adicionales) | Ninguno |
| `canceled` | Belvo canceló el método de pago. No puedes usarlo, y sus solicitudes de pago `initial` cambian a `failed` (`failedReason`: `CANCELED`). Recibes el webhook `payment_method_registration_canceled`. | (Estado final - sin transiciones adicionales) | Ninguno |


## Solicitudes de pago

Una **solicitud de pago** es un único débito contra un método de pago `activo`. Los tiempos de procesamiento siguen el horario de la Ciudad de México (GMT-6):

- **Creada antes de las 15:00:** Belvo debita los fondos antes de las 20:00 del mismo día y actualiza la solicitud de pago a `successful` o `failed` antes de las 12:00 del siguiente día hábil.
- **Creada después de las 15:00:** Belvo debita los fondos antes de las 20:00 del siguiente día hábil y actualiza la solicitud de pago a `successful` o `failed` antes de las 12:00 del día hábil posterior.


Para más información, consulta ¿Cuánto tiempo tardan los pagos en procesarse?.


```mermaid
stateDiagram-v2
    direction LR
    classDef pending fill:#ADD8E6,color:#000,stroke:none
    classDef success fill:#2E8B57,color:#fff,stroke:none
    classDef cancelled fill:#FFA500,color:#fff,stroke:none
    classDef failed fill:#CC3300,color:#fff,stroke:none

    initial --> processing
    processing --> successful
    successful --> chargeback
    processing --> failed
    initial --> canceled
    initial --> failed

    class initial,processing pending
    class successful success
    class canceled cancelled
    class failed,chargeback failed
```

| Estado  | Descripción | Transiciones a  | Disparador/Evento |
|  --- | --- | --- | --- |
| `initial` | La solicitud de pago fue creada. | - `processing`
- `canceled`
- `failed`

 | - Belvo genera los archivos de cobro y los envía a la institución financiera
- Cancelas la solicitud de pago, falla en las verificaciones de validación de Belvo, o su método de pago cambia a `error`
- Belvo cancela el método de pago (`failedReason`: `CANCELED`)

 |
| `processing` | Belvo envió los archivos de cobro y está esperando una respuesta de la institución financiera. | - `successful`
- `failed`

 | - La institución financiera confirma el débito
- La institución financiera reporta un error

 |
| `successful` | La institución financiera confirmó la solicitud de pago y los fondos fueron transferidos. Recibes el webhook `payment_request_successful`. | - `chargeback`

 | - El cliente disputa el débito con su institución financiera. Bajo la CIRCULAR 23/2009 del Banco de México, el cliente tiene hasta 90 días naturales desde la fecha de la transacción para disputarlo.

 |
| `failed` | La institución financiera reportó un error, o Belvo canceló el método de pago antes de procesarlo. No se transfirieron fondos. Los campos `failedReason` y `failedMessage` describen la causa. Recibes el webhook `payment_request_failed`. Para la lista de razones, consulta Errores bancarios. | (Estado final - no hay más transiciones) | Ninguno |
| `canceled` | La solicitud de pago fue cancelada antes de llegar a `processing`. Esto ocurre cuando realizas una llamada Cancelar una solicitud de pago (`failedReason`: `canceled_by_merchant`), cuando la solicitud de pago falla en las verificaciones de validación de Belvo, cuando su método de pago cambia a `error` (la solicitud de pago toma el `failedReason` del método de pago), o cuando Belvo la cancela. Los campos `failedReason` y `failedMessage` describen la causa. Recibes el webhook `payment_request_canceled`. | (Estado final - no hay más transiciones) | Ninguno |
| `chargeback` | La institución financiera revirtió una solicitud de pago `successful`. Los campos `chargebackDate` y `bankChargebackDate` registran cuándo ocurrió. Recibes el webhook `payment_request_chargeback`. Para más información, consulta Reversiones. | (Estado final - no hay más transiciones) | Ninguno |


## Consentimientos

Un **consentimiento** es la autorización documentada del cliente para debitar un método de pago. Un consentimiento debe estar `confirmado` antes de que puedas realizar solicitudes de pago. Belvo revisa los documentos enviados en 1–2 días hábiles.


```mermaid
stateDiagram-v2
    direction LR
    classDef pending fill:#ADD8E6,color:#000,stroke:none
    classDef success fill:#2E8B57,color:#fff,stroke:none
    classDef failed fill:#CC3300,color:#fff,stroke:none

    awaiting_information --> submitted
    submitted --> confirmed
    submitted --> incomplete_information
    incomplete_information --> submitted
    submitted --> rejected
    confirmed --> received_chargeback

    class awaiting_information,submitted,incomplete_information pending
    class confirmed success
    class rejected,received_chargeback failed
```

| Estado  | Descripción | Transiciones a  | Disparador/Evento |
|  --- | --- | --- | --- |
| `awaiting_information` | El consentimiento fue creado. Debes cargar los archivos requeridos: `id_front`, `id_back`, `selfie`, y `contract`, o `passport`, `selfie`, y `contract` para un pasaporte mexicano. | - `submitted`

 | - Todos los archivos requeridos están cargados

 |
| `submitted` | Todos los archivos requeridos están cargados y Belvo los está revisando. | - `confirmed`
- `incomplete_information`
- `rejected`

 | - Belvo aprueba los documentos
- Falta uno o más archivos o son inválidos
- Belvo no aprueba los documentos

 |
| `incomplete_information` | Falta uno o más archivos o son inválidos. | - `submitted`

 | - Cargas los archivos faltantes o corregidos

 |
| `confirmed` | Belvo aceptó los documentos. El consentimiento está activo y puedes realizar solicitudes de pago. | - `received_chargeback`

 | - El cliente reclama un contracargo en una solicitud de pago

 |
| `rejected` | Belvo rechazó los documentos enviados y el consentimiento no fue otorgado. | (Estado final - no hay más transiciones) | Ninguno |
| `received_chargeback` | El cliente recibió un contracargo después de que el consentimiento fue `confirmado`. | (Estado final - no hay más transiciones) | Ninguno |