# Introduction

In this article we provide you a detailed overview of entity states and their transitions within Belvo's payments product.

## Charges

A **Charge** represents the actual payment that needs to be made in Brazil's Open Finance Network. Below we outline the various states in the charge process, detailing the possible transitions between these states and describing the conditions under which these transitions occur. Please see the table below to get a comprehensive overview of each state and the flow of the process.

```mermaid
stateDiagram-v2
    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
    PENDING --> SCHEDULED
    PENDING --> SUCCEEDED
    PENDING --> CANCELED
    PENDING --> FAILED
    SCHEDULED --> SUCCEEDED
    SCHEDULED --> CANCELED
    SCHEDULED --> FAILED
    SUCCEEDED --> [*]
    CANCELED --> [*]
    FAILED --> [*]

    class PENDING,SCHEDULED pending
    class SUCCEEDED success
    class CANCELED cancelled
    class FAILED failed
```

| State  | Description | Transitions To  | Trigger/Event |
|  --- | --- | --- | --- |
| `CREATED` | Initial state when the charge is created. | - `PENDING`

 | - Charge is initiated but not yet processed by the OF network

 |
| `PENDING` | The charge is awaiting further action or scheduling. | - `SCHEDULED`
- `SUCCEEDED`
- `CANCELED`
- `FAILED`

 | - Charge is scheduled for processing
- The Charge has successfully been processed in the OF network
- Charge is canceled by OF network while pending
- Charge fails in the OF network while pending.

 |
| `SCHEDULED` | The charge is scheduled for processing at a future date. | - `SUCCEEDED`
- `CANCELED`
- `FAILED`

 | - Charge is successfully processed
- Charge is canceled while scheduled
- Charge fails while scheduled.

 |
| `SUCCEEDED` | The charge has been successfully processed. | (End state - no further transitions) | None |
| `CANCELED` | The charge has been canceled. | (End state - no further transitions) | None |
| `FAILED` | The charge has failed. | (End state - no further transitions) | None |


## Enrollment

An **Enrollment** represents the authorization of a user's device in the Open Finance Network with their institution (required for Biometric Payments). Below we outline the various states in the Enrollment process, detailing the possible transitions between these states and describing the conditions under which these transitions occur. Please see the table below to get a comprehensive overview of each state and the flow of the process.

```mermaid
stateDiagram-v2
    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
    PENDING --> SUCCEEDED
    PENDING --> FAILED
    SUCCEEDED --> CANCELLED : User or institution cancels enrollment
    SUCCEEDED --> [*]
    CANCELLED --> [*]
    FAILED --> [*]

    class PENDING pending
    class SUCCEEDED success
    class CANCELLED cancelled
    class FAILED failed
```

| State  | Description | Transitions To  | Trigger/Event |
|  --- | --- | --- | --- |
| Initial | Initial State of the Enrollment. | - `PENDING`

 | - The Enrollment payload is accepted and is awaiting confirmation by the user.

 |
| `PENDING` | The Enrollment has been created and is now waiting Authorization from the user. | - `SUCCEEDED`
- `FAILED`

 | - The user has accepted the Enrollment and it was successfully registered in the network as well as in the institution.
- The Enrollment failed, either due to user, network, or institution error.

 |
| `SUCCEEDED` | The Enrollment processes were completed successfully. | - `CANCELED`

 | - The user canceled the Enrollment.

 |
| `FAILED` | The Enrollment process failed. | (End state - no further transitions) | None |
| `CANCELED` | The user canceled the Enrollment. | (End state - no further transitions) | None |


## Payment Authorization

A **Payment Authorization** is the consent that your user gives you to charge (debit money from) their accounts. Below we outline the various states in the Payment Authorization process, detailing the possible transitions between these states and describing the conditions under which these transitions occur. Please see the table below to get a comprehensive overview of each state and the flow of the process.

```mermaid
stateDiagram-v2
    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
    classDef consumed fill:#7B2D8B,color:#fff,stroke:none

    [*] --> AWAITING_AUTHORIZATION
    [*] --> FAILED
    AWAITING_AUTHORIZATION --> AUTHORIZED
    AWAITING_AUTHORIZATION --> PARTIALLY_ACCEPTED
    AWAITING_AUTHORIZATION --> FAILED
    AUTHORIZED --> CONSUMED
    AUTHORIZED --> REVOKED : Pix Automatico Only
    AUTHORIZED --> FAILED : Rejected Single or Scheduled Payment
    PARTIALLY_ACCEPTED --> AUTHORIZED
    PARTIALLY_ACCEPTED --> FAILED
    CONSUMED --> [*]
    REVOKED --> [*]
    FAILED --> [*]

    class AWAITING_AUTHORIZATION,PARTIALLY_ACCEPTED pending
    class AUTHORIZED success
    class REVOKED cancelled
    class FAILED failed
    class CONSUMED consumed
```

| State  | Description | Transitions To  | Trigger/Event |
|  --- | --- | --- | --- |
| *INITIAL* | Initial state when the Payment Authorization is created. | - `AWAITING_AUTHORIZATION`
- `FAILED`

 | - The network accepts the Payment Authorization payload.
- The network rejects (fails) the Payment Authorization payload.

 |
| `AWAITING_AUTHORIZATION` | The Payment Authorization is awaiting confirmation by the user in the institution. | - `AUTHORIZED`
- `PARTIALLY_ACCEPTED`
- `FAILED`

 | - The user has confirmed the Payment Authorization.
- The user confirmed the Payment Authorization, however, the bank account requires an authorization from another party.
- The authorization failed (the user may not have accepted the authorization).

 |
| `PARTIALLY_ACCEPTED` | The user confirmed the Payment Authorization, however, the bank account requires an authorization from another party. The Institution will notify the relevant parties to approve the authorization. | - `AUTHORIZED`
- `FAILED`

 | - All users have confirmed the Payment Authorization.
- The authorization failed (the user may not have accepted the authorization).

 |
| `AUTHORIZED` | The user (or all users) have confirmed the Payment Authorization. | - `CONSUMED`
- `REVOKED`
- `FAILED`

 | - The authorization period (or number of transactions) has finished.
- The user has revoked the authorization.

 |
| `CONSUMED` | The authorization period (or number of transactions) has finished. | (End state - no further transitions) | None |
| `REVOKED` | The user has revoked the authorization. | (End state - no further transitions) | None |
| `FAILED` | The Payment Authorization has failed. | (End state - no further transitions) | None |


## Payment Intents

A **Payment Intent** contains all the information required to process a payment in Brazil's Open Finance Network. Below we outline the various states in the Payment Intent process, detailing the possible transitions between these states and describing the conditions under which these transitions occur. Please see the table below to get a comprehensive overview of each state and the flow of the process.

```mermaid
stateDiagram-v2
    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

    [*] --> REQUIRES_ACTION
    REQUIRES_ACTION --> PROCESSING
    REQUIRES_ACTION --> FAILED
    PROCESSING --> SUCCEEDED
    PROCESSING --> SCHEDULED
    PROCESSING --> CANCELED
    PROCESSING --> FAILED
    SCHEDULED --> SCHEDULE_FINISHED
    SCHEDULED --> CANCELED
    SCHEDULE_FINISHED --> [*]
    SUCCEEDED --> [*]
    CANCELED --> [*]
    FAILED --> [*]

    class REQUIRES_ACTION,PROCESSING,SCHEDULED pending
    class SUCCEEDED,SCHEDULE_FINISHED success
    class CANCELED cancelled
    class FAILED failed
```

| State  | Description | Transitions To  | Trigger/Event |
|  --- | --- | --- | --- |
| Created & Confirmed | Initial state when the Payment Intent is created and is confirmed by the user in the customer's flow. | - `REQUIRES_ACTION`

 | - Payment intent is created and confirmed.

 |
| `REQUIRES_ACTION` | The Payment Intent requires further action. | - `PROCESSING`
- `FAILED`

 | - Payment intent contains all required information
- Payment intent fails (for example, the user did not grant their consent in the banking application).

 |
| `PROCESSING` | The Payment Intent is being processed. | - `SCHEDULED`
- `SUCCEEDED`
- `CANCELED`
- `FAILED`

 | - Payment intent moves to scheduled state
- Payment intent is successfully processed
- Payment intent is canceled
- Payment intent fails.

 |
| `SCHEDULED` | The Payment Intent is scheduled for processing. | - `SCHEDULE_FINISHED`
- `CANCELED`

 | - Payment intent completed schedule payments
- Payment intent is canceled.

 |
| `SCHEDULE_FINISHED` | The Payment Intent has finished the scheduled processing. Only used if not 100% of a schedule succeeded. Otherwise the final status is `SUCCEEDED`. | (End state - no further transitions) | None |
| `SUCCEEDED` | The Payment Intent has been successfully processed. | (End state - no further transitions) | None |
| `CANCELED` | The Payment Intent has been canceled. | (End state - no further transitions) | None |
| `FAILED` | The Payment Intent has failed. | (End state - no further transitions) | None |