# Introdução

Neste artigo, fornecemos uma visão detalhada dos estados das entidades e suas transições dentro do produto de pagamentos por Débito Direto da Belvo. Cada entidade reporta seu estado atual no campo `status`.

## Métodos de pagamento

Um **método de pagamento** é a conta bancária (CLABE) ou cartão de débito que a Belvo debita para solicitações de pagamento. Seu estado inicial depende da sua configuração de pagamento: `pending_validation` quando a validação de centavo está habilitada, e `active` caso contrário.


```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  | Descrição | Transições Para  | Acionador/Evento |
|  --- | --- | --- | --- |
| `pending_validation` | A validação de centavo está em andamento. A Belvo enviou um centavo através do SPEI para a conta e compara os dados do proprietário no CEP (*Comprobante Electrónico de Pago*) com o `documentType` e `documentNumber` do cliente. Para mais informações, veja Validação de centavo. | - `active`
- `error`
- `canceled`

 | - As informações do proprietário no CEP correspondem ao cliente
- As informações do proprietário no CEP não correspondem ao cliente, ou a Belvo não pode enviar o centavo (`failedReason`: `account_validation_failed`)
- A Belvo cancela o método de pagamento

 |
| `active` | O método de pagamento está confirmado e você pode usá-lo em solicitações de pagamento. Você recebe o webhook `payment_method_registration_successful`. | - `error`
- `inactive`
- `canceled`

 | - A instituição financeira retorna uma resposta de débito que invalida a conta (por exemplo, a conta está encerrada). Para os códigos que têm esse efeito, veja Erros bancários.
- Você faz uma chamada para Desativar um método de pagamento. Isso só é possível quando nenhuma solicitação de pagamento para o método de pagamento está `processing`.
- A Belvo cancela o método de pagamento

 |
| `error` | A validação de centavo não foi bem-sucedida, ou a instituição financeira invalidou a conta. Os campos `failedReason` e `failedMessage` descrevem a causa. Você não pode usar o método de pagamento, e suas solicitações de pagamento `initial` mudam para `canceled`. Você recebe o webhook `payment_method_registration_failed`. | (Estado final - sem transições adicionais) | Nenhum |
| `inactive` | Você desativou o método de pagamento. Você não pode usá-lo em novas solicitações de pagamento. A Belvo não envia um webhook para este estado. | (Estado final - sem transições adicionais) | Nenhum |
| `canceled` | A Belvo cancelou o método de pagamento. Você não pode usá-lo, e suas solicitações de pagamento `initial` mudam para `failed` (`failedReason`: `CANCELED`). Você recebe o webhook `payment_method_registration_canceled`. | (Estado final - sem transições adicionais) | Nenhum |


## Solicitações de pagamento

Uma **solicitação de pagamento** é um único débito contra um método de pagamento `ativo`. Os prazos de processamento seguem o horário da Cidade do México (GMT-6):

- **Criada antes das 15:00:** A Belvo debita os fundos até as 20:00 do mesmo dia e atualiza a solicitação de pagamento para `successful` ou `failed` até as 12:00 do próximo dia útil.
- **Criada após as 15:00:** A Belvo debita os fundos até as 20:00 do próximo dia útil e atualiza a solicitação de pagamento para `successful` ou `failed` até as 12:00 do dia útil seguinte.


Para mais informações, veja Quanto tempo os pagamentos levam para serem processados?.


```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  | Descrição | Transições Para  | Disparo/Evento |
|  --- | --- | --- | --- |
| `initial` | A solicitação de pagamento foi criada. | - `processing`
- `canceled`
- `failed`

 | - A Belvo gera os arquivos de cobrança e os envia para a instituição financeira
- Você cancela a solicitação de pagamento, ela falha nas verificações de validação da Belvo, ou seu método de pagamento muda para `error`
- A Belvo cancela o método de pagamento (`failedReason`: `CANCELED`)

 |
| `processing` | A Belvo enviou os arquivos de cobrança e está aguardando uma resposta da instituição financeira. | - `successful`
- `failed`

 | - A instituição financeira confirma o débito
- A instituição financeira relata um erro

 |
| `successful` | A instituição financeira confirmou a solicitação de pagamento e os fundos foram transferidos. Você recebe o webhook `payment_request_successful`. | - `chargeback`

 | - O cliente contesta o débito com sua instituição financeira. Sob a CIRCULAR 23/2009 do Banco de México, o cliente tem até 90 dias corridos a partir da data da transação para contestá-la.

 |
| `failed` | A instituição financeira relatou um erro, ou a Belvo cancelou o método de pagamento antes do processamento. Nenhum fundo foi transferido. Os campos `failedReason` e `failedMessage` descrevem a causa. Você recebe o webhook `payment_request_failed`. Para a lista de razões, veja Erros bancários. | (Estado final - sem transições adicionais) | Nenhum |
| `canceled` | A solicitação de pagamento foi cancelada antes de chegar a `processing`. Isso acontece quando você faz uma chamada Cancelar uma solicitação de pagamento (`failedReason`: `canceled_by_merchant`), quando a solicitação de pagamento falha nas verificações de validação da Belvo, quando seu método de pagamento muda para `error` (a solicitação de pagamento assume o `failedReason` do método de pagamento), ou quando a Belvo a cancela. Os campos `failedReason` e `failedMessage` descrevem a causa. Você recebe o webhook `payment_request_canceled`. | (Estado final - sem transições adicionais) | Nenhum |
| `chargeback` | A instituição financeira reverteu uma solicitação de pagamento `successful`. Os campos `chargebackDate` e `bankChargebackDate` registram quando isso aconteceu. Você recebe o webhook `payment_request_chargeback`. Para mais informações, veja Chargebacks. | (Estado final - sem transições adicionais) | Nenhum |


## Consentimentos

Um **consentimento** é a autorização documentada do cliente para debitar um método de pagamento. Um consentimento deve ser `confirmado` antes que você possa fazer solicitações de pagamento. A Belvo revisa os documentos enviados em 1–2 dias úteis.


```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  | Descrição | Transições Para  | Acionador/Evento |
|  --- | --- | --- | --- |
| `awaiting_information` | O consentimento foi criado. Você deve enviar os arquivos necessários: `id_front`, `id_back`, `selfie` e `contract`, ou `passport`, `selfie` e `contract` para um passaporte mexicano. | - `submitted`

 | - Todos os arquivos necessários são enviados

 |
| `submitted` | Todos os arquivos necessários foram enviados e a Belvo está revisando-os. | - `confirmed`
- `incomplete_information`
- `rejected`

 | - A Belvo aprova os documentos
- Um ou mais arquivos estão faltando ou são inválidos
- A Belvo não aprova os documentos

 |
| `incomplete_information` | Um ou mais arquivos estão faltando ou são inválidos. | - `submitted`

 | - Você envia os arquivos faltantes ou corrigidos

 |
| `confirmed` | A Belvo aceitou os documentos. O consentimento está ativo e você pode fazer solicitações de pagamento. | - `received_chargeback`

 | - O cliente solicita um chargeback em uma solicitação de pagamento

 |
| `rejected` | A Belvo rejeitou os documentos enviados e o consentimento não foi concedido. | (Estado final - sem transições adicionais) | Nenhum |
| `received_chargeback` | O cliente recebeu um chargeback após o consentimento ter sido `confirmado`. | (Estado final - sem transições adicionais) | Nenhum |