# Introdução à Validação de Centavos

A validação de centavos é um método que a Belvo utiliza para confirmar que uma conta bancária existe e é de propriedade de um indivíduo ou entidade específica.


```mermaid
sequenceDiagram
    autonumber
    participant Client as Cliente
    participant Belvo as Belvo
    participant Provider as Provedor

    Client->>Belvo: Criar um cliente
    Belvo-->>Client: 201 - Cliente Criado
    Client->>Belvo: Criar um método de pagamento
    Belvo-->>Client: 201 - Método de Pagamento Criado
    Belvo->>Provider: Enviar "centavo" para a conta bancária registrada
    Provider-->>Belvo: CEP gerado
    rect rgba(0, 0, 0, .03)
        Note over Client,Provider: Belvo valida as informações no CEP contra as informações fornecidas ao criar o cliente
        Note over Client,Provider: Belvo atualiza o status do Método de Pagamento
    end
    Belvo-->>Client: Belvo envia o status do Método de Pagamento
```

O fluxo geral da validação de centavos da Belvo é:

1. Você cria um cliente e um método de pagamento.
2. A Belvo envia um "centavo" usando SPEI para a conta especificada quando você criou o método de pagamento.
3. Um Comprovante Eletrônico de Pagamento (CEP) é gerado para a transação e a Belvo recupera os dados do documento.
4. A Belvo compara as informações do proprietário do CEP com as informações que você forneceu ao criar o cliente para verificar a conta fornecida.


## Validação de centavo para Métodos de Pagamento (API)

1. Você cria um cliente.
2. Você cria um Método de Pagamento para o cliente.
3. O status do Método de Pagamento é definido como `pending_agreement_acceptance`.
4. Uma vez que o acordo é aceito, o status do Método de Pagamento é definido como `pending_validation`.
5. A Belvo envia o "centavo" para a conta registrada no Passo 2.
6. Um Comprovante Eletrônico de Pagamento (CEP) é gerado para a transação e a Belvo recupera os dados do documento.
7. A Belvo compara o `documentType` e `documentNumber` fornecidos no Passo 1 com as informações fornecidas no CEP.
  1. Se as informações forem as mesmas, o status do Método de Pagamento é definido como `active`. Você recebe o webhook `payment_method_registration_successful` com as seguintes informações:

```json Penny Validation Success
{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "active",
    "failedReason": null,
    "failedMessage": null,
    "cep": {
      "name": "Juan Perez",
      "document": "PELJ900101ABC",
      "url": "https://example.com/cep/3118128a-6792-4b06-bd61-4acf6f6ad6b5.pdf",
      "accountType": "savings",
      "bank": "mx_bancoppel",
      "accountNumber": "012345678901234567"
    }
  }
}
```
  2. Se as informações não forem as mesmas, o status do Método de Pagamento é definido como `error`. Você recebe o webhook `payment_method_registration_failed` com as seguintes informações de falha:

```json Penny Validation Error
{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "error",
    "failedReason": "account_validation_failed",
    "failedMessage": "Account owner validation was not successful",
    "cep": {
      "name": "Juan Perez",
      "document": "PELJ900101ABC",
      "url": "https://example.com/cep/3118128a-6792-4b06-bd61-4acf6f6ad6b5.pdf",
      "accountType": "savings",
      "bank": "mx_bancoppel",
      "accountNumber": "012345678901234567"
    }
  }
}
```


Quando disponível, ambos os webhooks podem incluir um objeto `cep` opcional em `details`. Este objeto contém os dados do CEP que a Belvo recuperou durante a validação de centavo: `name` (nome do titular da conta), `document` (RFC do titular da conta), `url` (URL do documento CEP), `accountType` (tipo de conta beneficiária), `bank` (instituição contraparte) e `accountNumber` (número da conta beneficiária).

## Validação de centavos usando Importações em Lote

1. Você envia seu CSV para Importação em Lote de Pagamentos por Débito Direto.
2. Se necessário, a Belvo cria os clientes associados para cada linha do seu CSV.
3. A Belvo cria um Método de Pagamento para cada novo cliente (ou seja, para qualquer cliente que não tenha sido previamente registrado com as mesmas informações).
4. O status do Método de Pagamento é definido como `pending_validation`.
5. A Belvo envia o “centavo" para a conta registrada no Passo 3.
6. Um Comprovante Eletrônico de Pagamento (CEP) é gerado para a transação e a Belvo recupera os dados do documento.
7. A Belvo compara o `documentType` e `documentNumber` fornecidos ao criar o cliente com as informações fornecidas no CEP.
  1. Se as informações forem as mesmas, o status do Método de Pagamento é definido como `active`.
  2. Se as informações não forem as mesmas, o status do Método de Pagamento é definido como `failed`. Em nossa interface, você verá o motivo da falha (`validation_failed`) junto com uma mensagem detalhando o motivo da falha (`Account owner validation was not successful`).


## **Solicitações de Pagamento com Métodos de Pagamento Adhoc**

1. Você cria um cliente (veja a referência da API).
2. Você cria uma Solicitação de Pagamento com um Método de Pagamento Adhoc para o cliente (veja a referência da API).
3. O status da Solicitação de Pagamento é definido como `pending_validation`.
4. A Belvo envia o “centavo" para a conta registrada no Passo 2.
5. Um Comprovante Eletrônico de Pagamento (CEP) é gerado para a transação e a Belvo recupera os dados do documento.
6. A Belvo compara o `documentType` e `documentNumber` fornecidos no Passo 1 com as informações fornecidas no CEP.
  1. Se as informações forem as mesmas, o status da Solicitação de Pagamento é definido como `initial`.
  2. Se as informações não forem as mesmas, o status da Solicitação de Pagamento é definido como `failed`. Você receberá um webhook `payment_request_failed` com as seguintes informações de falha:

```json
{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // O paymentRequestId
    "reference": "your_reference_here",
    "status": "failed",
    "failedReason": "account_validation_failed",
    "failedMessage": "A validação do proprietário da conta não foi bem-sucedida"
  }
}
```


-->