# Belvo API Docs
# Introduction
Reach new audiences and convert more users by easily and safely connecting to their financial data, understanding their behavior and enabling instant payments with open finance. Through our API, you can access:
## Available Information and Payment Methods
Belvo is an open banking API for Latin America that allows companies to access banking and fiscal information in a secure as well as agile way.
Through our API, you can access:
- Banking Information in Brazil
- Employment Information in Brazil
- Employment Information in Mexico
- Fiscal Information in Mexico
- Fiscal Information in Chile
You can also use our API to make payments in:
- Brazil
- Mexico
## Data Dictionaries
If you woud like the response documentation in Excel or CSV form, please download them from our public GitHub Reposiitory: Belvo Open Finance Data Dictionaries.
Our EXCEL and CSV files are additionally localized into Spanish and Portuguese (Brazil).
## Environments
We currently offer two environments: sandbox and production.
### Sandbox
Available for:
- 🟢 Aggregation and Enrichment
- ⚪️ Payment Initiation
Use our Sandbox environment to build your integration. We offer dummy data that mimics that of real-world use cases, which means you can test out all the endpoints, use the widget, and implement webhooks - just as you would with real-world data!
All you need to get started with the Sandbox environment is to get your API keys. We really recommend that you start creating your integration in this environment.
### Production
Available for:
- 🟢 Aggregation and Enrichment
- 🟢 Payment Initiation
After you have tested your integration in the Sandbox environment and are ready to go live, you'll need to request access to our Production environment. After you request access, our Sales Team will get in contact with you to schedule a meeting just to ensure your needs are met, and then you'll just need to go through a certification process with one of our engineers to make sure that your integration is running optimally. To prepare for the certification meeting, just follow our Integration checklist.
Once your integration is certified, all you'll need to do is:
- [ ] Request Production API keys (and change your Sandbox API keys in the code to these new ones).
- [ ] Change the base URL that you make requests to from `sandbox.belvo.com` to `api.belvo.com`.
- [ ] If you're using webhooks, make sure to set a Production URL for your webhooks.
## Response codes
We use the following HTTP status code in the response depending on the
success or failure:
| Status Code | Description |
|-----------|-------|
| `200` | ✅ **Success** - The content is available in the response body. |
| `201` | ✅ **Success** - The content was created successfully on Belvo. |
| `204` | ✅ **Success** - No content to return. |
| `400` | ❌ **Bad Request Error** - Request returned an error, detail in the content.|
| `401` | ❌ **Unauthorized** - The Belvo credentials provided are not valid.|
| `404` | ❌ **Not Found** - The resource you try to access cannot be found.|
| `405` | ❌ **Method Not Allowed** - The HTTP method you are using is not accepted for this resource.|
| `408` | ❌ **Request Timeout** - The request timed out and was terminated by the server.|
| `428` | ❌ **MFA Token Required** - MFA token was required by the institution to connect. |
| `500` | ❌ **Internal Server Error** - The detail of the error is available in the response body.|
## Error handling
Belvo API errors are returned in JSON format. For example, an error might look like this:
```json
[
{
"request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
"message": "This field is required.",
"code": "required",
"field": "link"
}
]
```
Typically, an error response will have the following parameters:
- `request_id`: a unique ID for the request, you should share it with the Belvo support team for investigations.
- `message`: human-readable description of the error.
- `code`: a unique code for the error. Check the table below to see how to handle each error code.
- `field` *(optional)*: The specific field in the request body that has an issue.
### Request identifier
When you need help with a specific error, include the request identifier (`request_id`) in your message to the Belvo support team. This will speed up investigations and get you back up and running in no time at all.
### Error codes and troubleshooting
For a full list of errors and how to troubleshoot them, please see our dedicated Error Handling article.
### Retry policy
#### 50x errors
Implement an automated exponential backoff of up to five retries. We recommend using a base interval of three seconds with a factor of two. For example, the first retry should be after three seconds, the second retry after six seconds (2 * 3), the third retry after 12 seconds (2 * 6), the fourth retry after 24 seconds (2 * 12), and the fifth retry after 48 seconds (2 * 24).
#### 40x errors
You should not retry making requests if you receive a 40x response, as this is a client error.
The only exception is the “Too Many Sessions” error, as it means that your end-user is accessing the account from another browser at the same time. In this case, please implement the same retry policy as with 50x errors.
## Deprecated fields
In our schema, you may see that a field has been marked as `deprecated`. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should **not** rely on this field.
## OpenAPI: required and nullable fields
In our API specification, you'll see that some response parameters will have a **required** annotation. According to the OpenAPI specification, when a response parameter is marked as **required**, this means that the response key must be returned. However, the value of that response parameter can be `null`.
> 📘 Info
>
> In short, any response parameter marked as required will be returned by our API, but the value can be set to null.
Version: 1.223.0
## Servers
Sandbox
```
https://sandbox.belvo.com
```
## Security
### basicAuth
Belvo employs **basic authentication** using your secret keys (You can find your API secret keys in your Belvo Dashboard, under the **Developers** section).
To authenticate, you need to use your API `secretId` as the `username` and your API `secretPassword` as the `password`. These credentials need to be **Base64 encoded** and included in the `Authorization` header of your HTTP requests. For example:
```shell
curl -X GET https://sandbox.belvo.com/api/ \
-H "Authorization: Basic $(echo -n 'YOUR_SECRET_ID:YOUR_SECRET_PASSWORD' | base64)"
```
Replace `YOUR_SECRET_ID` and `YOUR_SECRET_PASSWORD` with your actual credentials. **Never expose your credentials in client-side code or public repositories**.
Type: http
Scheme: basic
## Download OpenAPI description
[Belvo API Docs](https://developers.belvo.com/_bundle/apis/BelvoOpenApiSpec.yaml)
## Institutions
An **institution** is an entity that Belvo can access information from. It can be a:
- bank institution, such as Nubank Brazil.
- fiscal institution, such as the *Servicio de Administración Tributaria (SAT)* in Mexico.
- employment institutions, such as *Instituto Mexicano del Seguro Social (IMSS)* in Mexico or *Instituto Nacional do Seguro Social (INSS)* in Brazil.
### List institutions
- [GET /api/institutions/](https://developers.belvo.com/apis/belvoopenapispec/institutions/listinstitutions.md): ## ▶️ Usage
With the List Institutions method, you can:
1. List all institutions Belvo has available.
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Get an institution's details
- [GET /api/institutions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/institutions/detailinstitution.md): Get the details of a specific institution.
## Links
A **Link** is a set of credentials associated to an end-user's access to an **institution**. You will need to register a **Link** before accessing information from that specific end-user, such as account or transaction details.
We recommend using the Belvo Hosted Widget to manage the connection process.
### List links
- [GET /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/listlinks.md): ## ▶️ Usage
With the List Links method, you can:
1. List all links elated to your Belvo account (without using any query parameters).
2. Get the details of a specific link.id (using the id query parameter).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Register a new link
- [POST /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/registerlink.md): ## ▶️ Usage
Register a new link (a connection between your user and their institution) using the Belvo API.
> 👍 We really recommend using our Connect Widget to handle link creation and link status updates.
To make things easier, we've included custom examples for the links you can create for each of our products. Just click on the type of link you want to create in the Body Params section below.
### Complete a links request
- [PATCH /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/patchlinks.md): Used to resume a Link register session that was paused because an MFA token
was required by the institution.
### Get a link's details
- [GET /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/detaillink.md): Get the details of a specific link.
### Modify a link's data retrieval
- [PATCH /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/modifylinkdataretrieval.md): Modify the data retrieval settings for a specific link. At present you can:
- Change a link's access mode from single to recurrent or from recurrent to single.
- Modify they stale_in period for the link.
- Modify the historical resources you want to retrieve for the link (fetch_resources).
## Changing a link's access_mode
When you change a link from single to recurrent, the next day a historical update of the core resources for the link is triggered (resulting in you receiving historical_update webhooks for the link). You are billed for these historical updates.
## Modifying stale_in
If you only modify the stale_in period for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the access_mode.
## Modifying fetch_resources
If you only modify the fetch_resources for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the access_mode.
### Update a link's credentials
- [PUT /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/updatelink.md): Update the credentials of a specific link. If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you'll receive historical update webhooks.
> 👍 Use our Connect Widget
>
> We recommend using our Connect Widget to handle updating invalid or token_required links.
### Delete a link
- [DELETE /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/destroylink.md): Delete a specific link and all the associated data (for example: transactions, accounts, invoices, tax returns, employments, and so on) for that link from your Belvo account. This action is irreversible, and you will not be able to recover the deleted data.
{% admonition type="success" name="Use the X-Belvo-Request-Mode: async header" %}
We highly recommend setting the X-Belvo-Request-Mode header to async to enable asynchronous deletion. This way, you will avoid the rate limit of 5 deletions per minute. When set, the endpoint will respond with a 202 Accepted status and provide a request ID for tracking the deletion process. Once the process is complete, you will receive a link_deleted webhook notification.
If you do not set this header, the endpoint will respond with a 204 No Content status, but you will be subject to the rate limit of 5 deletions per minute. If you exceed this limit, you will receive a 429 Too Many Requests error.
{% /admonition %}
### Trigger a historical update for a link
- [POST /api/links/{id}/refresh/](https://developers.belvo.com/apis/belvoopenapispec/links/refreshhistoricaldataforlink.md): {% admonition type="warning" name="Concurrent Request Limit" %}
To prevent duplicate requests, this endpoint has a 10-minute cooldown period per link. If you attempt to refresh the same link within 10 minutes of a previous request, you will receive a 409 Conflict error with the message "The link has already been refreshed. Please wait X minutes before trying again.".
{% /admonition %}
Use this method to trigger a historical update for a specific link (single or recurrent). Use the fetch_resources parameter to specify which resources you want to update. If you do not specify this parameter, the historical update will be performed for all resources supported by the institution that the link is associated with.
On a successful request, our API will respond with a 202 status code and a request_id that you can later use to associate a given historical_update webhook to this request.
{% admonition type="info" name="Does not update link definition" %}
This endpoint does not update the link definition itself, only the historical data for the specified resources. If you want to change the link's fetch_resources permanently, you should use the Modify a link's data retrieval method instead.
{% /admonition %}
## Widget Access Token
### Generate a widget access token
- [POST /api/token/](https://developers.belvo.com/apis/belvoopenapispec/widget-access-token/generatewidgetaccesstoken.md): Generate a widget access token for our Hosted Widget.
## Consents
A consent is a permission given by the end user to access their financial data in the Open Finance Network in Brazil.
### List consents
- [GET /api/consents/](https://developers.belvo.com/apis/belvoopenapispec/consents/listconsents.md): ## ▶️ Usage
With the Consents method, you can:
1. List all consents related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Get a consent's details
- [GET /api/consents/{id}/](https://developers.belvo.com/apis/belvoopenapispec/consents/detailconsent.md): Get the details of a specific consent.
## Owners
An **owner** represents the person who has access to a Link and is the owner of all the accounts inside the Link.
You can use this endpoint in order to get useful information about your client, such as:
- their full name
- key contact information
- information about the ID document they used when opening the account
### List owners
- [GET /api/owners/](https://developers.belvo.com/apis/belvoopenapispec/owners/listowners.md): ## ▶️ Usage
With the List Owners method, you can:
1. List owners related to a specific link.id (using the link query parameter).
2. Get the details of a specific owners.id (using the id query parameter).
3. [Not Recommended] List all owners related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 🚨 Deprecated Fields
This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.
### Retrieve owners for a link
- [POST /api/owners/](https://developers.belvo.com/apis/belvoopenapispec/owners/retrieveowners.md): Retrieve owner information from a specific link.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Complete an owners request
- [PATCH /api/owners/](https://developers.belvo.com/apis/belvoopenapispec/owners/patchowners.md): Used to resume an Owner retrieve session that was paused because an MFA
token was required by the institution.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Get an owner's details
- [GET /api/owners/{id}/](https://developers.belvo.com/apis/belvoopenapispec/owners/detailowner.md): Get the details of a specific owner.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Delete an owner
- [DELETE /api/owners/{id}/](https://developers.belvo.com/apis/belvoopenapispec/owners/destroyowner.md): Delete a specific owner from your Belvo account.
## Accounts
An **account** is the representation of a bank account inside a financial institution. A user can have one or more accounts in an institution.
For example, one user (or link) can have a checking account, several credit cards, and a loan account.
Querying for a user's account information is useful as you can get information regarding:
- what types of accounts the user has.
- the balance for each account (savings, checking, credit card, loan, and so on).
- detailed information regarding their credit card spending.
- the current situation of any loans they may have.
### List accounts
- [GET /api/accounts/](https://developers.belvo.com/apis/belvoopenapispec/accounts/listaccounts.md): ## ▶️ Usage
With the List Accounts method, you can:
1. List accounts related to a specific link.id (using the link query parameter).
2. Get the details of a specific account.id (using the id query parameter).
3. [Not Recommended] List all accounts related to your Belvo account (without using any query parameters).
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🚨 Deprecated Fields
This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.
### Retrieve accounts for a link
- [POST /api/accounts/](https://developers.belvo.com/apis/belvoopenapispec/accounts/retrieveaccounts.md): Retrieve accounts from an existing link.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Complete an accounts request
- [PATCH /api/accounts/](https://developers.belvo.com/apis/belvoopenapispec/accounts/patchaccounts.md): Used to resume an Account retrieve session that was paused because an MFA
token was required by the institution.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Get an account's details
- [GET /api/accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/accounts/detailaccount.md): Get the details of a specific account.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Delete an account
- [DELETE /api/accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/accounts/destroyaccount.md): Delete a specific account from your Belvo account.
{% admonition type="danger" name="Rate Limited" %}
This endpoint is rate limited. You can only delete 5 items per minute. If you exceed this limit, you will receive a 429 status code.
{% /admonition %}
{% admonition type="info" %}
When you delete an account, all the associated transactions and owner information for that account are also removed.
{% /admonition %}
## Balances
A balance is the amount of money available in a given bank account (checking or savings) at a given time.
### List balances
- [GET /api/br/balances/](https://developers.belvo.com/apis/belvoopenapispec/balances/listbalances.md): ## ▶️ Usage
With the List Balances method, you can:
1. [Required] List balances related to a specific link.id (using the link query parameter).
2. [Highly Recommended] List balances related to a specific link.id and account.id (using the link and account query parameters).
2. Get the details of a specific balance.id (using the id query parameter).
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🚨 Deprecated Fields
This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.
### Retrieve the current balance for a link
- [POST /api/br/balances/](https://developers.belvo.com/apis/belvoopenapispec/balances/retrievebalances.md): Retrieve the current account balance for all checking and savings accounts for an existing link. We recommend also sending the account.id so that you receive balances for a specific account.
### Get a balances's details
- [GET /api/br/balances/{id}/](https://developers.belvo.com/apis/belvoopenapispec/balances/detailbalance.md): Get the details of a specific balance.
## Exchanges
An exchange is a currency exchange operation in the Brazilian Open Finance Network. The resource contains details of foreign exchange operations, including exchange rates, amounts in local and foreign currencies, and settlement information. Each exchange operation can have associated history events that record any modifications to the original contract.
### List exchanges
- [GET /api/br/exchanges/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/listexchanges.md): {% admonition type="warning" name="Coming Soon" %}
This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
## ▶️ Usage
With the List Exchanges method, you can:
1. [Required] List exchanges related to a specific link.id (using the link query parameter).
2. Get the details of a specific exchange.id (using the id query parameter).
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
### Retrieve exchanges for a link
- [POST /api/br/exchanges/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/retrieveexchanges.md): {% admonition type="warning" name="Coming Soon" %}
This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
Retrieve exchange operations for an existing link. By default, we retrieve exchange data for the last 365 days.
> Note: When you retrieve exchanges, we automatically retrieve the exchange history for each exchange operation found.
### Get an exchange's details
- [GET /api/br/exchanges/{id}/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/detailexchange.md): {% admonition type="warning" name="Coming Soon" %}
This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
Get the details of a specific exchange.
> Note: When you delete an exchange, all associated exchange history records are also deleted.
### Delete an exchange
- [DELETE /api/br/exchanges/{id}/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/deleteexchange.md): {% admonition type="warning" name="Coming Soon" %}
This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
Delete a specific exchange from your Belvo account.
> Note: When you delete an exchange, all associated exchange history records are also deleted.
### List exchange history for a specific exchange
- [GET /api/br/exchanges/{id}/history/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/listexchangehistory.md): {% admonition type="warning" name="Coming Soon" %}
This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
Get the modification history (audit trail) for a specific exchange operation.
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## Transactions
A **transaction** contains the detailed information of each movement inside an account. For example, a purchase at a store or a restaurant.
### List transactions
- [GET /api/transactions/](https://developers.belvo.com/apis/belvoopenapispec/transactions/listtransactions.md): ## ▶️ Usage
With the List Transactions method, you can:
1. [Required] List transactions related to a specific link.id (using the link query parameter).
2. Filter the returned transactions using query parameters (see the Filtering responses section below).
3. Get the details of a specific transaction.id (using the id query parameter along with the link query parameter).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve transactions for a link
- [POST /api/transactions/](https://developers.belvo.com/apis/belvoopenapispec/transactions/retrievetransactions.md): Retrieve transactions for one or more accounts from a specific link.
> 📘 Transaction Periods and Retrieval
>
> When retrieving transactions, it is important to understand that the available transaction data ranges depend on each institution. If you try to access older information than what we can access, we will return all the data we can read within that date range. For example, if you request transactions for the last year and we can only access the last six months, we will return the information corresponding to these six months of data.
### Complete a transactions request
- [PATCH /api/transactions/](https://developers.belvo.com/apis/belvoopenapispec/transactions/patchtransactions.md): Used to resume a Transaction retrieve session that was paused because an MFA
token was required by the institution.
### Get a transaction's details
- [GET /api/transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/transactions/detailtransaction.md): Get the details of a specific transaction.
### Delete a transaction
- [DELETE /api/transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/transactions/destroytransaction.md): Delete a specific transaction from your Belvo account.
> ❗️ Rate limited
>
> This endpoint is rate limited. You can only delete 5 items per minute. If you exceed this limit, you will receive a 429 status code.
## Bills
A **bill** refers to the credit card bill a user receives for a given account.
### List bills
- [GET /api/bills/](https://developers.belvo.com/apis/belvoopenapispec/bills/listbills.md): ## ▶️ Usage
With the List Bills method, you can:
1. [Required] List bills related to a specific link.id (using the link query parameter).
2. Filter the returned bills using query parameters (see the Filtering responses section below).
3. Get the details of a specific bill.id (using the id query parameter).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve bills for a link
- [POST /api/bills/](https://developers.belvo.com/apis/belvoopenapispec/bills/retrievebills.md): Retrieve bills from one or more accounts for a specific link within a
specified date range.
### Get a bill's details
- [GET /api/bills/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bills/detailbills.md): Get the details of a specific bill.
### Delete a bill
- [DELETE /api/bills/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bills/destroybills.md): Delete a specific bill from your Belvo account.
## Investments Brazil
### List investments
- [GET /api/br/investments/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/listinvestmentsbrazil.md): ## ▶️ Usage
With the List Investments method, you can:
1. [Required] List investments related to a specific link.id (using the link query parameter).
2. Get the details of a specific investment.id (using the id query parameter).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve investments for a link
- [POST /api/br/investments/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/retrieveinvestmentsbrazil.md): Retrieve investments for an existing link.
### Get an investment's details
- [GET /api/br/investments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/detailinvestmentbrazil.md): Get the details of a specific investment.
### Delete an investment
- [DELETE /api/br/investments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/destroyinvestmentbrazil.md): Delete a specific investment from your Belvo account.
## Investment Transactions Brazil
### List investment transactions
- [GET /api/br/investment-transactions/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/listinvestmenttransactionsbrazil.md): ## ▶️ Usage
With the List Investment Transactions method, you can:
1. [Required] List investment transactions related to a specific link.id (using the link query parameter).
2. Get the details of a specific investment-transaction.id (using the id query parameter).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve investments for a link
- [POST /api/br/investment-transactions/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/retrieveinvestmenttransactionsbrazil.md): Retrieve investments for an existing link.
### Get an investment transaction's details
- [GET /api/br/investment-transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/detailinvestmenttransactionbrazil.md): Get the details of a specific investment transaction.
### Delete an investment transaction
- [DELETE /api/br/investment-transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/destroyinvestmenttransactionbrazil.md): Delete a specific investment transaction from your Belvo account.
## Employments Brazil
Our employments resource for Brazil lets you get a comprehensive view of your user's current employment history and salary information.
For each user, we return the:
- work history (including occupations and employer data)
- historical and current salary information (per employer)
At the moment, the employments resource is available for:
- 🇧🇷 Brazil (INSS)
### List employments
- [GET /api/br/employments/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/listemploymentsbrazil.md): ## ▶️ Usage
With the List Employments method, you can:
1. [Required] List employments related to a specific link.id (using the link query parameter).
2. Get the details of a specific employment.id (using the id query parameter).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve employments for a link
- [POST /api/br/employments/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/retrieveemploymentsbrazil.md): Retrieve employments from an existing link.
### Get an employment's details
- [GET /api/br/employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/detailemploymentbrazil.md): Get the details of a specific employment.
### Delete an employment
- [DELETE /api/br/employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/destroyemploymentbrazil.md): Delete a specific employment from your Belvo account.
## Employment Records Mexico
Our employment records resource for Mexico lets you get a comprehensive view of your user’s current social security contributions and employment history.
With Belvo's employment records resource for Mexico, you can access information about your user's current social security contributions and employment history. For the each user, we return the:
- personal data
- work history
- historical and current daily base salary
- and more!
At the moment, the employment records resource is available for:
- 🇲🇽 Mexico (IMSS)
- 🇲🇽 Mexico (ISSSTE)
### List employment records
- [GET /api/employment-records/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/listemploymentrecords.md): ## ▶️ Usage
With the List Employment Records method, you can:
1. List employment records related to a specific link.id (using the link query parameter).
2. Get the details of a specific employment-record.id (using the id query parameter).
3. [Not Recommended] List all employment records related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve employment record details
- [POST /api/employment-records/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/retrieveemploymentrecorddetails.md): Retrieve employment record details for an individual.
### Get an employment record's details
- [GET /api/employment-records/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/detailemploymentrecord.md): Get the details of a specific employment record.
### Delete an employment record
- [DELETE /api/employment-records/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/destroyemploymentrecord.md): Delete a specific employment record from your Belvo account.
> ❗️ Rate limited
>
> This endpoint is rate limited. You can only delete 5 items per minute. If you exceed this limit, you will receive a 429 status code.
## Current Employments Mexico
The Current Employments resource provides real-time access to the current employment status of individuals in Mexico. This resource offers detailed information about whether an individual is currently employed or unemployed, along with their active employment records.
## Key Features
- **Real-time Employment Status**: Get up-to-date information about an individual's current employment situation
- **Current vs Historical**: Unlike Employment Records, this resource focuses specifically on current employment status rather than historical employment data
- **Comprehensive Employment Details**: When employed, receive detailed information including employer details, salary information, and employment duration
- **Unemployment Status**: Clear indication when an individual is currently unemployed
When an individual is **employed**, you will receive:
- Personal identification data (name, birth date, NSS, CURP)
- Current employment status
- Employer information (name, RFC, ID)
- Employment location (state)
- Duration of employment (days employed)
- Salary information (base and monthly salary)
### List current employments
- [GET /api/mx/current-employments/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/listcurrentemployments.md): ## ▶️ Usage
With the List Current Employments method, you can:
1. List current employments related to a specific link.id (using the link query parameter).
2. Get the details of a specific current-employment.id (using the id query parameter).
3. [Not Recommended] List all current employments related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve current employments
- [POST /api/mx/current-employments/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/retrievecurrentemployments.md): Retrieve current employment information for a specific link.id.
### Get current employment details
- [GET /api/mx/current-employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/getcurrentemploymentdetails.md): Get the details of a specific current employment record.
### Delete current employment
- [DELETE /api/mx/current-employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/deletecurrentemployment.md): Delete a specific current employment record from your Belvo account.
## Invoices
### List invoices
- [GET /api/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices/listinvoices.md): ## ▶️ Usage
With the List Invoices method, you can:
1. List invoices related to a specific link.id (using the link query parameter).
2. Get the details of a specific invoice.id (using the id query parameter).
3. [Not Recommended] List all invoices related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 🚨 Deprecated Fields
This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.
### Retrieve invoices for a link
- [POST /api/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices/retrieveinvoices.md): Retrieve invoice information from a specific fiscal link.
> 📘 Info
>
> You can ask for up to one year (365 days) of invoices per request. If you need invoices for more than one year, just make another request.
> 🚧 Warning
>
> This resource may return deprecated fields. Please check the response documentation for more information.
### Complete an invoices request
- [PATCH /api/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices/patchinvoices.md): Used to resume an Invoice retrieve session that was paused because an MFA
token was required by the institution.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Get an invoice's details
- [GET /api/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices/detailinvoice.md): Get the details of a specific invoice.
{% admonition type="info" %}
This resource may return deprecated fields. Please check the response documentation for more information.
{% /admonition %}
### Delete an invoice
- [DELETE /api/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices/destroyinvoice.md): Delete a specific invoice from your Belvo account.
## Tax compliance status
### List tax compliance statuses
- [GET /api/tax-compliance-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/listtaxcompliancestatus.md): ## ▶️ Usage
With the List Tax Compliance Statuses method, you can:
1. List tax compliance statuses related to a specific link.id (using the link query parameter).
2. Get the details of a specific tax-compliance-status.id (using the id query parameter).
3. [Not Recommended] List all tax compliance statuses related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve tax compliance statuses for a link
- [POST /api/tax-compliance-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/retrievetaxcompliancestatus.md): Retrieve the Tax compliance status information for a specific fiscal link.
### Get a tax compliance status's details
- [GET /api/tax-compliance-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/detailtaxcompliancestatus.md): Get the details of a specific Tax compliance status.
### Delete a tax compliance status
- [DELETE /api/tax-compliance-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/destroytaxcompliancestatus.md): Delete a specific Tax compliance status from your Belvo account.
## Tax returns
### List tax returns
- [GET /api/tax-returns/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/listtaxreturns.md): ## ▶️ Usage
With the List Tax Returns method, you can:
1. List tax returns related to a specific link.id (using the link query parameter).
2. Get the details of a specific tax-return.id (using the id query parameter).
3. [Not Recommended] List all tax returns related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 🔔 Multiple Schemas
As a link can have both yearly and monthly tax returns, the response will include a mix of these two types of tax returns (and thus difference schemas).
### Retrieve tax returns for a link
- [POST /api/tax-returns/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/retrievetaxreturns.md): Retrieve tax return information for a specific fiscal link.
### Get a tax return's details
- [GET /api/tax-returns/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/detailtaxreturn.md): Get the details of a specific tax return.
### Delete a tax return
- [DELETE /api/tax-returns/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/destroytaxreturn.md): Delete a specific tax return from your Belvo account.
## Tax retentions
### List tax retentions
- [GET /api/tax-retentions/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/listtaxretentions.md): ## ▶️ Usage
With the List Tax Retentions method, you can:
1. List tax retentions related to a specific link.id (using the link query parameter).
2. Get the details of a specific tax-retention.id (using the id query parameter).
3. [Not Recommended] List all tax retentions related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve tax retentions for a link
- [POST /api/tax-retentions/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/retrievetaxretentions.md): Retrieve tax retention information from a specific link. The maximum number of tax retentions that can be returned for a period is 500.
### Get a tax retention's details
- [GET /api/tax-retentions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/detailtaxretentions.md): Get the details of a specific tax retention.
### Delete a tax retention
- [DELETE /api/tax-retentions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/destroytaxretention.md): Delete a specific tax retention from your Belvo account.
## Tax status
### List tax statuses
- [GET /api/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/listtaxstatus.md): ## ▶️ Usage
With the List Tax Statuses method, you can:
1. List tax statuses related to a specific link.id (using the link query parameter).
2. Get the details of a specific tax-status.id (using the id query parameter).
3. [Not Recommended] List all tax statuses related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve tax statuses for a link
- [POST /api/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/retrievetaxstatus.md): Retrieve tax status information for a specific fiscal link.
### Get a tax status's details
- [GET /api/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/detailtaxstatus.md): Get the details of a specific tax status.
### Delete a tax status
- [DELETE /api/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/destroytaxstatus.md): Delete a specific tax status from your Belvo account.
## Financial Statements
### List Financial Statements
- [GET /api/financial-statements/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/listfinancialstatements.md): ## ▶️ Usage
With the List Financial Statements method, you can:
1. List financial statements related to a specific link.id (using the link query parameter).
2. Get the details of a specific financial-statement.id (using the id query parameter).
3. [Not Recommended] List all financial statements related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve Financial Statements for a link
- [POST /api/financial-statements/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/retrievefinancialstatements.md): Retrieve the Financial Statements information for a specific fiscal link.
### Get a Financial Statement's details
- [GET /api/financial-statements/{id}/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/detailfinancialstatement.md): Get the details of a specific Financial Statement.
### Delete a Financial Statement
- [DELETE /api/financial-statements/{id}/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/destroyfinancialstatement.md): Delete a specific Financial Statement from your Belvo account.
## Invoices Chile
### List invoices
- [GET /api/cl/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/listinvoiceschile.md): ## ▶️ Usage
With the List Invoices method, you can:
1. List invoices related to a specific link.id (using the link query parameter).
2. Get the details of a specific invoice.id (using the id query parameter).
3. [Not Recommended] List all invoices related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve invoices for a link
- [POST /api/cl/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/retrieveinvoiceschile.md): Retrieve invoice information from a specific Chilean fiscal link.
You can ask for up to one year (365 days) of invoices per request. If you need invoices for more than one year, just make another request.
> 📘 Highly Recommended > > We strongly recommend that you use Belvo's X-Belvo-Request-Mode header parameter and implement an asynchronous workflow. This will ensure that you do not receive any timeout errors while retrieving invoice data.
### Get an invoice's details
- [GET /api/cl/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/detailinvoicechile.md): Get the details of a specific invoice.
### Delete an invoice
- [DELETE /api/cl/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/destroyinvoicechile.md): Delete a specific invoice from your Belvo account.
## Tax Status Chile
### List tax statuses
- [GET /api/cl/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/listtaxstatuschile.md): ## ▶️ Usage
With the Tax Status method, you can:
1. List tax statuses related to a specific link.id (using the link query parameter).
2. Get the details of a specific tax-status.id (using the id query parameter).
3. [Not Recommended] List all tax statuses related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve tax statuses for a link
- [POST /api/cl/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/retrievetaxstatuschile.md): Retrieve tax status information for a specific fiscal link.
### Get a tax status's details
- [GET /api/cl/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/detailtaxstatuschile.md): Get the details of a specific tax status.
### Delete a tax status
- [DELETE /api/cl/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/destroytaxstatuschile.md): Delete a specific tax status from your Belvo account.
## Debt Reports Chile
### List debts reports
- [GET /api/cl/debt-reports/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/listdebtreportchile.md): ## ▶️ Usage
With the List Debt Reports method, you can:
1. List debt reports related to a specific link.id (using the link query parameter).
2. Get the details of a specific debt-report.id (using the id query parameter).
3. [Not Recommended] List all debt reports related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve debt details for a link
- [POST /api/cl/debt-reports/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/retrievedebtreportchile.md): Retrieve debt reports information for a specific fiscal link.
### Get a debt's details
- [GET /api/cl/debt-reports/{id}/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/detaildebtreportchile.md): Get the details of a specific debt.
### Delete a debt report
- [DELETE /api/cl/debt-reports/{id}/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/destroydebtreportchile.md): Delete a specific debt report from your Belvo account.
## Incomes
Use the Incomes endpoint to gather insights on an account's income sources for the past 365 days. The endpoint is particularly useful when you want to verify a person's income.
> 📘 Info
>
> The incomes resource is **only** available for Checking and Savings accounts associated with banking links.
### List incomes
- [GET /api/incomes/](https://developers.belvo.com/apis/belvoopenapispec/incomes/listincomes.md): ## ▶️ Usage
With the List Incomes method, you can:
1. List incomes related to a specific link.id (using the link query parameter).
2. Get the details of a specific income.id (using the id query parameter).
3. [Not Recommended] List all incomes related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve incomes for a link
- [POST /api/incomes/](https://developers.belvo.com/apis/belvoopenapispec/incomes/retrieveincome.md): Retrieve income insights for checking and savings accounts from a
specific link. You can receive insights for a period of up to 365 days,
depending on the transaction history available for each institution.
### Get an income's details
- [GET /api/incomes/{id}/](https://developers.belvo.com/apis/belvoopenapispec/incomes/detailincome.md): Get the details of a specific income.
### Delete an income
- [DELETE /api/incomes/{id}/](https://developers.belvo.com/apis/belvoopenapispec/incomes/destroyincomes.md): Delete a specific income from your Belvo account.
## Recurring Expenses
Belvo's Recurring Expenses API allows you to identify a user's regular payments for subscription services, such as Netflix or gym memberships, as well as utility payments, such as electricity or phone bills. We return information for up to 365 days.
> 📘 Info
>
> The recurring expenses resource is **only** available for Checking, Savings and Credit Card accounts associated with banking links.
### List recurring expenses
- [GET /api/recurring-expenses/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/listrecurringexpenses.md): ## ▶️ Usage
With the List Recurring Expenses method, you can:
1. List recurring expenses related to a specific link.id (using the link query parameter).
2. Get the details of a specific recurring-expense.id (using the id query parameter).
3. [Not Recommended] List all recurring expenses related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve recurring expenses for a link
- [POST /api/recurring-expenses/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/retrieverecurringexpenses.md): Retrieve recurring expense insights for checking and savings accounts from a
specific link. You can receive insights for a period of up to 365 days,
depending on the transaction history available for each institution.
### Get a recurring expense's details
- [GET /api/recurring-expenses/{id}/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/detailrecurringexpense.md): Get the details of a specific recurring expense.
### Delete a recurring expense
- [DELETE /api/recurring-expenses/{id}/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/destroyrecurringexpense.md): Delete a specific recurring expense from your Belvo account.
## Risk Insights
### List risk insights
- [GET /api/risk-insights/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/listriskinsights.md): ## ▶️ Usage
With the List Risk Insights method, you can:
1. List risk insights related to a specific link.id (using the link query parameter).
2. Get the details of a specific risk-insight.id (using the id query parameter).
3. [Not Recommended] List all risk insights related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve risk insights for a link
- [POST /api/risk-insights/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/retrieveriskinsights.md): Request the risk insights for a given link ID.
If you need to know the currency of the account, just do a GET Details to the accounts endpoint (using the ID you receive from the accounts response).
### Get a risk insight's details
- [GET /api/risk-insights/{id}/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/detailriskinsights.md): Get the details of a specific risk insight.
### Delete a risk insight
- [DELETE /api/risk-insights/{id}/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/destroyriskinsights.md): Delete a specific risk insight from your Belvo account.
## Employment Metrics
### List employment metrics
- [GET /api/employment-metrics/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/listemploymentmetrics.md): ## ▶️ Usage
With the List Employment Metrics method, you can:
1. List employment metrics related to a specific link.id (using the link query parameter).
2. Get the details of a specific employment-metric.id (using the id query parameter).
3. [Not Recommended] List all employment metrics related to your Belvo account (without using any query parameters).
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
### Retrieve employment metrics
- [POST /api/employment-metrics/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/retrieveemploymentmetricdetails.md): Retrieve employment metrics for an individual.
> Note: Employment metrics are only available for IMSS links (imss_mx_employment), as a paid opt-in add-on. They aren't available for ISSSTE (issste_mx_employment) or the Sandbox institution (planet_mx_employment). Contact your Belvo representative to enable them.
> Note: Before requesting employment metrics, make sure to first make a POST Retrieve employment record details request.
### Get an employment metric's details
- [GET /api/employment-metrics/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/detailemploymentmetric.md): Get the details of a specific employment metric.
### Delete an employment metric
- [DELETE /api/employment-metrics/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/destroyemploymentmetric.md): Delete a specific employment metric from your Belvo account.
## Payment Institutions (Brazil)
A **payment institution** is an entity that Belvo can access information from. You can see a complete list of institutions available for payments by making a List request to this endpoint.
### List all payment institutions
- [GET /payments/br/institutions/](https://developers.belvo.com/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil.md): List all available payment institutions.
## Customers (Brazil)
A **customer** is the payer that's going to push funds into your bank account. You need to create a customer in order to receive inflow payments to your organization's bank account.
{% admonition type="info" name="Resource Versioning" %}
This endpoint supports resource-level versioning. By including the header `X-Belvo-API-Resource-Version: Payments-BR.V2`, you can access the latest (V2) request and response formats. If the header is not provided, the default (V1) format will be used. See the API documentation for details on the differences between versions.
{% /admonition %}
### Create a new customer
- [POST /payments/br/customers/](https://developers.belvo.com/apis/belvoopenapispec/customers-(brazil)/createcustomerbrazil.md): Create a new customer to send or request funds.
### List all customers
- [GET /payments/br/customers/](https://developers.belvo.com/apis/belvoopenapispec/customers-(brazil)/listcustomersbrazil.md): List all customers associated with your Belvo account.
### Get details about a customer
- [GET /payments/br/customers/{id}/](https://developers.belvo.com/apis/belvoopenapispec/customers-(brazil)/detailcustomerbrazil.md): Get the details about a specific customer
## Bank Accounts (Brazil)
To receive inflow payments to your organization's bank account, you must register the bank accounts (individual and business) using Belvo's Payments API.
- **Individual** bank accounts must be created for each payer (your customer).
- **Business** bank accounts need to be created for the beneficiary of the payment (your organization).
{% admonition type="info" name="Resource Versioning" %}
This endpoint supports resource-level versioning. By including the header `X-Belvo-API-Resource-Version: Payments-BR.V2`, you can access the latest (V2) request and response formats. If the header is not provided, the default (V1) format will be used. See the API documentation for details on the differences between versions.
{% /admonition %}
### Register a new bank account
- [POST /payments/br/bank-accounts/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/registerbankaccountbrazil.md): Register a new bank account from which to send or request funds.
### List all bank accounts
- [GET /payments/br/bank-accounts/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/listbankaccountbrazil.md): List all bank accounts associated with your Belvo account.
### Activate or deactivate a bank account
- [PATCH /payments/br/bank-accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/patchbankaccountbrazil.md): Updates whether a bank account is active by setting active to true or false.
Setting active to false deactivates the bank account identified in the path. Deactivated accounts are ignored for duplicate checks on the same institution, agency, and account number, which lets you register a new bank account with the same banking details when you need to fix incorrect holder information (such as name or CPF/CNPJ) or similar mistakes from an initial registration.
### Get details about a bank account
- [GET /payments/br/bank-accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/detailbankaccountbrazil.md): Get the details about a specific bank account
## Payment Authorizations (Brazil)
A Payment Authorization is the consent that your user gives you to charge (debit money from) their accounts. You need to perform one Payment Authorization per ‘contract’ (for example, if your company does both electricity and water but they are billed separately, then you will create two separate Payment Authorizations).
Once the user confirms the authorization, you will need to listen for a a `PAYMENT_AUTHORIZATION` webhook with the status set to `AUTHORIZED`. Once you receive this webhook, the authorization process is complete, and you will be able to charge your user.
{% admonition type="info" name="What is a Charge?" %}
A **Charge** represents the individual payment (debit) that your customer will make.
{% /admonition %}
{% admonition type="info" name="Smart Transfers" %}
**Smart Transfers** (`PIX_OF_SMART_TRANSFERS`) let your user authorize you once to move money, on demand, between accounts they hold (for example, from their checking account to their investment account). The beneficiary account must belong to the payer. After the Payment Authorization is `AUTHORIZED`, you create each transfer as a Charge, within the limits that the user approved.
{% /admonition %}
{% admonition type="warning" name="Available payment methods" %}
At present, only Smart Transfers (`PIX_OF_SMART_TRANSFERS`) is available. The Immediate (`PIX_OF_IMMEDIATE`), Scheduled (`PIX_OF_SCHEDULED`), and Pix Automático payment methods aren't available yet.
{% /admonition %}
{% admonition type="danger" name="Version Header" %}
The Payment Authorization resource requires that you send through the `X-Belvo-API-Resource-Version` header set to `Payments-BR.V2`.
{% /admonition %}
### Create a new Payment Authorization
- [POST /payments/br/payment-authorizations/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationbrazil.md): Create a Payment Authorization. The request body depends on the payment_method. At present, only Smart Transfers (PIX_OF_SMART_TRANSFERS) is available. The Immediate (PIX_OF_IMMEDIATE) and Scheduled (PIX_OF_SCHEDULED) payment methods aren't available yet.
For Smart Transfers (PIX_OF_SMART_TRANSFERS):
1. Create the authorization. The response includes payment_method_configuration.authorization_url.
2. Redirect your user to the authorization_url to approve the authorization at their institution.
3. Wait for the PAYMENT_AUTHORIZATION webhook with the status set to AUTHORIZED.
4. Create each transfer with the Create a Charge/createpaymentauthorizationchargebrazil) endpoint.
To create a Smart Transfers authorization against a specific payer account, send payer.account_details (together with the required payer.institution). Your user can then only approve the authorization for that account. If you do not send it, your user selects the account at their institution.
{% admonition type="warning" name="Smart Transfers: same holder only" %}
The beneficiary bank account must be held by the payer (the same CPF, or the same CNPJ root for businesses). Otherwise, the Payment Authorization is created with the FAILED status and the API returns a 500 error.
{% /admonition %}
### List all Payment Authorizations
- [GET /payments/br/payment-authorizations/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationsbrazil.md): List all Payment Authorizations associated with your Belvo account.
### Get details about a Payment Authorization
- [GET /payments/br/payment-authorizations/{payment_authorization_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationbrazil.md): Get the details about a specific Payment Authorization.
### Change a Payment Authorization's beneficiary
- [PATCH /payments/br/payment-authorizations/{payment_authorization_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/patchpaymentauthorizationbrazil.md): Change the beneficiary bank account of a Smart Transfers (PIX_OF_SMART_TRANSFERS) Payment Authorization. Charges that you create after the change are paid to the new bank account. The response is the complete, updated Payment Authorization.
You can only edit a Payment Authorization while its status is AUTHORIZED. Otherwise, you receive a 400 error (The Payment Authorization is not authorized. It cannot be edited.). Payment Authorizations with the PIX_OF_IMMEDIATE or PIX_OF_SCHEDULED payment method cannot be edited.
If the holder name of the new bank account is different from the current one, Belvo also updates the authorization at the payer's institution.
{% admonition type="warning" name="Same holder only" %}
The new beneficiary bank account must have the same holder (holder.identifier) as the current beneficiary bank account. Otherwise, the request fails with a 500 error (unexpected_error) and the beneficiary is not changed. You also receive a 500 error if the institution does not accept the update.
{% /admonition %}
### Cancel a Payment Authorization
- [POST /payments/br/payment-authorizations/{payment_authorization_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationbrazil.md): Cancel a Payment Authorization
We respond with a 204 - No Content and will inform you via webhook that the Payment Authorization was canceled successfully.
{% admonition type="warning" name="Cancellation Time Restrictions (Pix Automático)" %}
For Pix Automático Payment Authorizations, the latest you can cancel a Payment Authorization is by 22:00:00 (GMT-3) on the day before the next Charge date. This restriction doesn't apply to Smart Transfers (see below). If you miss the cutoff time, the Payment Authorization will be cancelled, but the Charge will still be processed.
{% /admonition %}
{% admonition type="info" name="Smart Transfers" %}
You can cancel a Smart Transfers (PIX_OF_SMART_TRANSFERS) Payment Authorization only while its status is AUTHORIZED. Otherwise, you receive a 400 error. After you cancel it, the status changes to REVOKED asynchronously: wait for the PAYMENT_AUTHORIZATION webhook (or check the authorization) to confirm it.
{% /admonition %}
### Create a Charge
- [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationchargebrazil.md): Create a Charge for a Payment Authorization. At present, you can create Charges only for Smart Transfers (PIX_OF_SMART_TRANSFERS) authorizations, and only while the authorization is AUTHORIZED. Otherwise, you receive a 400 error (Payment Authorization is not AUTHORIZED.).
A Charge moves from PENDING to SCHEDULED to SETTLED, or ends as FAILED or CANCELED. Belvo notifies you of status changes by webhook. SETTLED confirms that the payer's account was debited.
{% admonition type="warning" name="Rejected Charges still return 201" %}
If the institution rejects the Charge immediately, the API still responds with 201 - Created, with the Charge status set to FAILED and the reason in status_reason_code. No webhook is sent for this rejection, so always check the status in the response.
{% /admonition %}
### List all Charges for a Payment Authorization
- [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationchargesbrazil.md): List all Charges associated with a Payment Authorization
### Get details about a Charge for a Payment Authorization
- [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationchargebrazil.md): Get the details about a specific Charge associated with a Payment Authorization.
### Retry a failed Charge for a Payment Authorization
- [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/retrypaymentauthorizationchargebrazil.md): {% admonition type="warning" name="Coming Soon" %}
This endpoint isn't available yet. It applies only to Pix Automático Payment Authorizations, which aren't available yet. You cannot use it for Smart Transfers (PIX_OF_SMART_TRANSFERS) Charges.
{% /admonition %}
Retry a failed Charge for a given Payment Authorization.
{% admonition type="warning" name="Additional documentation" %}
Please make sure to read the dedicated Retrying Charges and Linked Charges documentation before attempting to retry a Charge.
{% /admonition %}
{% admonition type="info" name="Not available for Smart Transfers" %}
You cannot retry Charges of Smart Transfers (PIX_OF_SMART_TRANSFERS) authorizations. To transfer the funds again, create a new Charge with the Create a Charge/createpaymentauthorizationchargebrazil) endpoint.
{% /admonition %}
### Cancel a scheduled Charge
- [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationchargebrazil.md): Cancel a scheduled Charge.
We respond with a 204 - No Content and will inform you via webhook that the Charge was canceled successfully.
{% admonition type="warning" name="Cancellation Time Restriction (Pix Automático)" %}
For Pix Automático Charges, the latest you can cancel a scheduled Charge is by 22:00:00 (GMT-3) on the day before the Charge date. If you miss the cutoff time, you will receive an API error from Belvo and the payment will go through. This restriction doesn't apply to Smart Transfers (see below).
{% /admonition %}
{% admonition type="info" name="Smart Transfers" %}
For Smart Transfers (PIX_OF_SMART_TRANSFERS) Charges, you can cancel a Charge when all of the following are true:
- The Charge status is PENDING or SCHEDULED.
- It is before the Charge date (Brasília time): the cutoff is 23:59:59 (GMT-3) on the day before the Charge date. A Charge dated today cannot be canceled.
- The Payment Authorization is AUTHORIZED.
{% /admonition %}
## Charges (Brazil)
You can use the Charges resource to get details over a single charge or to list all charges associated with a payment intent.
### List all charges
- [GET /payments/br/charges/](https://developers.belvo.com/apis/belvoopenapispec/charges-(brazil)/listallchargesbrazil.md): List all the charges related to your account.
### Get details about a Charge
- [GET /payments/br/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/charges-(brazil)/detailchargebrazil.md): Get the details about a specific Charge.
## Payment Intents (Brazil)
A **payment intent** is a single point of access to create payments using any payment method offered by Belvo.
A payment intent captures all payment information (such as the amount to be charged, the description of the payment, the provider, and so on) and guides your customers through the payment flow.
### Create a new Payment Intent
- [POST /payments/br/payment-intents/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/createpaymentintentbrazil.md): Create a Payment Intent.
You can create Payment Intent in the following configurations:
|Beneficiary|Customer (Payer)|Example|
|---|---|---|
|Pix Key|Already registered with Belvo|Pix Key (With Existing Customer)|
|Pix Key|Register with Belvo at time of Payment Intent request|Pix Key (With New Customer)|
|Bank Account (Already Registered)|Already Registered |Bank Account (With Existing Customer)|
|Bank Account (Already Registered)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer)|
|Bank Account (Register at time of Payment Intent request)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer and Beneficiary Bank Account)|
{% admonition type="warning" name="Pix Payments" %}
When you create Payment Intents using a Pix Key, you have to make a PATCH Complete a Payment Intent request to complete the Payment Intent creation.
{% /admonition %}
### List all payment intents
- [GET /payments/br/payment-intents/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/listpaymentintentsbrazil.md): List all payment intents associated with your Belvo account.
### Complete a payment intent
- [PATCH /payments/br/payment-intents/{id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/patchpaymentintentbrazil.md): Complete a new payment intent.
### Get details about a payment intent
- [GET /payments/br/payment-intents/{id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/detailpaymentintentbrazil.md): Get the details about a specific payment intent.
### Cancel a scheduled payment intent
- [POST /payments/br/payment-intents/{id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/cancelpaymentintentbrazil.md): Cancel a scheduled (one-off) payment intent.
We respond with a 204 - No Content and will inform you via webhook that the payment intent was canceled successfully.
> Note: The latest you can cancel a scheduled payment intent is by 23:59:00 (GMT-3) on the day before the scheduled payment date.
### List all charges for a payment intent
- [GET /payments/br/payment-intents/{payment_intent_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/listchargesbrazil.md): List all charges associated with a payment intent.
### Get details about a charge for a payment intent
- [GET /payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/detailchargesbrazil.md): Get the details about a specific charge associated with a payment intent.
### Cancel a scheduled charge
- [POST /payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/cancelchargebrazil.md): Cancel a scheduled charge.
We respond with a 204 - No Content and will inform you via webhook that the charge was canceled successfully.
> Note: The latest you can cancel a scheduled charge is by 23:59:00 (GMT-3) on the day before the scheduled payment date.
## Biometric payments Widget Access Token (Brazil)
Use the Biometric payments widget token request to create an access token for Biometric payments.
### Generate a payment widget access token
- [POST /payments/br/token/](https://developers.belvo.com/apis/belvoopenapispec/biometric-payments-widget-access-token-(brazil)/generatepaymentwidgetaccesstoken.md): Generate a payment widget access token for the Biometric payments enrollment or payment process.
## Enrollments (Brazil)
### Enroll a new user device
- [POST /payments/br/enrollments/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/createenrollmentbrazil.md): ## ▶️ Usage
With the Enroll a new user device method, you can begin the enrollment process for a new device to allow for Biometric payments.
> 🚧 Create a customer first
>
> Before you can enroll a user device, you must first create a customer.
### List enrollments
- [GET /payments/br/enrollments/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/listenrollmentsbrazil.md): ## ▶️ Usage
With the List Enrollments method, you can:
1. (Recommended) List enrollments related to a specific CPF (using the customer__identifier query parameter).
2. List enrollments related to a specific customer.id and institution.id (using the customer and institution query parameters).
3. List enrollments according to a specific status (using the status query parameter).
4. [Not Recommended] List all enrollements related to your Belvo account (without using any query parameters).
## 🔦 Filtering Responses
Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.
## 📖 Pagination
This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
### Get details about an enrollment
- [GET /payments/br/enrollments/{enrollment_id}/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/detailenrollmentbrazil.md): Get details regarding a specific device enrollment.
### Complete enrollment after redirection
- [POST /payments/br/enrollments/complete-redirection/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/completeenrollmentredirectionbrazil.md): ## ▶️ Usage
Use this endpoint to complete the enrollment process after the user is redirected back from the institution. The request body should match the parameters received in the callback URL, either for a successful or error callback.
## Payment Transactions (Brazil)
Each time you receive an inflow payment from your customer, a **transaction** is created in the Belvo database.
You can use the Payment Transactions resource in order to get useful information about a transaction as well as the specific charge associated with it.
### List all payment transactions
- [GET /payments/br/transactions/](https://developers.belvo.com/apis/belvoopenapispec/payment-transactions-(brazil)/listpaymenttransactionsbrazil.md): List all payment transactions associated with your Belvo account.
### Get details about a payment transaction
- [GET /payments/br/transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-transactions-(brazil)/detailpaymenttransactionsbrazil.md): Get the details about a specific payment transaction.
## Collection Instructions (Brazil)
{% admonition type="info" name="Beta" %}
Smart Collections is currently in Beta. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}
A collection instruction tells Belvo which amounts you want to collect from a user, and when. It is the first phase of Smart Collections in Brazil.
You create an instruction for a user's Open Finance Data Aggregation Link, with one or more **items**. Each item has an `amount` and one or more **collection windows** (`collection_policies`). While a window is open, Belvo checks the balances of the user's accounts several times a day. When one account has enough balance for an item, Belvo sends you the `item_ready_to_charge` webhook, and you create the Charge yourself using Payments (Brazil).
These endpoints use your Belvo API keys (`secretId` and `secretPassword`), like the rest of the aggregation API. They don't require a version header.
For the statuses, the webhook, and the full flow, see the Smart Collections statuses and webhooks article.
### Create a collection instruction
- [POST /api/collection-instructions/](https://developers.belvo.com/apis/belvoopenapispec/collection-instructions-(brazil)/createcollectioninstructionbrazil.md): Create a collection instruction for a user's Link. While an item's collection window is open, Belvo checks the balances of the user's accounts several times a day. When one account has at least the item's amount plus BRL 0.01, Belvo sets the item to CHARGE_SETTLED and sends you the item_ready_to_charge webhook. You then create the Charge yourself, using Payments (Brazil). For every item status and the webhook payload, see the Smart Collections statuses and webhooks article.
Before you send the request, check that:
- The link_id is an active, confirmed Link of your organization, with exactly one data consent.
- Every item has at least one collection window that ends in the future. If one item doesn't, Belvo rejects the whole request.
- Each policy amount is the same as its item's amount. Belvo doesn't use the policy amount yet.
This request is not idempotent, and external_id is not checked for uniqueness. If you retry after a timeout, first list your collection instructions to check whether the first request created one.
Errors: Belvo returns a 400 error only for problems with link_id or a body that is not valid JSON. Any other problem returns a 500 error, including a body that doesn't match the schema, an item with no window that ends in the future, a Link that doesn't have exactly one data consent, and a failure to read the Link's accounts.
### List collection instructions
- [GET /api/collection-instructions/](https://developers.belvo.com/apis/belvoopenapispec/collection-instructions-(brazil)/listcollectioninstructionsbrazil.md): List the collection instructions of your organization. The response is an array of summaries without the items. To see the items and their statuses, get the instruction's details.
The response is not paginated: it returns every instruction that matches your filters, in no guaranteed order. Use status, consent_id, created_after, and created_before to keep the response small. Belvo ignores any other query parameter.
Errors: A filter value that is not valid (for example, an unknown status or a date that is not YYYY-MM-DD) returns a 500 error.
### Get a collection instruction's details
- [GET /api/collection-instructions/{instruction_id}/](https://developers.belvo.com/apis/belvoopenapispec/collection-instructions-(brazil)/detailcollectioninstructionbrazil.md): Get a collection instruction with all of its items and their collection windows. Use it to check each item's status, for example when you miss an item_ready_to_charge webhook or to find items that ended as POLICY_EXPIRED, CHARGE_REJECTED, or FAILED (Belvo sends no webhook for these statuses).
The instruction's own status stays PROCESSING until you cancel it, even after every item reaches a final status.
Errors: An instruction_id that doesn't exist or doesn't belong to your organization returns a 500 error. An instruction_id that is not a UUID returns a 404 error.
### Cancel a collection instruction
- [PATCH /api/collection-instructions/{instruction_id}/](https://developers.belvo.com/apis/belvoopenapispec/collection-instructions-(brazil)/patchcollectioninstructionbrazil.md): Cancel a collection instruction. Send the request without a body. Belvo sets the instruction to CANCELLED and cancels every item that is still PENDING or PROCESSING. Items that already reached a final status, such as CHARGE_SETTLED or COMPLETED, keep their status. Cancelling cannot be undone.
To stop monitoring only one item, cancel the item instead (PATCH /api/collection-instructions/{instruction_id}/items/{item_id}/).
Belvo doesn't check the instruction's current status, so cancelling an instruction that is already CANCELLED returns 200 again.
Errors: An instruction_id that doesn't exist or doesn't belong to your organization returns a 500 error. An instruction_id that is not a UUID returns a 404 error.
### Cancel a collection instruction item
- [PATCH /api/collection-instructions/{instruction_id}/items/{item_id}/](https://developers.belvo.com/apis/belvoopenapispec/collection-instructions-(brazil)/patchcollectioninstructionitembrazil.md): Cancel one item of a collection instruction. Send the request without a body. Belvo sets the item to CANCELLED and stops checking balances for it. The instruction and its other items are not changed, even if this was the last active item.
You can only cancel an item while it is PENDING or PROCESSING.
Errors: Belvo returns a 500 error when the instruction or the item doesn't exist, the item doesn't belong to the instruction, the instruction doesn't belong to your organization, or the item isn't in a status that allows this operation. An ID that is not a UUID returns a 404 error.
### Mark a collection instruction item as complete
- [PATCH /api/items/complete/](https://developers.belvo.com/apis/belvoopenapispec/collection-instructions-(brazil)/patchcollectioninstructionitemcompletebrazil.md): Mark an item as complete when you no longer need Belvo to monitor it, for example because the user paid the amount outside Belvo. Belvo sets the item to COMPLETED and stops checking balances for it.
Identify the item with exactly one of item_id or external_id. We recommend item_id: Belvo searches external_id across all the items of your organization, and the request fails if more than one item has the same value.
You can only mark an item as complete while it is PENDING. An item that is PROCESSING (a balance check is running) or already in a final status, including CHARGE_SETTLED, can't be marked as complete.
Errors: Belvo returns a 400 error only when the body is not valid JSON. It returns a 500 error when you send both or neither of item_id and external_id, when no item of your organization matches, when more than one item has the external_id, or when the item isn't in a status that allows this operation.