{ "openapi": "3.0.2", "info": { "title": "Belvo API Docs", "version": "1.223.0", "description": "# Introduction\n\nReach 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:\n\n## Available Information and Payment Methods\n\nBelvo 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.\n\nThrough our API, you can access:\n\n- Banking Information in Brazil\n- Employment Information in Brazil\n- Employment Information in Mexico\n- Fiscal Information in Mexico\n- Fiscal Information in Chile\n\nYou can also use our API to make payments in:\n\n- Brazil\n- Mexico\n\n## Data Dictionaries\n\nIf you woud like the response documentation in Excel or CSV form, please download them from our public GitHub Reposiitory: Belvo Open Finance Data Dictionaries. \n\nOur EXCEL and CSV files are additionally localized into Spanish and Portuguese (Brazil).\n\n\n## Environments\n\nWe currently offer two environments: sandbox and production.\n\n### Sandbox\n\nAvailable for:\n\n- 🟢 Aggregation and Enrichment\n- ⚪️ Payment Initiation\n\nUse 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!\n\nAll 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.\n\n\n### Production\n\nAvailable for:\n\n- 🟢 Aggregation and Enrichment\n- 🟢 Payment Initiation\n\nAfter 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.\n\nOnce your integration is certified, all you'll need to do is:\n\n - [ ] Request Production API keys (and change your Sandbox API keys in the code to these new ones).\n - [ ] Change the base URL that you make requests to from `sandbox.belvo.com` to `api.belvo.com`.\n - [ ] If you're using webhooks, make sure to set a Production URL for your webhooks.\n\n\n\n## Response codes\n\n\nWe use the following HTTP status code in the response depending on the\nsuccess or failure:\n\n\n| Status Code | Description |\n|-----------|-------|\n| `200` | ✅ **Success** - The content is available in the response body. |\n| `201` | ✅ **Success** - The content was created successfully on Belvo. |\n| `204` | ✅ **Success** - No content to return. |\n| `400` | ❌ **Bad Request Error** - Request returned an error, detail in the content.|\n| `401` | ❌ **Unauthorized** - The Belvo credentials provided are not valid.|\n| `404` | ❌ **Not Found** - The resource you try to access cannot be found.|\n| `405` | ❌ **Method Not Allowed** - The HTTP method you are using is not accepted for this resource.|\n| `408` | ❌ **Request Timeout** - The request timed out and was terminated by the server.|\n| `428` | ❌ **MFA Token Required** - MFA token was required by the institution to connect. |\n| `500` | ❌ **Internal Server Error** - The detail of the error is available in the response body.|\n\n\n## Error handling\n\nBelvo API errors are returned in JSON format. For example, an error might look like this:\n\n\n```json\n[\n {\n \"request_id\": \"a6e1c493d7a29d91aed4338e6fcf077d\",\n \"message\": \"This field is required.\",\n \"code\": \"required\",\n \"field\": \"link\"\n }\n]\n```\n\n\nTypically, an error response will have the following parameters:\n\n- `request_id`: a unique ID for the request, you should share it with the Belvo support team for investigations.\n- `message`: human-readable description of the error.\n- `code`: a unique code for the error. Check the table below to see how to handle each error code.\n- `field` *(optional)*: The specific field in the request body that has an issue.\n\n\n\n### Request identifier\n\nWhen 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.\n\n### Error codes and troubleshooting\n\nFor a full list of errors and how to troubleshoot them, please see our dedicated Error Handling article.\n\n### Retry policy\n\n#### 50x errors\n\nImplement 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).\n\n#### 40x errors\n\nYou should not retry making requests if you receive a 40x response, as this is a client error.\n\nThe 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.\n\n## Deprecated fields\n\nIn 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.\n\n## OpenAPI: required and nullable fields\n\nIn 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`.\n\n> 📘 Info\n> \n> In short, any response parameter marked as required will be returned by our API, but the value can be set to null.", "contact": { "name": "Need help?", "url": "https://developers.belvo.com", "email": "support@belvo.com" }, "x-logo": { "url": "https://files.readme.io/5111448-belvo-for-developers.svg", "altText": "Belvo Logo" } }, "servers": [ { "url": "https://sandbox.belvo.com", "description": "Sandbox" } ], "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Institutions", "description": "An **institution** is an entity that Belvo can access information from. It can be a:\n\n- bank institution, such as Nubank Brazil.\n- fiscal institution, such as the *Servicio de Administración Tributaria (SAT)* in Mexico.\n- employment institutions, such as *Instituto Mexicano del Seguro Social (IMSS)* in Mexico or *Instituto Nacional do Seguro Social (INSS)* in Brazil." }, { "name": "Links", "description": "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.\n\nWe recommend using the Belvo Hosted Widget to manage the connection process." }, { "name": "Consents", "description": "A consent is a permission given by the end user to access their financial data in the Open Finance Network in Brazil." }, { "name": "Accounts", "description": "An **account** is the representation of a bank account inside a financial institution. A user can have one or more accounts in an institution. \n\nFor example, one user (or link) can have a checking account, several credit cards, and a loan account.\n\nQuerying for a user's account information is useful as you can get information regarding:\n\n- what types of accounts the user has.\n- the balance for each account (savings, checking, credit card, loan, and so on).\n- detailed information regarding their credit card spending.\n- the current situation of any loans they may have." }, { "name": "Transactions", "description": "A **transaction** contains the detailed information of each movement inside an account. For example, a purchase at a store or a restaurant." }, { "name": "Owners", "description": "An **owner** represents the person who has access to a Link and is the owner of all the accounts inside the Link.\n\nYou can use this endpoint in order to get useful information about your client, such as:\n\n- their full name\n- key contact information\n- information about the ID document they used when opening the account" }, { "name": "Bills", "description": "A **bill** refers to the credit card bill a user receives for a given account." }, { "name": "Balances", "description": "A balance is the amount of money available in a given bank account (checking or savings) at a given time." }, { "name": "Exchanges", "description": "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." }, { "name": "Employments Brazil", "description": "Our employments resource for Brazil lets you get a comprehensive view of your user's current employment history and salary information.\n\nFor each user, we return the:\n\n- work history (including occupations and employer data)\n- historical and current salary information (per employer)\n\nAt the moment, the employments resource is available for:\n\n- 🇧🇷 Brazil (INSS)" }, { "name": "Employment Records Mexico", "description": "Our employment records resource for Mexico lets you get a comprehensive view of your user’s current social security contributions and employment history.\n\nWith 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:\n\n- personal data\n- work history\n- historical and current daily base salary\n- and more!\n\nAt the moment, the employment records resource is available for:\n\n- 🇲🇽 Mexico (IMSS)\n- 🇲🇽 Mexico (ISSSTE)" }, { "name": "Current Employments Mexico", "description": "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.\n\n## Key Features\n\n- **Real-time Employment Status**: Get up-to-date information about an individual's current employment situation\n- **Current vs Historical**: Unlike Employment Records, this resource focuses specifically on current employment status rather than historical employment data\n- **Comprehensive Employment Details**: When employed, receive detailed information including employer details, salary information, and employment duration\n- **Unemployment Status**: Clear indication when an individual is currently unemployed\n\nWhen an individual is **employed**, you will receive:\n- Personal identification data (name, birth date, NSS, CURP)\n- Current employment status\n- Employer information (name, RFC, ID)\n- Employment location (state)\n- Duration of employment (days employed)\n- Salary information (base and monthly salary)\n" }, { "name": "Incomes", "description": "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.\n\n\n> 📘 Info\n>\n> The incomes resource is **only** available for Checking and Savings accounts associated with banking links." }, { "name": "Recurring Expenses", "description": "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.\n\n> 📘 Info\n>\n> The recurring expenses resource is **only** available for Checking, Savings and Credit Card accounts associated with banking links." }, { "name": "Payment Institutions (Brazil)", "description": "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.\n" }, { "name": "Customers (Brazil)", "description": "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.\n\n{% admonition type=\"info\" name=\"Resource Versioning\" %}\n 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.\n{% /admonition %}\n" }, { "name": "Bank Accounts (Brazil)", "description": "To receive inflow payments to your organization's bank account, you must register the bank accounts (individual and business) using Belvo's Payments API.\n\n- **Individual** bank accounts must be created for each payer (your customer).\n- **Business** bank accounts need to be created for the beneficiary of the payment (your organization).\n\n{% admonition type=\"info\" name=\"Resource Versioning\" %}\n 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.\n{% /admonition %}" }, { "name": "Payment Intents (Brazil)", "description": "\nA **payment intent** is a single point of access to create payments using any payment method offered by Belvo.\n\nA 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.\n" }, { "name": "Payment Authorizations (Brazil)", "description": "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).\n\nOnce 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.\n\n{% admonition type=\"info\" name=\"What is a charge?\" %}\nA **charge** represents the individual payment (debit) that your customer will make.\n{% /admonition %}\n\n{% admonition type=\"danger\" name=\"Version Header\" %}\n The Payment Authorization resource requires that you send through the `X-Belvo-API-Resource-Version` header set to `Payments-BR.V2`.\n{% /admonition %}" }, { "name": "Biometric Pix Widget Access Token (Brazil)", "description": "Use the Biometric Pix Widget Token requests to create a access token for Biometric Payments.\n" }, { "name": "Payment Transactions (Brazil)", "description": "Each time you receive an inflow payment from your customer, a **transaction** is created in the Belvo database.\n\nYou can use the Payment Transactions resource in order to get useful information about a transaction as well as the specific charge associated with it.\n" }, { "name": "Charges (Brazil)", "description": "You can use the Charges resource to get details over a single charge or to list all charges associated with a payment intent.\n" } ], "paths": { "/api/institutions/": { "get": { "tags": [ "Institutions" ], "operationId": "ListInstitutions", "summary": "List institutions", "description": "## ▶️ Usage\n\nWith the List Institutions method, you can:\n\n1. List all institutions Belvo has available.\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/display_name" }, { "$ref": "#/components/parameters/country_code" }, { "$ref": "#/components/parameters/country_code__in" }, { "$ref": "#/components/parameters/resources__allin" }, { "$ref": "#/components/parameters/name" }, { "$ref": "#/components/parameters/name__in" }, { "$ref": "#/components/parameters/status_institutions" }, { "$ref": "#/components/parameters/status__in_institutions" }, { "$ref": "#/components/parameters/type_institutions" }, { "$ref": "#/components/parameters/type__in_institutions" }, { "$ref": "#/components/parameters/website" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of institution objects.", "items": { "$ref": "#/components/schemas/InstitutionPublicApi" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/institutions/{id}/": { "get": { "tags": [ "Institutions" ], "operationId": "DetailInstitution", "summary": "Get an institution's details", "description": "Get the details of a specific institution.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The `institution.id` you want to get detailed information about.", "schema": { "type": "string", "pattern": "[0-9]+" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstitutionPublicApi" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/links/": { "get": { "tags": [ "Links" ], "operationId": "ListLinks", "summary": "List links", "description": "## ▶️ Usage\n\nWith the List Links method, you can:\n\n1. List all links elated to your Belvo account (without using any query parameters).\n2. Get the details of a specific `link.id` (using the `id` query parameter).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/institution" }, { "$ref": "#/components/parameters/institution__in" }, { "$ref": "#/components/parameters/access_mode" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/created_by__not_in" }, { "$ref": "#/components/parameters/external_id" }, { "$ref": "#/components/parameters/external_id__in" }, { "$ref": "#/components/parameters/institution_user_id" }, { "$ref": "#/components/parameters/institution_user_id__in" }, { "$ref": "#/components/parameters/refresh_rate" }, { "$ref": "#/components/parameters/status_links" }, { "$ref": "#/components/parameters/status__in_links" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of link objects.", "items": { "$ref": "#/components/schemas/Link" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Links" ], "operationId": "RegisterLink", "summary": "Register a new link", "description": "## ▶️ Usage\n\nRegister a new link (a connection between your user and their institution) using the Belvo API.\n\n> 👍 We really recommend using our Connect Widget to handle link creation and link status updates.\n\nTo 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.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LinksRequestEmploymentBrazil" }, { "$ref": "#/components/schemas/LinksRequestEmploymentMexico" }, { "$ref": "#/components/schemas/LinksRequestFiscalMexico" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Links" ], "operationId": "PatchLinks", "summary": "Complete a links request", "description": "Used to resume a Link register session that was paused because an MFA token\nwas required by the institution.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/links/{id}/": { "get": { "tags": [ "Links" ], "operationId": "DetailLink", "summary": "Get a link's details", "description": "Get the details of a specific link.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The `link.id` you want to get detailed information about." } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Links" ], "operationId": "ModifyLinkDataRetrieval", "summary": "Modify a link's data retrieval", "description": "Modify the data retrieval settings for a specific link. At present you can:\n\n - Change a link's access mode from `single` to `recurrent` or from `recurrent` to `single`.\n - Modify they `stale_in` period for the link.\n - Modify the historical resources you want to retrieve for the link (`fetch_resources`).\n\n## Changing a link's `access_mode`\n \nWhen 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.\n\n## Modifying `stale_in`\n\nIf 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`.\n\n## Modifying `fetch_resources`\n \nIf 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`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "description": "The `link.id` you want to change the `access_mode`, `stale_in`, or `fetch_resources` for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeAccessMode" } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "put": { "tags": [ "Links" ], "operationId": "UpdateLink", "summary": "Update a link's credentials", "description": "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.\n\n> 👍 Use our Connect Widget\n>\n> We recommend using our Connect Widget to handle updating invalid or token_required links.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The `link.id` you want to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksPutRequest" } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Links" ], "operationId": "DestroyLink", "summary": "Delete a link", "description": "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.\n\n{% admonition type=\"success\" name=\"Use the X-Belvo-Request-Mode: async header\" %}\n 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.\n \n 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.\n{% /admonition %}\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The `link.id` that you want to delete." }, { "name": "X-Belvo-Request-Mode", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "async" ] }, "description": "Set to `async` to enable asynchronous deletion, which bypasses rate limiting. When set, the endpoint returns a `202 Accepted` response with a request ID. You will later receive a webhook notification when the deletion is complete.\n" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "The unique identifier for tracking the async deletion request." } }, "required": [ "request_id" ] } } } }, "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/links/{id}/refresh/": { "post": { "tags": [ "Links" ], "operationId": "RefreshHistoricalDataForLink", "summary": "Trigger a historical update for a link", "description": "{% admonition type=\"warning\" name=\"Concurrent Request Limit\" %}\n 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.\"`.\n{% /admonition %}\n\nUse 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.\n\nOn 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.\n\n{% admonition type=\"info\" name=\"Does not update link definition\" %}\n 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.\n{% /admonition %}\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "description": "The `link.id` you want to refresh." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fetch_resources": { "type": "array", "description": "An array of resources that you would like to receive a historical update for. If you do not specify this field, the historical update will be performed for all resources supported by the institution.\n\n{% admonition type=\"warning\" name=\"Unsupported Resources for a Link\" %}\n If you specify a resource that is not supported by the institution, we return a `400 Bad Request` error, specifying which resources are supported for the given link.\n{% /admonition %}\n", "items": { "type": "string", "description": "A Belvo resource that the institution supports.", "example": "ACCOUNTS" }, "example": [ "ACCOUNTS", "TRANSACTIONS", "OWNERS" ] } } } } } }, "responses": { "202": { "description": "Historical Refresh Request Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique ID for this request. We recommend you store this value to later identify which webhook event relates to an asynchronous request.", "example": "b5d0106ac9cc43d5b36199fe831f6bbe" } }, "required": [ "request_id" ] } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "409": { "$ref": "#/components/responses/409_link_already_refreshed" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/consents/": { "get": { "tags": [ "Consents" ], "operationId": "ListConsents", "summary": "List consents", "description": "## ▶️ Usage\n\nWith the Consents method, you can:\n\n1. List all consents related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/pageSize_query" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/document_number" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of consent objects.", "items": { "$ref": "#/components/schemas/Consents" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/consents/{id}/": { "get": { "tags": [ "Consents" ], "operationId": "DetailConsent", "summary": "Get a consent's details", "description": "Get the details of a specific consent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The `consent.id` you want to get detailed information about." } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consents" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/token/": { "post": { "tags": [ "Widget Access Token" ], "summary": "Generate a widget access token", "operationId": "GenerateWidgetAccessToken", "description": "Generate a widget access token for our Hosted Widget.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WidgetTokenRequestBankingBrazil" }, { "$ref": "#/components/schemas/WidgetTokenRequestEmploymentBrazil" }, { "$ref": "#/components/schemas/WidgetTokenRequestEmploymentMexico" }, { "$ref": "#/components/schemas/WidgetTokenRequestFiscalMexico" } ] } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetToken" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/accounts/": { "get": { "tags": [ "Accounts" ], "operationId": "ListAccounts", "summary": "List accounts", "description": "## ▶️ Usage\n\nWith the List Accounts method, you can:\n \n 1. List accounts related to a specific `link.id` (using the `link` query parameter).\n 2. Get the details of a specific `account.id` (using the `id` query parameter).\n 3. **[Not Recommended]** List all accounts related to your Belvo account (without using any query parameters).\n\n## 🔦 Filtering Responses\n\nPlease 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.\n\n## 📖 Pagination\n\nThis 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.\n \n## 🚨 Deprecated Fields\n\nThis 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/balance__available" }, { "$ref": "#/components/parameters/balance__available__lt" }, { "$ref": "#/components/parameters/balance__available__lte" }, { "$ref": "#/components/parameters/balance__available__gt" }, { "$ref": "#/components/parameters/balance__available__gte" }, { "$ref": "#/components/parameters/balance__available__range" }, { "$ref": "#/components/parameters/balance__current" }, { "$ref": "#/components/parameters/balance__current__lt" }, { "$ref": "#/components/parameters/balance__current__lte" }, { "$ref": "#/components/parameters/balance__current__gt" }, { "$ref": "#/components/parameters/balance__current__gte" }, { "$ref": "#/components/parameters/balance__current__range" }, { "$ref": "#/components/parameters/category" }, { "$ref": "#/components/parameters/category__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/currency" }, { "$ref": "#/components/parameters/currency__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/institution" }, { "$ref": "#/components/parameters/institution__in" }, { "$ref": "#/components/parameters/name_accounts" }, { "$ref": "#/components/parameters/name__icontains" }, { "$ref": "#/components/parameters/number_accounts" }, { "$ref": "#/components/parameters/number__in_accounts" }, { "$ref": "#/components/parameters/public_identification_name" }, { "$ref": "#/components/parameters/public_identification_value" }, { "$ref": "#/components/parameters/type_accounts" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "title": "Accounts (OFDA Brazil)", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of account objects.", "items": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Accounts" ], "operationId": "RetrieveAccounts", "summary": "Retrieve accounts for a link", "description": "Retrieve accounts from an existing link.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "token": { "$ref": "#/components/schemas/token" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" } }, "examples": { "AccountsOfdaChecking": { "$ref": "#/components/examples/AccountsOfdaChecking" }, "AccountsOfdaCreditCard": { "$ref": "#/components/examples/AccountsOfdaCreditCard" }, "AccountsOfdaLoanData": { "$ref": "#/components/examples/AccountsOfdaLoanData" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" } }, "examples": { "AccountsOfdaChecking": { "$ref": "#/components/examples/AccountsOfdaChecking" }, "AccountsOfdaCreditCard": { "$ref": "#/components/examples/AccountsOfdaCreditCard" }, "AccountsOfdaLoanData": { "$ref": "#/components/examples/AccountsOfdaLoanData" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Accounts" ], "operationId": "PatchAccounts", "summary": "Complete an accounts request", "description": "Used to resume an Account retrieve session that was paused because an MFA\ntoken was required by the institution.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" } }, "examples": { "AccountsOfdaChecking": { "$ref": "#/components/examples/AccountsOfdaChecking" }, "AccountsOfdaCreditCard": { "$ref": "#/components/examples/AccountsOfdaCreditCard" }, "AccountsOfdaLoanData": { "$ref": "#/components/examples/AccountsOfdaLoanData" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" } }, "examples": { "AccountsOfdaChecking": { "$ref": "#/components/examples/AccountsOfdaChecking" }, "AccountsOfdaCreditCard": { "$ref": "#/components/examples/AccountsOfdaCreditCard" }, "AccountsOfdaLoanData": { "$ref": "#/components/examples/AccountsOfdaLoanData" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/accounts/{id}/": { "get": { "tags": [ "Accounts" ], "operationId": "DetailAccount", "summary": "Get an account's details", "description": "Get the details of a specific account.\n\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `account.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" }, "examples": { "AccountsOfdaChecking": { "$ref": "#/components/examples/AccountsOfdaCheckingDetail" }, "AccountsOfdaCreditCard": { "$ref": "#/components/examples/AccountsOfdaCreditCardDetail" }, "AccountsOfdaLoanData": { "$ref": "#/components/examples/AccountsOfdaLoanDataDetail" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Accounts" ], "operationId": "DestroyAccount", "summary": "Delete an account", "description": "Delete a specific account from your Belvo account.\n\n{% admonition type=\"danger\" name=\"Rate Limited\" %}\n 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.\n{% /admonition %}\n\n{% admonition type=\"info\" %}\n When you delete an account, all the associated transactions and owner information for that account are also removed.\n{% /admonition %}\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `account.id` you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/balances/": { "get": { "tags": [ "Balances" ], "operationId": "ListBalances", "summary": "List balances", "description": "## ▶️ Usage\n\nWith the List Balances method, you can:\n \n 1. **[Required]** List balances related to a specific `link.id` (using the `link` query parameter).\n 2. **[Highly Recommended]** List balances related to a specific `link.id` and `account.id` (using the `link` and `account` query parameters).\n 2. Get the details of a specific `balance.id` (using the `id` query parameter).\n\n## 🔦 Filtering Responses\n\nPlease 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.\n\n## 📖 Pagination\n\nThis 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.\n \n## 🚨 Deprecated Fields\n\nThis 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/account__in" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/collected_at" }, { "$ref": "#/components/parameters/collected_at__gt" }, { "$ref": "#/components/parameters/collected_at__gte" }, { "$ref": "#/components/parameters/collected_at__lt" }, { "$ref": "#/components/parameters/collected_at__lte" }, { "$ref": "#/components/parameters/collected_at__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "OK - Balances Retrieved", "content": { "application/json": { "schema": { "type": "object", "title": "Balances (OFDA Brazil)", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of balance objects.", "items": { "$ref": "#/components/schemas/BalanceOFDA" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Balances" ], "operationId": "RetrieveBalances", "summary": "Retrieve the current balance for a link", "description": "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.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "account_id": { "$ref": "#/components/schemas/account_id" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "OK - Balance Retrieved (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceOFDA" } } } } }, "201": { "description": "OK - Balance Retrieved (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceOFDA" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/balances/{id}/": { "get": { "tags": [ "Balances" ], "operationId": "DetailBalance", "summary": "Get a balances's details", "description": "Get the details of a specific balance.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `balance.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceOFDA" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/exchanges/": { "get": { "tags": [ "Exchanges" ], "operationId": "ListExchanges", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "List exchanges", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\n## ▶️ Usage\n\nWith the List Exchanges method, you can:\n \n 1. **[Required]** List exchanges related to a specific `link.id` (using the `link` query parameter).\n 2. Get the details of a specific `exchange.id` (using the `id` query parameter).\n\n## 🔦 Filtering Responses\n\nPlease 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.\n\n## 📖 Pagination\n\nThis 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/collected_at" }, { "$ref": "#/components/parameters/collected_at__gt" }, { "$ref": "#/components/parameters/collected_at__gte" }, { "$ref": "#/components/parameters/collected_at__lt" }, { "$ref": "#/components/parameters/collected_at__lte" }, { "$ref": "#/components/parameters/collected_at__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "OK - Exchanges Retrieved", "content": { "application/json": { "schema": { "type": "object", "title": "Exchanges (Brazil)", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of exchange objects.", "items": { "$ref": "#/components/schemas/Exchange" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Exchanges" ], "operationId": "RetrieveExchanges", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Retrieve exchanges for a link", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nRetrieve exchange operations for an existing link. By default, we retrieve exchange data for the last 365 days.\n\n> **Note**: When you retrieve exchanges, we automatically retrieve the exchange history for each exchange operation found.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "date_from": { "type": "string", "format": "date", "description": "The starting date for which you want to retrieve exchange data, in `YYYY-MM-DD` format. If not provided, we retrieve data for the last 365 days.", "example": "2022-01-01" }, "date_to": { "type": "string", "format": "date", "description": "The ending date for which you want to retrieve exchange data, in `YYYY-MM-DD` format. If not provided, we retrieve data up to today.", "example": "2022-12-31" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "OK - Exchanges Retrieved (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Exchange" } } } } }, "201": { "description": "OK - Exchanges Retrieved (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Exchange" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/exchanges/{id}/": { "get": { "tags": [ "Exchanges" ], "operationId": "DetailExchange", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Get an exchange's details", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nGet the details of a specific exchange.\n\n> **Note**: When you delete an exchange, all associated exchange history records are also deleted.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `exchange.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Exchange" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Exchanges" ], "operationId": "DeleteExchange", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Delete an exchange", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nDelete a specific exchange from your Belvo account.\n\n> **Note**: When you delete an exchange, all associated exchange history records are also deleted.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `exchange.id` you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/exchanges/{id}/history/": { "get": { "tags": [ "Exchanges" ], "operationId": "ListExchangeHistory", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "List exchange history for a specific exchange", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nGet the modification history (audit trail) for a specific exchange operation.\n\n## 📖 Pagination\n\nThis 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.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `exchange.id` you want to get the history for.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK - Exchange History Retrieved", "content": { "application/json": { "schema": { "type": "object", "title": "Exchange History (Brazil)", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of exchange history objects.", "items": { "$ref": "#/components/schemas/ExchangeHistory" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/transactions/": { "get": { "tags": [ "Transactions" ], "operationId": "ListTransactions", "summary": "List transactions", "description": "## ▶️ Usage\n\nWith the List Transactions method, you can:\n\n1. **[Required]** List transactions related to a specific `link.id` (using the `link` query parameter).\n2. Filter the returned transactions using query parameters (see the Filtering responses section below).\n3. Get the details of a specific `transaction.id` (using the `id` query parameter along with the `link` query parameter).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/account__in" }, { "$ref": "#/components/parameters/account__balance__available" }, { "$ref": "#/components/parameters/account__balance__available__lt" }, { "$ref": "#/components/parameters/account__balance__available__lte" }, { "$ref": "#/components/parameters/account__balance__available__gt" }, { "$ref": "#/components/parameters/account__balance__available__gte" }, { "$ref": "#/components/parameters/account__balance__available__range" }, { "$ref": "#/components/parameters/account__balance__current" }, { "$ref": "#/components/parameters/account__balance__current__gt" }, { "$ref": "#/components/parameters/account__balance__current__gte" }, { "$ref": "#/components/parameters/account__balance__current__lt" }, { "$ref": "#/components/parameters/account__balance__current__lte" }, { "$ref": "#/components/parameters/account__balance__current__range" }, { "$ref": "#/components/parameters/account_type" }, { "$ref": "#/components/parameters/account_type__in" }, { "$ref": "#/components/parameters/accounting_date" }, { "$ref": "#/components/parameters/accounting_date__gt" }, { "$ref": "#/components/parameters/accounting_date__gte" }, { "$ref": "#/components/parameters/accounting_date__lt" }, { "$ref": "#/components/parameters/accounting_date__lte" }, { "$ref": "#/components/parameters/accounting_date__range" }, { "$ref": "#/components/parameters/amount" }, { "$ref": "#/components/parameters/amount__gt" }, { "$ref": "#/components/parameters/amount__gte" }, { "$ref": "#/components/parameters/amount__lt" }, { "$ref": "#/components/parameters/amount__lte" }, { "$ref": "#/components/parameters/amount__range" }, { "$ref": "#/components/parameters/collected_at" }, { "$ref": "#/components/parameters/collected_at__gt" }, { "$ref": "#/components/parameters/collected_at__gte" }, { "$ref": "#/components/parameters/collected_at__lt" }, { "$ref": "#/components/parameters/collected_at__lte" }, { "$ref": "#/components/parameters/collected_at__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/currency" }, { "$ref": "#/components/parameters/currency__in" }, { "$ref": "#/components/parameters/credit_card_data__bill_name__in" }, { "$ref": "#/components/parameters/reference" }, { "$ref": "#/components/parameters/reference__in" }, { "$ref": "#/components/parameters/status_transactions" }, { "$ref": "#/components/parameters/status__in_transactions" }, { "$ref": "#/components/parameters/type_transactions" }, { "$ref": "#/components/parameters/type__in_transactions" }, { "$ref": "#/components/parameters/value_date" }, { "$ref": "#/components/parameters/value_date__gt" }, { "$ref": "#/components/parameters/value_date__gte" }, { "$ref": "#/components/parameters/value_date__lt" }, { "$ref": "#/components/parameters/value_date__lte" }, { "$ref": "#/components/parameters/value_date__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "title": "Transactions (OFDA Brazil)", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of transaction objects (OFDA Brazil).", "items": { "$ref": "#/components/schemas/TransactionOpenFinanceBrazil" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Transactions" ], "operationId": "RetrieveTransactions", "summary": "Retrieve transactions for a link", "description": "Retrieve transactions for one or more accounts from a specific link.\n\n> 📘 Transaction Periods and Retrieval\n>\n> 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.\n", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for the Retrieve Transactions method.", "required": [ "link", "date_from", "date_to" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "account": { "type": "string", "format": "uuid", "description": "If provided, we return transactions only from this account.", "example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "token": { "$ref": "#/components/schemas/token" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionOpenFinanceBrazil" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionOpenFinanceBrazil" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Transactions" ], "operationId": "PatchTransactions", "summary": "Complete a transactions request", "description": "Used to resume a Transaction retrieve session that was paused because an MFA\ntoken was required by the institution.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionOpenFinanceBrazil" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionOpenFinanceBrazil" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/transactions/{id}/": { "get": { "tags": [ "Transactions" ], "operationId": "DetailTransaction", "summary": "Get a transaction's details", "description": "Get the details of a specific transaction.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `transaction.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionOpenFinanceBrazil" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Transactions" ], "operationId": "DestroyTransaction", "summary": "Delete a transaction", "description": "Delete a specific transaction from your Belvo account.\n\n> ❗️ Rate limited\n>\n> 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.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `transaction.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/bills/": { "get": { "tags": [ "Bills" ], "operationId": "ListBills", "summary": "List bills", "description": "## ▶️ Usage\n\nWith the List Bills method, you can:\n\n1. **[Required]** List bills related to a specific link.id (using the `link` query parameter).\n2. Filter the returned bills using query parameters (see the Filtering responses section below).\n3. Get the details of a specific bill.id (using the `id` query parameter).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/account__in" }, { "$ref": "#/components/parameters/due_date" }, { "$ref": "#/components/parameters/due_date__gt" }, { "$ref": "#/components/parameters/due_date__gte" }, { "$ref": "#/components/parameters/due_date__lt" }, { "$ref": "#/components/parameters/due_date__lte" }, { "$ref": "#/components/parameters/due_date__range" }, { "$ref": "#/components/parameters/collected_at__gt" }, { "$ref": "#/components/parameters/collected_at__gte" }, { "$ref": "#/components/parameters/collected_at__lt" }, { "$ref": "#/components/parameters/collected_at__lte" }, { "$ref": "#/components/parameters/collected_at__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "title": "Bills", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of Bill objects.", "items": { "$ref": "#/components/schemas/Bill" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Bills" ], "operationId": "RetrieveBills", "summary": "Retrieve bills for a link", "description": "Retrieve bills from one or more accounts for a specific link within a\nspecified date range.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Bill" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Bill" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/bills/{id}/": { "get": { "tags": [ "Bills" ], "operationId": "DetailBills", "summary": "Get a bill's details", "description": "Get the details of a specific bill.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `bill.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Bills" ], "operationId": "DestroyBills", "summary": "Delete a bill", "description": "Delete a specific bill from your Belvo account.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `bill.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/owners/": { "get": { "tags": [ "Owners" ], "operationId": "ListOwners", "summary": "List owners", "description": "## ▶️ Usage\n\nWith the List Owners method, you can:\n\n1. List owners related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `owners.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all owners related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n\n## 🚨 Deprecated Fields\n\nThis 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/email" }, { "$ref": "#/components/parameters/display_name__icontains" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of either:\n\n - Owner Individual (OFDA Brazil) objects\n - Owner Business (OFDA Brazil) objects\n - Owner Standard (Multi-Region) objects\n \n > 🚧 One schema type per response\n >\n > The response will contain an array of **one** of the schema types described above. In other words, there **will not** be a mix of schema types in the response.\n", "items": { "oneOf": [ { "$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil" }, { "$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil" }, { "$ref": "#/components/schemas/Owner" } ] } } } } ] }, "examples": { "OwnerIndividualOfdaPaginated": { "$ref": "#/components/examples/OwnerOfdaIndividualPaginated" }, "OwnerBusinessOfdaPaginated": { "$ref": "#/components/examples/OwnerOfdaBusinessPaginated" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Owners" ], "operationId": "RetrieveOwners", "summary": "Retrieve owners for a link", "description": "Retrieve owner information from a specific link.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "token": { "$ref": "#/components/schemas/token" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil" }, { "$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil" }, { "$ref": "#/components/schemas/Owner" } ] } }, "examples": { "OwnerIndividualOfda": { "$ref": "#/components/examples/OwnerOfdaIndividual" }, "OwnerBusinessOfda": { "$ref": "#/components/examples/OwnerOfdaBusiness" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil" }, { "$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil" }, { "$ref": "#/components/schemas/Owner" } ] } }, "examples": { "OwnerIndividualOfda": { "$ref": "#/components/examples/OwnerOfdaIndividual" }, "OwnerBusinessOfda": { "$ref": "#/components/examples/OwnerOfdaBusiness" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Owners" ], "operationId": "PatchOwners", "summary": "Complete an owners request", "description": "Used to resume an Owner retrieve session that was paused because an MFA\ntoken was required by the institution.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil" }, { "$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil" } ] } }, "examples": { "OwnerIndividualOfda": { "$ref": "#/components/examples/OwnerOfdaIndividual" }, "OwnerBusinessOfda": { "$ref": "#/components/examples/OwnerOfdaBusiness" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil" }, { "$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil" } ] } }, "examples": { "OwnerIndividualOfda": { "$ref": "#/components/examples/OwnerOfdaIndividual" }, "OwnerBusinessOfda": { "$ref": "#/components/examples/OwnerOfdaBusiness" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/owners/{id}/": { "get": { "tags": [ "Owners" ], "operationId": "DetailOwner", "summary": "Get an owner's details", "description": "Get the details of a specific owner.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `owner.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OwnerIndividualOpenFinanceBrazil" }, { "$ref": "#/components/schemas/OwnerBusinessOpenFinanceBrazil" }, { "$ref": "#/components/schemas/Owner" } ] }, "examples": { "OwnerIndividualOfdaDetails": { "$ref": "#/components/examples/OwnerOfdaIndividuaDetail" }, "OwnerBusinessOfdaDetails": { "$ref": "#/components/examples/OwnerOfdaBusinessDetail" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" } } }, "delete": { "tags": [ "Owners" ], "operationId": "DestroyOwner", "summary": "Delete an owner", "description": "Delete a specific owner from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `owner.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/investments/": { "get": { "tags": [ "Investments Brazil" ], "operationId": "ListInvestmentsBrazil", "summary": "List investments", "description": "## ▶️ Usage\n\nWith the List Investments method, you can:\n\n1. **[Required]** List investments related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `investment.id` (using the `id` query parameter).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/pageSize_query" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/type_investments" }, { "$ref": "#/components/parameters/type__in_investments" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of investment objects.", "items": { "$ref": "#/components/schemas/InvestmentBrazil" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Investments Brazil" ], "operationId": "RetrieveInvestmentsBrazil", "summary": "Retrieve investments for a link", "description": "Retrieve investments for an existing link.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvestmentBrazil" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvestmentBrazil" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/investments/{id}/": { "get": { "tags": [ "Investments Brazil" ], "operationId": "DetailInvestmentBrazil", "summary": "Get an investment's details", "description": "Get the details of a specific investment.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `investment.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestmentBrazil" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Investments Brazil" ], "operationId": "DestroyInvestmentBrazil", "summary": "Delete an investment", "description": "Delete a specific investment from your Belvo account.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `investment.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/investment-transactions/": { "get": { "tags": [ "Investment Transactions Brazil" ], "operationId": "ListInvestmentTransactionsBrazil", "summary": "List investment transactions", "description": "## ▶️ Usage\n\nWith the List Investment Transactions method, you can:\n\n1. **[Required]** List investment transactions related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `investment-transaction.id` (using the `id` query parameter).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/pageSize_query" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/type_investments" }, { "$ref": "#/components/parameters/type__in_investments" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of investment transaction objects.", "items": { "$ref": "#/components/schemas/InvestmentTransactionBrazil" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Investment Transactions Brazil" ], "operationId": "RetrieveInvestmentTransactionsBrazil", "summary": "Retrieve investments for a link", "description": "Retrieve investments for an existing link.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The request body for investment transactions in Brazil.", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvestmentTransactionBrazil" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvestmentTransactionBrazil" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/investment-transactions/{id}/": { "get": { "tags": [ "Investment Transactions Brazil" ], "operationId": "DetailInvestmentTransactionBrazil", "summary": "Get an investment transaction's details", "description": "Get the details of a specific investment transaction.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `investment-transaction.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestmentTransactionBrazil" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Investment Transactions Brazil" ], "operationId": "DestroyInvestmentTransactionBrazil", "summary": "Delete an investment transaction", "description": "Delete a specific investment transaction from your Belvo account.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `investment-transaction.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/employment-records/": { "get": { "tags": [ "Employment Records Mexico" ], "operationId": "ListEmploymentRecords", "summary": "List employment records", "description": "## ▶️ Usage\n\nWith the List Employment Records method, you can:\n\n1. List employment records related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `employment-record.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all employment records related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/internal_identification" }, { "$ref": "#/components/parameters/internal_identification__in" }, { "$ref": "#/components/parameters/collected_at" }, { "$ref": "#/components/parameters/collected_at__gt" }, { "$ref": "#/components/parameters/collected_at__gte" }, { "$ref": "#/components/parameters/collected_at__lt" }, { "$ref": "#/components/parameters/collected_at__lte" }, { "$ref": "#/components/parameters/collected_at__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of employment record objects.", "items": { "$ref": "#/components/schemas/EmploymentRecord" } } } } ] }, "examples": { "IMSS": { "$ref": "#/components/examples/imss_example_paginated" }, "ISSSTE": { "$ref": "#/components/examples/issste_example_paginated" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Employment Records Mexico" ], "operationId": "RetrieveEmploymentRecordDetails", "summary": "Retrieve employment record details", "description": "Retrieve employment record details for an individual.\n", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmploymentRecord" } }, "examples": { "IMSS": { "$ref": "#/components/examples/imss_example" }, "ISSSTE": { "$ref": "#/components/examples/issste_example" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmploymentRecord" } }, "examples": { "IMSS": { "$ref": "#/components/examples/imss_example" }, "ISSSTE": { "$ref": "#/components/examples/issste_example" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/employment-records/{id}/": { "get": { "tags": [ "Employment Records Mexico" ], "operationId": "DetailEmploymentRecord", "summary": "Get an employment record's details", "description": "Get the details of a specific employment record.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `employment-record.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentRecord" }, "examples": { "IMSS": { "$ref": "#/components/examples/imss_example_detail" }, "ISSSTE": { "$ref": "#/components/examples/issste_example_detail" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Employment Records Mexico" ], "operationId": "DestroyEmploymentRecord", "summary": "Delete an employment record", "description": "Delete a specific employment record from your Belvo account.\n\n> ❗️ Rate limited\n>\n> 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.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `employment-record.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/mx/current-employments/": { "get": { "tags": [ "Current Employments Mexico" ], "summary": "List current employments", "operationId": "ListCurrentEmployments", "description": "## ▶️ Usage\n\nWith the List Current Employments method, you can:\n\n1. List current employments related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `current-employment.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all current employments related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/collected_at" }, { "$ref": "#/components/parameters/collected_at__gt" }, { "$ref": "#/components/parameters/collected_at__gte" }, { "$ref": "#/components/parameters/collected_at__lt" }, { "$ref": "#/components/parameters/collected_at__lte" }, { "$ref": "#/components/parameters/collected_at__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentEmployment" } } } } ] } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Current Employments Mexico" ], "summary": "Retrieve current employments", "description": "Retrieve current employment information for a specific `link.id`.\n", "operationId": "RetrieveCurrentEmployments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when existing)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentEmployment" } } } } }, "201": { "description": "Created (when new)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentEmployment" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/mx/current-employments/{id}/": { "get": { "tags": [ "Current Employments Mexico" ], "summary": "Get current employment details", "description": "Get the details of a specific current employment record.\n", "operationId": "getCurrentEmploymentDetails", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the current employment record.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentEmployment" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Current Employments Mexico" ], "summary": "Delete current employment", "description": "Delete a specific current employment record from your Belvo account.\n", "operationId": "deleteCurrentEmployment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the current employment record to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/employments/": { "get": { "tags": [ "Employments Brazil" ], "operationId": "ListEmploymentsBrazil", "summary": "List employments", "description": "## ▶️ Usage\n\nWith the List Employments method, you can:\n\n1. **[Required]** List employments related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `employment.id` (using the `id` query parameter).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link__required" }, { "$ref": "#/components/parameters/pageSize_query" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/start_date" }, { "$ref": "#/components/parameters/start_date__gt" }, { "$ref": "#/components/parameters/start_date__gte" }, { "$ref": "#/components/parameters/start_date__lt" }, { "$ref": "#/components/parameters/start_date__lte" }, { "$ref": "#/components/parameters/start_date__range" }, { "$ref": "#/components/parameters/end_date" }, { "$ref": "#/components/parameters/end_date__gt" }, { "$ref": "#/components/parameters/end_date__gte" }, { "$ref": "#/components/parameters/end_date__lt" }, { "$ref": "#/components/parameters/end_date__lte" }, { "$ref": "#/components/parameters/end_date__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of employment objects.", "items": { "$ref": "#/components/schemas/EmploymentBrazil" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Employments Brazil" ], "operationId": "RetrieveEmploymentsBrazil", "summary": "Retrieve employments for a link", "description": "Retrieve employments from an existing link.\n", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body to retrieve employment information from Brazil's INSS.", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmploymentBrazil" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmploymentBrazil" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/br/employments/{id}/": { "get": { "tags": [ "Employments Brazil" ], "operationId": "DetailEmploymentBrazil", "summary": "Get an employment's details", "description": "Get the details of a specific employment.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `employment.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentBrazil" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Employments Brazil" ], "operationId": "DestroyEmploymentBrazil", "summary": "Delete an employment", "description": "Delete a specific employment from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `employment.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/incomes/": { "get": { "tags": [ "Incomes" ], "operationId": "ListIncomes", "summary": "List incomes", "description": "## ▶️ Usage\n\nWith the List Incomes method, you can:\n\n1. List incomes related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `income.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all incomes related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/account__in" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of income objects.", "items": { "$ref": "#/components/schemas/Income" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Incomes" ], "operationId": "RetrieveIncome", "summary": "Retrieve incomes for a link", "description": "Retrieve income insights for checking and savings accounts from a\nspecific link. You can receive insights for a period of up to 365 days,\ndepending on the transaction history available for each institution.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "allowed_income_types": { "type": "array", "description": "The categories of the incomes you want to get information for.", "items": { "$ref": "#/components/schemas/EnumInvoiceAllowedIncomeTypesRequest" } }, "minimum_confidence_level": { "$ref": "#/components/schemas/EnumIncomeMinimumConfidenceLevelRequest" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "token": { "$ref": "#/components/schemas/token" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Income" } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Income" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Incomes" ], "operationId": "PatchIncomes", "summary": "Complete an incomes request", "description": "Used to resume an Income retrieve session that was paused because an MFA\ntoken was required by the institution.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Income" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Income" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/incomes/{id}/": { "get": { "tags": [ "Incomes" ], "operationId": "DetailIncome", "summary": "Get an income's details", "description": "Get the details of a specific income.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `income.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Income" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Incomes" ], "operationId": "DestroyIncomes", "summary": "Delete an income", "description": "Delete a specific income from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "the `income.id` that you want to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/recurring-expenses/": { "get": { "tags": [ "Recurring Expenses" ], "operationId": "ListRecurringExpenses", "summary": "List recurring expenses", "description": "## ▶️ Usage\n\nWith the List Recurring Expenses method, you can:\n\n1. List recurring expenses related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `recurring-expense.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all recurring expenses related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/account__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of recurring expense objects.", "items": { "$ref": "#/components/schemas/RecurringExpenses" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Recurring Expenses" ], "operationId": "RetrieveRecurringExpenses", "summary": "Retrieve recurring expenses for a link", "description": "Retrieve recurring expense insights for checking and savings accounts from a\nspecific link. You can receive insights for a period of up to 365 days,\ndepending on the transaction history available for each institution.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for the Retrieve Recurring Expenses method.", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "token": { "$ref": "#/components/schemas/token" }, "save_data": { "$ref": "#/components/schemas/save_data" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" } } } } } }, "responses": { "200": { "description": "Ok (when save_data=false)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringExpenses" } } } } }, "201": { "description": "Created (when save_data=true)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringExpenses" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Recurring Expenses" ], "operationId": "PatchRecurringExpenses", "summary": "Complete a recurring expenses request", "description": "Used to resume an Recurring Expenses retrieve session that was paused because an MFA\ntoken was required by the institution.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when save_data=false)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringExpenses" } } } } }, "201": { "description": "Created (when save_data=true)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringExpenses" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/recurring-expenses/{id}/": { "get": { "tags": [ "Recurring Expenses" ], "operationId": "DetailRecurringExpense", "summary": "Get a recurring expense's details", "description": "Get the details of a specific recurring expense.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `recurring-expenses.id` you want to get detailed information about.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringExpenses" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Recurring Expenses" ], "operationId": "DestroyRecurringExpense", "summary": "Delete a recurring expense", "description": "Delete a specific recurring expense from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `recurring-expenses.id` that you want to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/risk-insights/": { "get": { "tags": [ "Risk Insights" ], "operationId": "ListRiskInsights", "summary": "List risk insights", "description": "## ▶️ Usage\n\nWith the List Risk Insights method, you can:\n\n1. List risk insights related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `risk-insight.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all risk insights related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/account__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of risk insights objects.", "items": { "$ref": "#/components/schemas/RiskInsights" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Risk Insights" ], "operationId": "RetrieveRiskInsights", "summary": "Retrieve risk insights for a link", "description": "Request the risk insights for a given link ID.\n\n\nIf 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).\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "token": { "$ref": "#/components/schemas/token" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when save_data=false)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskInsights" } } } }, "201": { "description": "Created (when save_data=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskInsights" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Risk Insights" ], "operationId": "PatchRiskInsights", "summary": "Complete a risk insights request", "description": "Used to resume an Risk insights retrieve session that was paused because an MFA\ntoken was required by the institution.\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when save_data=false)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RiskInsights" } } } } }, "201": { "description": "Created (when save_data=true)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RiskInsights" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/risk-insights/{id}/": { "get": { "tags": [ "Risk Insights" ], "operationId": "DetailRiskInsights", "summary": "Get a risk insight's details", "description": "Get the details of a specific risk insight.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `risk-insights.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RiskInsights" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Risk Insights" ], "operationId": "DestroyRiskInsights", "summary": "Delete a risk insight", "description": "Delete a specific risk insight from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `risk-insights.id` that you want to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/employment-metrics/": { "get": { "tags": [ "Employment Metrics" ], "operationId": "ListEmploymentMetrics", "summary": "List employment metrics", "description": "## ▶️ Usage\n\nWith the List Employment Metrics method, you can:\n\n1. List employment metrics related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `employment-metric.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all employment metrics related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of employment metric objects.", "items": { "$ref": "#/components/schemas/EmploymentMetric" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Employment Metrics" ], "operationId": "RetrieveEmploymentMetricDetails", "summary": "Retrieve employment metrics", "description": "Retrieve employment metrics for an individual.\n\n> **Note:** Before requesting employment metrics, make sure to first make a POST Retrieve employment record details request. \n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "reference_date": { "type": "string", "format": "date", "description": "The date until which you want the employment metrics to be calculated, in `YYYY-MM-DD` format. For example, if you do not want to calculate employment metrics for all of 2023, the add `2022-12-31` as the `reference_date`.\n\nIf you do not provide a `reference_date`, we perform calcualtions up until the date you make the request.\n\n**Note:** All calculations will be relative to this date.\n", "example": "2023-03-01" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentMetric" } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentMetric" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/employment-metrics/{id}/": { "get": { "tags": [ "Employment Metrics" ], "operationId": "DetailEmploymentMetric", "summary": "Get an employment metric's details", "description": "Get the details of a specific employment metric.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `employment-metric.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentMetric" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Employment Metrics" ], "operationId": "DestroyEmploymentMetric", "summary": "Delete an employment metric", "description": "Delete a specific employment metric from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `employment-metric.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/financial-statements/": { "get": { "tags": [ "Financial Statements" ], "operationId": "ListFinancialStatements", "summary": "List Financial Statements", "description": "## ▶️ Usage\n\nWith the List Financial Statements method, you can:\n\n1. List financial statements related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `financial-statement.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all financial statements related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of tax compliance status objects.", "items": { "$ref": "#/components/schemas/FinancialStatement" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Financial Statements" ], "operationId": "RetrieveFinancialStatements", "summary": "Retrieve Financial Statements for a link", "description": "Retrieve the Financial Statements information for a specific fiscal link.", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialStatement" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialStatement" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/financial-statements/{id}/": { "get": { "tags": [ "Financial Statements" ], "operationId": "DetailFinancialStatement", "summary": "Get a Financial Statement's details", "description": "Get the details of a specific Financial Statement.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `financial-statement.id` you want to get detailed information\nabout.\n", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialStatement" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Financial Statements" ], "operationId": "DestroyFinancialStatement", "summary": "Delete a Financial Statement", "description": "Delete a specific Financial Statement from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `financial-statement.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/invoices/": { "get": { "tags": [ "Invoices" ], "operationId": "ListInvoices", "description": "## ▶️ Usage\n\nWith the List Invoices method, you can:\n\n1. List invoices related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `invoice.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all invoices related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n\n## 🚨 Deprecated Fields\n\nThis 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.\n", "summary": "List invoices", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/invoice_date" }, { "$ref": "#/components/parameters/invoice_date__lt" }, { "$ref": "#/components/parameters/invoice_date__lte" }, { "$ref": "#/components/parameters/invoice_date__gt" }, { "$ref": "#/components/parameters/invoice_date__gte" }, { "$ref": "#/components/parameters/invoice_date__range" }, { "$ref": "#/components/parameters/invoice_identification" }, { "$ref": "#/components/parameters/invoice_identification__in" }, { "$ref": "#/components/parameters/status_invoice" }, { "$ref": "#/components/parameters/status__in_invoice" }, { "$ref": "#/components/parameters/type_invoice" }, { "$ref": "#/components/parameters/type__in_invoice" }, { "$ref": "#/components/parameters/total_amount" }, { "$ref": "#/components/parameters/total_amount__lt" }, { "$ref": "#/components/parameters/total_amount__lte" }, { "$ref": "#/components/parameters/total_amount__gt" }, { "$ref": "#/components/parameters/total_amount__gte" }, { "$ref": "#/components/parameters/total_amount__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of invoice objects.", "items": { "$ref": "#/components/schemas/InvoiceWithIdSat" } } } } ] }, "examples": { "InvoiceIngresso": { "$ref": "#/components/examples/InvoiceIngresoPaginated" }, "InvoicePago": { "$ref": "#/components/examples/InvoicePagoPaginated" }, "InvoiceNomina": { "$ref": "#/components/examples/InvoiceNominaPaginated" }, "InvoiceEgreso": { "$ref": "#/components/examples/InvoiceEgresoPaginated" }, "InvoiceTraslado": { "$ref": "#/components/examples/InvoiceTrasladoPaginated" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Invoices" ], "operationId": "RetrieveInvoices", "summary": "Retrieve invoices for a link", "description": "Retrieve invoice information from a specific fiscal link.\n\n> 📘 Info\n>\n> 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.\n\n> 🚧 Warning\n>\n> This resource may return deprecated fields. Please check the response documentation for more information.\n", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date_from", "date_to", "link", "type" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "type": { "$ref": "#/components/schemas/EnumInvoiceType" }, "attach_xml": { "$ref": "#/components/schemas/attach_xml" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceWithIdSat" } }, "examples": { "InvoiceIngresso": { "$ref": "#/components/examples/InvoiceIngreso" }, "InvoicePago": { "$ref": "#/components/examples/InvoicePago" }, "InvoiceNomina": { "$ref": "#/components/examples/InvoiceNomina" }, "InvoiceEgreso": { "$ref": "#/components/examples/InvoiceEgreso" }, "InvoiceTraslado": { "$ref": "#/components/examples/InvoiceTraslado" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceWithIdSat" } }, "examples": { "InvoiceIngresso": { "$ref": "#/components/examples/InvoiceIngreso" }, "InvoicePago": { "$ref": "#/components/examples/InvoicePago" }, "InvoiceNomina": { "$ref": "#/components/examples/InvoiceNomina" }, "InvoiceEgreso": { "$ref": "#/components/examples/InvoiceEgreso" }, "InvoiceTraslado": { "$ref": "#/components/examples/InvoiceTraslado" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "patch": { "tags": [ "Invoices" ], "operationId": "PatchInvoices", "summary": "Complete an invoices request", "description": "Used to resume an Invoice retrieve session that was paused because an MFA\ntoken was required by the institution.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBody" } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceWithIdSat" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceWithIdSat" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/invoices/{id}/": { "get": { "tags": [ "Invoices" ], "operationId": "DetailInvoice", "summary": "Get an invoice's details", "description": "Get the details of a specific invoice.\n\n{% admonition type=\"info\" %}\n This resource may return deprecated fields. Please check the response documentation for more information.\n{% /admonition %}\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `invoice.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceWithIdSat" }, "examples": { "InvoiceIngresso": { "$ref": "#/components/examples/InvoiceIngresoDetail" }, "InvoicePago": { "$ref": "#/components/examples/InvoicePagoDetail" }, "InvoiceNomina": { "$ref": "#/components/examples/InvoiceNominaDetail" }, "InvoiceEgreso": { "$ref": "#/components/examples/InvoiceEgresoDetail" }, "InvoiceTraslado": { "$ref": "#/components/examples/InvoiceTrasladoDetail" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Invoices" ], "operationId": "DestroyInvoice", "summary": "Delete an invoice", "description": "Delete a specific invoice from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `invoice.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-compliance-status/": { "get": { "tags": [ "Tax compliance status" ], "operationId": "ListTaxComplianceStatus", "summary": "List tax compliance statuses", "description": "## ▶️ Usage\n\nWith the List Tax Compliance Statuses method, you can:\n\n1. List tax compliance statuses related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `tax-compliance-status.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all tax compliance statuses related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of tax compliance status objects.", "items": { "$ref": "#/components/schemas/TaxComplianceStatus" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Tax compliance status" ], "operationId": "RetrieveTaxComplianceStatus", "summary": "Retrieve tax compliance statuses for a link", "description": "Retrieve the Tax compliance status information for a specific fiscal link.", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxComplianceStatus" } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxComplianceStatus" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-compliance-status/{id}/": { "get": { "tags": [ "Tax compliance status" ], "operationId": "DetailTaxComplianceStatus", "summary": "Get a tax compliance status's details", "description": "Get the details of a specific Tax compliance status.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-compliance-status.id` you want to get detailed information\nabout.\n", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxComplianceStatus" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Tax compliance status" ], "operationId": "DestroyTaxComplianceStatus", "summary": "Delete a tax compliance status", "description": "Delete a specific Tax compliance status from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-compliance-status.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-returns/": { "get": { "tags": [ "Tax returns" ], "operationId": "ListTaxReturns", "summary": "List tax returns", "description": "## ▶️ Usage\n\n With the List Tax Returns method, you can:\n\n 1. List tax returns related to a specific `link.id` (using the `link` query parameter).\n 2. Get the details of a specific `tax-return.id` (using the `id` query parameter).\n 3. **[Not Recommended]** List all tax returns related to your Belvo account (without using any query parameters).\n\n ## 📖 Pagination\n \n 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.\n \n ## 🔦 Filtering Responses\n \n 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.\n\n ## 🔔 Multiple Schemas\n\n 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).\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/ejercicio" }, { "$ref": "#/components/parameters/ejercicio__lt" }, { "$ref": "#/components/parameters/ejercicio__lte" }, { "$ref": "#/components/parameters/ejercicio__gt" }, { "$ref": "#/components/parameters/ejercicio__gte" }, { "$ref": "#/components/parameters/ejercicio__range" }, { "$ref": "#/components/parameters/tipo_declaracion" }, { "$ref": "#/components/parameters/tipo_declaracion__in" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "An array of:\n\n - Tax Return Personal (Yearly) objects\n - Tax Return Personal (Monthly) objects\n - Tax Return Business (Yearly) objects\n - Tax Return Business (Monthly) objects\n \n > 🚧 Multiple Schemas\n >\n > 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).\n", "items": { "anyOf": [ { "$ref": "#/components/schemas/TaxReturnPersonal" }, { "$ref": "#/components/schemas/TaxReturnPersonalMonthly" }, { "$ref": "#/components/schemas/TaxReturnBusiness" }, { "$ref": "#/components/schemas/TaxReturnBusinessMonthly" } ] } } } } ] }, "examples": { "TaxReturnPersonal": { "$ref": "#/components/examples/TaxReturnPersonalListPaginated" }, "TaxReturnPersonalMonthlyPFAE": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPaginatedPFAE" }, "TaxReturnPersonalMonthlyPFAI": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPaginatedPFAI" }, "TaxReturnBusiness": { "$ref": "#/components/examples/TaxReturnBusinessListPaginated" }, "TaxReturnBusinessMonthly": { "$ref": "#/components/examples/TaxReturnBusinessListMonthlyPaginated" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Tax returns" ], "operationId": "RetrieveTaxReturns", "summary": "Retrieve tax returns for a link", "description": "Retrieve tax return information for a specific fiscal link.", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaxReturnsMonthlyRequest" }, { "$ref": "#/components/schemas/TaxReturnsYearlyRequest" } ] } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TaxReturnPersonal" }, { "$ref": "#/components/schemas/TaxReturnPersonalMonthly" }, { "$ref": "#/components/schemas/TaxReturnBusiness" }, { "$ref": "#/components/schemas/TaxReturnBusinessMonthly" } ] } }, "examples": { "TaxReturnPersonal": { "$ref": "#/components/examples/TaxReturnPersonalList" }, "TaxReturnPersonalMonthlyPFAE": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPFAE" }, "TaxReturnPersonalMonthlyPFAI": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPFAI" }, "TaxReturnBusiness": { "$ref": "#/components/examples/TaxReturnBusinessList" }, "TaxReturnBusinessMonthly": { "$ref": "#/components/examples/TaxReturnBusinessListMonthly" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TaxReturnPersonal" }, { "$ref": "#/components/schemas/TaxReturnPersonalMonthly" }, { "$ref": "#/components/schemas/TaxReturnBusiness" }, { "$ref": "#/components/schemas/TaxReturnBusinessMonthly" } ] } }, "examples": { "TaxReturnPersonal": { "$ref": "#/components/examples/TaxReturnPersonalList" }, "TaxReturnPersonalMonthlyPFAE": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPFAE" }, "TaxReturnPersonalMonthlyPFAI": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPFAI" }, "TaxReturnBusiness": { "$ref": "#/components/examples/TaxReturnBusinessList" }, "TaxReturnBusinessMonthly": { "$ref": "#/components/examples/TaxReturnBusinessListMonthly" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-returns/{id}/": { "get": { "tags": [ "Tax returns" ], "operationId": "DetailTaxReturn", "summary": "Get a tax return's details", "description": "Get the details of a specific tax return.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-return.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaxReturnPersonal" }, { "$ref": "#/components/schemas/TaxReturnPersonalMonthly" }, { "$ref": "#/components/schemas/TaxReturnBusiness" }, { "$ref": "#/components/schemas/TaxReturnBusinessMonthly" } ] }, "examples": { "TaxReturnPersonal": { "$ref": "#/components/examples/TaxReturnPersonalListDetail" }, "TaxReturnPersonalMonthlyPFAE": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPFAEDetail" }, "TaxReturnPersonalMonthlyPFAI": { "$ref": "#/components/examples/TaxReturnPersonalListMonthlyPFAIDetail" }, "TaxReturnBusiness": { "$ref": "#/components/examples/TaxReturnBusinessListDetail" }, "TaxReturnBusinessMonthly": { "$ref": "#/components/examples/TaxReturnBusinessListMonthlyDetail" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Tax returns" ], "operationId": "DestroyTaxReturn", "summary": "Delete a tax return", "description": "Delete a specific tax return from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the tax return you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-retentions/": { "get": { "tags": [ "Tax retentions" ], "operationId": "ListTaxRetentions", "summary": "List tax retentions", "description": "## ▶️ Usage\n\n With the List Tax Retentions method, you can:\n\n 1. List tax retentions related to a specific `link.id` (using the `link` query parameter).\n 2. Get the details of a specific `tax-retention.id` (using the `id` query parameter).\n 3. **[Not Recommended]** List all tax retentions related to your Belvo account (without using any query parameters).\n\n ## 📖 Pagination\n \n 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.\n \n ## 🔦 Filtering Responses\n \n 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of tax retentions objects.", "items": { "$ref": "#/components/schemas/TaxRetentions" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Tax retentions" ], "operationId": "RetrieveTaxRetentions", "summary": "Retrieve tax retentions for a link", "description": "Retrieve tax retention information from a specific link. The maximum number of tax retentions that can be returned for a period is 500.", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link", "date_from", "date_to", "type" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "type": { "$ref": "#/components/schemas/EnumTaxRetentionType" }, "attach_xml": { "$ref": "#/components/schemas/attach_xml" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRetentions" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRetentions" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-retentions/{id}/": { "get": { "tags": [ "Tax retentions" ], "operationId": "DetailTaxRetentions", "summary": "Get a tax retention's details", "description": "Get the details of a specific tax retention.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-retention.id` you want to get detailed information\nabout.\n", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRetentions" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Tax retentions" ], "operationId": "DestroyTaxRetention", "summary": "Delete a tax retention", "description": "Delete a specific tax retention from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-retention.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-status/": { "get": { "tags": [ "Tax status" ], "operationId": "ListTaxStatus", "summary": "List tax statuses", "description": "## ▶️ Usage\n\nWith the List Tax Statuses method, you can:\n\n1. List tax statuses related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `tax-status.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all tax statuses related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of tax status objects.", "items": { "$ref": "#/components/schemas/TaxStatusSat" } } } } ] }, "examples": { "TaxStatusPersonalListPaginated": { "$ref": "#/components/examples/TaxStatusPersonalListPaginated" }, "TaxStatusBusinessListPaginated": { "$ref": "#/components/examples/TaxStatusBusinessListPaginated" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Tax status" ], "operationId": "RetrieveTaxStatus", "summary": "Retrieve tax statuses for a link", "description": "Retrieve tax status information for a specific fiscal link.", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for the Retrieve Tax Status method.", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxStatusSat" }, "examples": { "TaxStatusPersonal": { "$ref": "#/components/examples/TaxStatusPersonalList" }, "TaxStatusBusiness": { "$ref": "#/components/examples/TaxStatusBusinessList" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxStatusSat" }, "examples": { "TaxStatusPersonal": { "$ref": "#/components/examples/TaxStatusPersonalList" }, "TaxStatusBusiness": { "$ref": "#/components/examples/TaxStatusBusinessList" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/tax-status/{id}/": { "get": { "tags": [ "Tax status" ], "operationId": "DetailTaxStatus", "summary": "Get a tax status's details", "description": "Get the details of a specific tax status.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-status.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxStatusSat" }, "examples": { "TaxStatusPersonal": { "$ref": "#/components/examples/TaxStatusPersonalList" }, "TaxStatusBusiness": { "$ref": "#/components/examples/TaxStatusBusinessList" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Tax status" ], "operationId": "DestroyTaxStatus", "summary": "Delete a tax status", "description": "Delete a specific tax status from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "the `tax-status.id` that you want to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "428": { "$ref": "#/components/responses/428_token_required_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/cl/invoices/": { "get": { "tags": [ "Invoices Chile" ], "operationId": "ListInvoicesChile", "description": "## ▶️ Usage\n\nWith the List Invoices method, you can:\n\n1. List invoices related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `invoice.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all invoices related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "summary": "List invoices", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of invoice objects.", "items": { "$ref": "#/components/schemas/invoice_chile" } } } } ] }, "examples": { "ChileInvoicesAll": { "$ref": "#/components/examples/ChileInvoicesAll" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Invoices Chile" ], "operationId": "RetrieveInvoicesChile", "summary": "Retrieve invoices for a link", "description": "Retrieve invoice information from a specific Chilean fiscal link.\nYou 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.\n> 📘 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.\n", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date_from", "date_to", "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" }, "type": { "$ref": "#/components/schemas/EnumInvoiceType" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/invoice_chile" } }, "examples": { "PurchaseInvoiceArray": { "$ref": "#/components/examples/PurchaseInvoiceArray" }, "SummaryInvoiceArray": { "$ref": "#/components/examples/SummaryInvoiceArray" }, "SaleInvoiceArray": { "$ref": "#/components/examples/SaleInvoiceArray" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/invoice_chile" } }, "examples": { "PurchaseInvoiceArray": { "$ref": "#/components/examples/PurchaseInvoiceArray" }, "SummaryInvoiceArray": { "$ref": "#/components/examples/SummaryInvoiceArray" }, "SaleInvoiceArray": { "$ref": "#/components/examples/SaleInvoiceArray" } } } } }, "202": { "$ref": "#/components/responses/202_accepted_response" }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/cl/invoices/{id}/": { "get": { "tags": [ "Invoices Chile" ], "operationId": "DetailInvoiceChile", "summary": "Get an invoice's details", "description": "Get the details of a specific invoice.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `invoice.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_chile" }, "examples": { "PurchaseInvoiceDetails": { "$ref": "#/components/examples/PurchaseInvoiceDetails" }, "SummaryInvoiceDetails": { "$ref": "#/components/examples/SummaryInvoiceDetails" }, "SaleInvoiceDetails": { "$ref": "#/components/examples/SaleInvoiceDetails" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Invoices Chile" ], "operationId": "DestroyInvoiceChile", "summary": "Delete an invoice", "description": "Delete a specific invoice from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `invoice.id` that you want to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/cl/tax-status/": { "get": { "tags": [ "Tax Status Chile" ], "operationId": "ListTaxStatusChile", "summary": "List tax statuses", "description": "## ▶️ Usage\n\nWith the Tax Status method, you can:\n\n1. List tax statuses related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `tax-status.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all tax statuses related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of tax status objects.", "items": { "$ref": "#/components/schemas/tax_status_sii" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Tax Status Chile" ], "operationId": "RetrieveTaxStatusChile", "summary": "Retrieve tax statuses for a link", "description": "Retrieve tax status information for a specific fiscal link.", "parameters": [ { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/tax_status_sii" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/tax_status_sii" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/cl/tax-status/{id}/": { "get": { "tags": [ "Tax Status Chile" ], "operationId": "DetailTaxStatusChile", "summary": "Get a tax status's details", "description": "Get the details of a specific tax status.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `tax-status.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tax_status_sii" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Tax Status Chile" ], "operationId": "DestroyTaxStatusChile", "summary": "Delete a tax status", "description": "Delete a specific tax status from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "the `tax-status.id` that you want to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/cl/debt-reports/": { "get": { "tags": [ "Debt Reports Chile" ], "operationId": "ListDebtReportChile", "summary": "List debts reports", "description": "## ▶️ Usage\n\nWith the List Debt Reports method, you can:\n\n1. List debt reports related to a specific `link.id` (using the `link` query parameter).\n2. Get the details of a specific `debt-report.id` (using the `id` query parameter).\n3. **[Not Recommended]** List all debt reports related to your Belvo account (without using any query parameters).\n\n## 📖 Pagination\n\nThis 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.\n\n## 🔦 Filtering Responses\n\nPlease 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.\n", "parameters": [ { "$ref": "#/components/parameters/link" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/link__in" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of debt report objects.", "items": { "$ref": "#/components/schemas/debt_chile" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "post": { "tags": [ "Debt Reports Chile" ], "operationId": "RetrieveDebtReportChile", "summary": "Retrieve debt details for a link", "description": "Retrieve debt reports information for a specific fiscal link.", "parameters": [ { "$ref": "#/components/parameters/async" }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" } } } } } }, "responses": { "200": { "description": "Ok (when `save_data=false`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/debt_chile" } } } } }, "201": { "description": "Created (when `save_data=true`)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/debt_chile" } } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/api/cl/debt-reports/{id}/": { "get": { "tags": [ "Debt Reports Chile" ], "operationId": "DetailDebtReportChile", "summary": "Get a debt's details", "description": "Get the details of a specific debt.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The `debt-report.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/omit" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/debt_chile" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "delete": { "tags": [ "Debt Reports Chile" ], "operationId": "DestroyDebtReportChile", "summary": "Delete a debt report", "description": "Delete a specific debt report from your Belvo account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "the `debt-report.id` that you want to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/institutions/": { "get": { "tags": [ "Payment Institutions (Brazil)" ], "operationId": "ListPaymentInstitutionsBrazil", "summary": "List all payment institutions", "description": "List all available payment institutions.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/name__payments" }, { "$ref": "#/components/parameters/institution_type" }, { "$ref": "#/components/parameters/institution_id__in" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of institution objects.", "items": { "$ref": "#/components/schemas/paymentInstitutionBR" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/charges/": { "get": { "tags": [ "Charges (Brazil)" ], "operationId": "ListAllChargesBrazil", "summary": "List all charges", "description": "List all the charges related to your account.\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/amount" }, { "$ref": "#/components/parameters/amount__gt" }, { "$ref": "#/components/parameters/amount__gte" }, { "$ref": "#/components/parameters/amount__lt" }, { "$ref": "#/components/parameters/amount__lte" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/payment_intent" }, { "$ref": "#/components/parameters/payment_intent__in" }, { "$ref": "#/components/parameters/status_charges" }, { "$ref": "#/components/parameters/status__in_charges" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of Payment Authorization objects.", "items": { "oneOf": [ { "$ref": "#/components/schemas/ChargeBrazil" }, { "$ref": "#/components/schemas/ChargeBrazilPix" } ] } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/charges/{charge_id}/": { "get": { "tags": [ "Charges (Brazil)" ], "operationId": "DetailChargeBrazil", "summary": "Get details about a Charge", "description": "Get the details about a specific Charge.\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "charge_id", "required": true, "in": "path", "description": "The `charge.id` you want details about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ChargeBrazil" }, { "$ref": "#/components/schemas/ChargeBrazilPix" }, { "$ref": "#/components/schemas/ChargeV2" } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/customers/": { "post": { "tags": [ "Customers (Brazil)" ], "operationId": "CreateCustomerBrazil", "summary": "Create a new customer", "description": "Create a new customer to send or request funds.", "parameters": [ { "$ref": "#/components/parameters/header_version" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateCustomerV2" }, { "$ref": "#/components/schemas/CreateCustomerOfpi" } ] } } } }, "responses": { "201": { "description": "OK (Created)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CustomerV2" }, { "$ref": "#/components/schemas/CustomerOfpi" } ] } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "get": { "tags": [ "Customers (Brazil)" ], "operationId": "ListCustomersBrazil", "summary": "List all customers", "description": "List all customers associated with your Belvo account.", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/customer__type" }, { "$ref": "#/components/parameters/external_id__payments" }, { "$ref": "#/components/parameters/external_id__in__payments" }, { "$ref": "#/components/parameters/search" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of customer objects.", "items": { "oneOf": [ { "$ref": "#/components/schemas/CustomerV2" }, { "$ref": "#/components/schemas/CustomerOfpi" } ] } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/customers/{id}/": { "get": { "tags": [ "Customers (Brazil)" ], "operationId": "DetailCustomerBrazil", "summary": "Get details about a customer", "description": "Get the details about a specific customer", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "id", "required": true, "in": "path", "description": "The `customer.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CustomerV2" }, { "$ref": "#/components/schemas/CustomerOfpi" } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/bank-accounts/": { "post": { "tags": [ "Bank Accounts (Brazil)" ], "operationId": "RegisterBankAccountBrazil", "summary": "Register a new bank account", "description": "Register a new bank account from which to send or request funds.\n", "parameters": [ { "$ref": "#/components/parameters/header_version" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBankAccountV2" }, { "$ref": "#/components/schemas/CreateBankAccountOfpiBusiness" }, { "$ref": "#/components/schemas/CreateBankAccountOfpiIndividual" } ] } } } }, "responses": { "201": { "description": "OK (Created)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BankAccountV2" }, { "$ref": "#/components/schemas/BankAccountOfpiResponse" } ] } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "get": { "tags": [ "Bank Accounts (Brazil)" ], "operationId": "ListBankAccountBrazil", "summary": "List all bank accounts", "description": "List all bank accounts associated with your Belvo account.", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/number" }, { "$ref": "#/components/parameters/number__in" }, { "$ref": "#/components/parameters/customer" }, { "$ref": "#/components/parameters/external_id__payments" }, { "$ref": "#/components/parameters/external_id__in__payments" }, { "$ref": "#/components/parameters/institution" }, { "$ref": "#/components/parameters/holder__type" }, { "$ref": "#/components/parameters/holder__type__in" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of bank account objects.", "items": { "oneOf": [ { "$ref": "#/components/schemas/BankAccountV2" }, { "$ref": "#/components/schemas/BankAccountOfpiResponse" } ] } } } } ] }, "examples": { "OfpiBusinessPixInfo": { "$ref": "#/components/examples/ResponseBankAccountBusinessPixInfoPaginated" }, "OfpiIndividualPixInfo": { "$ref": "#/components/examples/ResponseBankAccountIndividualPixInfoPaginated" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/bank-accounts/{id}/": { "get": { "tags": [ "Bank Accounts (Brazil)" ], "operationId": "DetailBankAccountBrazil", "summary": "Get details about a bank account", "description": "Get the details about a specific bank account", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "id", "required": true, "in": "path", "description": "The `bank-account.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BankAccountV2" }, { "$ref": "#/components/schemas/BankAccountOfpiResponse" } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-intents/": { "post": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "CreatePaymentIntentBrazil", "summary": "Create a new Payment Intent", "description": "Create a Payment Intent.\n\nYou can create Payment Intent in the following configurations:\n\n |Beneficiary|Customer (Payer)|Example|\n |---|---|---|\n |Pix Key|Already registered with Belvo|Pix Key (With Existing Customer)|\n |Pix Key|Register with Belvo at time of Payment Intent request|Pix Key (With New Customer)|\n |Bank Account (Already Registered)|Already Registered |Bank Account (With Existing Customer)|\n |Bank Account (Already Registered)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer)|\n |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)|\n\n {% admonition type=\"warning\" name=\"Pix Payments\" %}\n 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.\n {% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/header_idempotency_key" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreatePaymentIntentPixKeys" }, { "$ref": "#/components/schemas/CreatePaymentIntentPixKeysAndCustomer" }, { "$ref": "#/components/schemas/CreatePaymentIntentOfpi" }, { "$ref": "#/components/schemas/CreatePaymentIntentAndCustomerOfpi" }, { "$ref": "#/components/schemas/CreatePaymentIntentAndBankAccountAndCustomerOfpi" } ] } } } }, "responses": { "201": { "description": "OK (Created)", "headers": { "Belvo-Idempotency-Key": { "$ref": "#/components/headers/header_idempotency_key_response" }, "Belvo-Idempotency-Status": { "$ref": "#/components/headers/header_idempotency_key_status_response" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPixKeys" }, { "$ref": "#/components/schemas/PaymentIntentOfpi" } ] }, "examples": { "PaymentIntentResponsePixKeyInitial": { "$ref": "#/components/examples/PaymentIntentResponsePixKeyInitial" }, "PaymentIntentResponseOfpiBankAccount": { "$ref": "#/components/examples/PaymentIntentResponseOfpiBankAccount" } } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "409": { "$ref": "#/components/responses/409_idempotency_conflict_error" }, "422": { "$ref": "#/components/responses/422_idempotency_mismatch_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "get": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "ListPaymentIntentsBrazil", "summary": "List all payment intents", "description": "List all payment intents associated with your Belvo account.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/amount" }, { "$ref": "#/components/parameters/amount__gt" }, { "$ref": "#/components/parameters/amount__gte" }, { "$ref": "#/components/parameters/amount__lt" }, { "$ref": "#/components/parameters/amount__lte" }, { "$ref": "#/components/parameters/amount__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/customer" }, { "$ref": "#/components/parameters/customer__in" }, { "$ref": "#/components/parameters/external_id__payments" }, { "$ref": "#/components/parameters/external_id__in__payments" }, { "$ref": "#/components/parameters/ordering__payment-intents" }, { "$ref": "#/components/parameters/provider" }, { "$ref": "#/components/parameters/payment_method_type" }, { "$ref": "#/components/parameters/search" }, { "$ref": "#/components/parameters/status_payment-intents" }, { "$ref": "#/components/parameters/status__in_payment-intents" }, { "$ref": "#/components/parameters/updated_at" }, { "$ref": "#/components/parameters/updated_at__gt" }, { "$ref": "#/components/parameters/updated_at__gte" }, { "$ref": "#/components/parameters/updated_at__lt" }, { "$ref": "#/components/parameters/updated_at__lte" }, { "$ref": "#/components/parameters/updated_at__range" } ], "responses": { "200": { "description": "OK", "headers": { "Belvo-Idempotency-Key": { "$ref": "#/components/headers/header_idempotency_key_response" }, "Belvo-Idempotency-Status": { "$ref": "#/components/headers/header_idempotency_key_status_response" } }, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of payment intent objects.", "items": { "$ref": "#/components/schemas/PaymentIntentOfpi" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-intents/{id}/": { "patch": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "PatchPaymentIntentBrazil", "summary": "Complete a payment intent", "description": "Complete a new payment intent.\n", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The `payment-intent.id` you want to complete the payment for.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PatchPaymentIntentPixKeys" }, { "$ref": "#/components/schemas/PatchPaymentIntentOfpi" } ] } } } }, "responses": { "200": { "description": "OK (Confirmed)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPixKeys" }, { "$ref": "#/components/schemas/PaymentIntentOfpi" } ] } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "get": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "DetailPaymentIntentBrazil", "summary": "Get details about a payment intent", "description": "Get the details about a specific payment intent.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The `payment-intent.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentOfpi" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-intents/{id}/cancel/": { "post": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "CancelPaymentIntentBrazil", "summary": "Cancel a scheduled payment intent", "description": "Cancel a scheduled (one-off) payment intent.\n\nWe respond with a `204 - No Content` and will inform you via webhook that the payment intent was canceled successfully.\n\n> **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.\n", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The scheduled `payment-intent.id` you want to cancel.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-intents/{payment_intent_id}/charges/": { "get": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "ListChargesBrazil", "summary": "List all charges for a payment intent", "description": "List all charges associated with a payment intent.\n", "parameters": [ { "name": "payment_intent_id", "required": true, "in": "path", "description": "The `payment-intent.id` the charges belong to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "name": "status", "in": "query", "description": "Return results only for this value.", "schema": { "type": "string", "example": "SUCCEEDED" } }, { "name": "status__in", "in": "query", "description": "Return results for listed status.", "schema": { "type": "string", "example": "PENDING,SUCCEEDED" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of charge objects.", "items": { "$ref": "#/components/schemas/ChargeBrazil" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/": { "get": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "DetailChargesBrazil", "summary": "Get details about a charge for a payment intent", "description": "Get the details about a specific charge associated with a payment intent.\n", "parameters": [ { "name": "payment_intent_id", "required": true, "in": "path", "description": "The `payment-intent.id` the charge belongs to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "name": "charge_id", "required": true, "in": "path", "description": "The `charge.id` you want details about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeBrazil" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/": { "post": { "tags": [ "Payment Intents (Brazil)" ], "operationId": "CancelChargeBrazil", "summary": "Cancel a scheduled charge", "description": "Cancel a scheduled charge.\n\nWe respond with a `204 - No Content` and will inform you via webhook that the charge was canceled successfully.\n\n> **Note**: The latest you can cancel a scheduled charge is by **23:59:00 (GMT-3)** on the day **before** the scheduled payment date.\n", "parameters": [ { "name": "payment_intent_id", "required": true, "in": "path", "description": "The scheduled `payment-intent.id` the charge belongs to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "name": "charge_id", "required": true, "in": "path", "description": "The scheduled `charge.id` you want to cancel.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/": { "post": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "CreatePaymentAuthorizationBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Create a new Payment Authorization", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nCreate a Payment Authorization.\n", "parameters": [ { "$ref": "#/components/parameters/header_version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreatePaymentAuthorizationImmediate" }, { "$ref": "#/components/schemas/CreatePaymentAuthorizationScheduled" } ] } } } }, "responses": { "201": { "description": "OK - Payment Authorization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAuthorization" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "get": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "ListPaymentAuthorizationsBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "List all Payment Authorizations", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nList all Payment Authorizations associated with your Belvo account.\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/amount" }, { "$ref": "#/components/parameters/amount__gt" }, { "$ref": "#/components/parameters/amount__gte" }, { "$ref": "#/components/parameters/amount__lt" }, { "$ref": "#/components/parameters/amount__lte" }, { "$ref": "#/components/parameters/amount__range" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/customer" }, { "$ref": "#/components/parameters/customer__in" }, { "$ref": "#/components/parameters/external_id__payments" }, { "$ref": "#/components/parameters/external_id__in__payments" }, { "$ref": "#/components/parameters/search" }, { "$ref": "#/components/parameters/updated_at" }, { "$ref": "#/components/parameters/updated_at__gt" }, { "$ref": "#/components/parameters/updated_at__gte" }, { "$ref": "#/components/parameters/updated_at__lt" }, { "$ref": "#/components/parameters/updated_at__lte" }, { "$ref": "#/components/parameters/updated_at__range" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of Payment Authorization objects.", "items": { "$ref": "#/components/schemas/PaymentAuthorization" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/{payment_authorization_id}/": { "get": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "DetailPaymentAuthorizationBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Get details about a Payment Authorization", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nGet the details about a specific Payment Authorization.\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "payment_authorization_id", "required": true, "in": "path", "description": "The `payment-authorization.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAuthorization" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/{payment_authorization_id}/cancel/": { "post": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "CancelPaymentAuthorizationBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Cancel a Payment Authorization", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nCancel a Payment Authorization\n\nWe respond with a `204 - No Content` and will inform you via webhook that the Payment Authorization was canceled successfully.\n\n{% admonition type=\"warning\" name=\"Cancellation Time Restrictions\" %}\nThe latest you can cancel a Payment Authorization is by 22:00:00 (GMT-3) on the day before the next Charge date. If you miss the cutoff time, the Payment Authorization will be cancelled, **but the Charge will still be processed**.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "payment_authorization_id", "required": true, "in": "path", "description": "The scheduled `payment-authorization.id` you want to cancel.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/{payment_authorization_id}/charges/": { "get": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "ListPaymentAuthorizationChargesBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "List all Charges for a Payment Authorization", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nList all Charges associated with a Payment Authorization\n", "parameters": [ { "name": "payment_authorization_id", "required": true, "in": "path", "description": "The `payment-authorization.id` the charges belong to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "name": "status", "in": "query", "description": "Return results only for this value.", "schema": { "type": "string", "example": "SUCCEEDED" } }, { "name": "status__in", "in": "query", "description": "Return results for listed status.", "schema": { "type": "string", "example": "PENDING,SUCCEEDED" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of charge objects.", "items": { "$ref": "#/components/schemas/ChargeV2" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/": { "get": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "DetailPaymentAuthorizationChargeBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Get details about a Charge for a Payment Authorization", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nGet the details about a specific Charge associated with a Payment Authorization.\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "payment_authorization_id", "required": true, "in": "path", "description": "The `payment-authorization.id` the Charge belongs to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "name": "charge_id", "required": true, "in": "path", "description": "The `charge.id` you want details about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeV2" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/": { "post": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "RetryPaymentAuthorizationChargeBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Retry a failed Charge for a Payment Authorization", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nRetry a failed Charge for a given Payment Authorization.\n\n{% admonition type=\"warning\" name=\"Additional documentation\" %}\n Please make sure to read the dedicated Retrying Charges and Linked Charges documentation before attempting to retry a charge.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "payment_authorization_id", "required": true, "in": "path", "description": "The `payment-authorization.id` the Charge belongs to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "name": "charge_id", "required": true, "in": "path", "description": "The `charge.id` you want details about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The date you want to retry the Charge on, in `YYYY-MM-DD` format. Must be at least one day in the future.", "example": "2025-06-30" } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeV2" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/": { "post": { "tags": [ "Payment Authorizations (Brazil)" ], "operationId": "CancelPaymentAuthorizationChargeBrazil", "x-badges": [ { "name": "Coming Soon", "position": "before" } ], "summary": "Cancel a scheduled Charge", "description": "{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n\nCancel a scheduled Charge.\n\nWe respond with a `204 - No Content` and will inform you via webhook that the charge was canceled successfully.\n\n{% admonition type=\"warning\" name=\"Cancellation Time Restriction\" %}\n 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.\n{% /admonition %}\n", "parameters": [ { "$ref": "#/components/parameters/header_version" }, { "name": "payment_authorization_id", "required": true, "in": "path", "description": "The scheduled `payment-authorization.id` the Charge belongs to.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } }, { "name": "charge_id", "required": true, "in": "path", "description": "The scheduled `charge.id` you want to cancel.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/transactions/": { "get": { "tags": [ "Payment Transactions (Brazil)" ], "operationId": "ListPaymentTransactionsBrazil", "summary": "List all payment transactions", "description": "List all payment transactions associated with your Belvo account.", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/id__in" }, { "$ref": "#/components/parameters/created_at" }, { "$ref": "#/components/parameters/created_at__gt" }, { "$ref": "#/components/parameters/created_at__gte" }, { "$ref": "#/components/parameters/created_at__lt" }, { "$ref": "#/components/parameters/created_at__lte" }, { "$ref": "#/components/parameters/created_at__range" }, { "$ref": "#/components/parameters/charge" }, { "$ref": "#/components/parameters/charge__in" }, { "$ref": "#/components/parameters/beneficiary" }, { "$ref": "#/components/parameters/beneficiary__in" }, { "$ref": "#/components/parameters/payer" }, { "$ref": "#/components/parameters/payer__in" }, { "$ref": "#/components/parameters/customer" }, { "$ref": "#/components/parameters/customer__in" }, { "$ref": "#/components/parameters/payment_intent" }, { "$ref": "#/components/parameters/payment_intent__in" }, { "$ref": "#/components/parameters/transaction__type" }, { "$ref": "#/components/parameters/currency" }, { "$ref": "#/components/parameters/description" }, { "$ref": "#/components/parameters/amount" }, { "$ref": "#/components/parameters/amount__gt" }, { "$ref": "#/components/parameters/amount__gte" }, { "$ref": "#/components/parameters/amount__lt" }, { "$ref": "#/components/parameters/amount__lte" }, { "$ref": "#/components/parameters/amount__range" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of transaction objects.", "items": { "$ref": "#/components/schemas/paymentTransaction" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/transactions/{id}/": { "get": { "tags": [ "Payment Transactions (Brazil)" ], "operationId": "DetailPaymentTransactionsBrazil", "summary": "Get details about a payment transaction", "description": "Get the details about a specific payment transaction.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The `transaction.id` you want to get detailed information about.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentTransaction" } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/enrollments/": { "post": { "tags": [ "Enrollments (Brazil)" ], "operationId": "CreateEnrollmentBrazil", "summary": "Enroll a new user device", "description": "\n\n## ▶️ Usage\n\nWith the **Enroll a new user device** method, you can begin the enrollment process for a new device to allow for Biometric Pix payments.\n\n> 🚧 Create a customer first\n>\n> Before you can enroll a user device, you must first create a customer.\n", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnrollmentBiometricPix" } } } }, "responses": { "201": { "description": "OK (Created)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBiometricPix" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } }, "get": { "tags": [ "Enrollments (Brazil)" ], "operationId": "ListEnrollmentsBrazil", "summary": "List enrollments", "description": "## ▶️ Usage\n\nWith the List Enrollments method, you can:\n \n 1. (Recommended) List enrollments related to a specific CPF (using the `customer__identifier` query parameter).\n 2. List enrollments related to a specific `customer.id` and `institution.id` (using the `customer` and `institution` query parameters).\n 3. List enrollments according to a specific status (using the `status` query parameter).\n 4. **[Not Recommended]** List all enrollements related to your Belvo account (without using any query parameters).\n\n## 🔦 Filtering Responses\n\nPlease 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.\n\n## 📖 Pagination\n\nThis 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.\n", "parameters": [ { "$ref": "#/components/parameters/customer_identifier" }, { "$ref": "#/components/parameters/customer" }, { "$ref": "#/components/parameters/external_id__payments" }, { "$ref": "#/components/parameters/external_id__in__payments" }, { "$ref": "#/components/parameters/institution" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/status_enrollments" }, { "$ref": "#/components/parameters/status__in_enrollments" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/payments_common_pagination_properties" }, { "properties": { "results": { "type": "array", "description": "Array of enrollment objects.", "items": { "$ref": "#/components/schemas/EnrollmentBiometricPix" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/enrollments/{enrollment_id}/": { "get": { "tags": [ "Enrollments (Brazil)" ], "operationId": "DetailEnrollmentBrazil", "summary": "Get details about an enrollment", "description": "Get details regarding a specific device enrollment.", "parameters": [ { "name": "enrollment_id", "required": true, "in": "path", "description": "The `enrollment.id` you want to get details for.", "schema": { "type": "string", "format": "uuid", "example": "a3b92311-1888-449f-acaa-49ae28d68fcd" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBiometricPix" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/token/": { "post": { "tags": [ "Biometric Pix Widget Access Token (Brazil)" ], "summary": "Generate a payment widget access token", "operationId": "GeneratePaymentWidgetAccessToken", "description": "Generate a payment widget access token for the Biometric Pix enrollment or payment process.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricPaymentWidgetRequest" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetToken" } } } }, "400": { "$ref": "#/components/responses/400_bad_request_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } }, "/payments/br/enrollments/complete-redirection/": { "post": { "tags": [ "Enrollments (Brazil)" ], "operationId": "CompleteEnrollmentRedirectionBrazil", "summary": "Complete enrollment after redirection", "description": "## ▶️ Usage\n\nUse 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.\n", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Successful Callback", "required": [ "state" ], "properties": { "state": { "type": "string", "description": "The value of the `state` query parameter you received in the callback URL.", "example": "abc123" }, "code": { "type": "string", "description": "The value of the `code` query parameter you received in the callback URL.", "example": "xyz456" }, "id_token": { "type": "string", "description": "The value of the `id_token` query parameter you received in the callback URL.", "example": "idtoken789" } } }, { "type": "object", "title": "Error Callback", "required": [ "state", "error", "error_description" ], "properties": { "state": { "type": "string", "description": "The value of the `state` query parameter you received in the callback URL.", "example": "abc123" }, "error": { "type": "string", "description": "The value of the `error` query parameter you received in the callback URL.", "example": "access_denied" }, "error_description": { "type": "string", "description": "The value of the `error_description` query parameter you received in the callback URL.", "example": "The user denied access." } } } ] } } } }, "responses": { "200": { "description": "OK (Enrollment Successfully Updated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentBiometricPix" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/400_validation_error" } } } } }, "401": { "$ref": "#/components/responses/401_unauthorized_error" }, "403": { "$ref": "#/components/responses/403_access_denied_error" }, "404": { "$ref": "#/components/responses/404_not_found_error" }, "408": { "$ref": "#/components/responses/408_request_timeout_error" }, "500": { "$ref": "#/components/responses/500_unexpected_error" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Belvo employs **basic authentication** using your secret keys (You can find your API secret keys in your Belvo Dashboard, under the **Developers** section).\n\n\nTo 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:\n\n\n```shell\ncurl -X GET https://sandbox.belvo.com/api/ \\\n -H \"Authorization: Basic $(echo -n 'YOUR_SECRET_ID:YOUR_SECRET_PASSWORD' | base64)\"\n```\n\nReplace `YOUR_SECRET_ID` and `YOUR_SECRET_PASSWORD` with your actual credentials. **Never expose your credentials in client-side code or public repositories**." } }, "parameters": { "page_size": { "name": "page_size", "in": "query", "description": "Indicates how many results to return per page. By default we return 100 results per page.\n\nℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).\n", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000, "example": 100 } }, "page": { "name": "page", "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 1 } }, "display_name": { "name": "display_name", "in": "query", "description": "Return institutions that partially match this display name.", "schema": { "type": "string", "maxLength": 30, "example": "Erebor Bank" } }, "country_code": { "name": "country_code", "in": "query", "description": "Return institutions only for this two-letter country code.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "MX" } }, "country_code__in": { "name": "country_code__in", "in": "query", "description": "Return institutions only for these two-letter country codes.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "BR" } } }, "resources__allin": { "name": "resources__allin", "in": "query", "description": "Return institutions that support this combination resources.", "style": "form", "explode": false, "schema": { "type": "array", "minimum": 2, "items": { "type": "string", "example": "OWNERS" } } }, "name": { "name": "name", "in": "query", "description": "Return an institution with this Belvo-designated name.", "schema": { "type": "string", "pattern": "^[a-z_]{1,40}$", "minLength": 1, "maxLength": 40, "example": "planet_mx_retail" } }, "name__in": { "name": "name__in", "in": "query", "description": "Return institutions with one or more of these Belvo-designated names.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]{1,40}$", "minLength": 1, "maxLength": 40, "example": "planet_mx_retail" } } }, "status_institutions": { "name": "status", "in": "query", "description": "Return institutions with the given status. You can choose between `healthy` or `down`.", "schema": { "type": "string", "example": "healthy" } }, "status__in_institutions": { "name": "status__in", "in": "query", "description": "Return institutions with one of the given statuses. You can choose between `healthy` or `down`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "healthy" } } }, "type_institutions": { "name": "type", "in": "query", "description": "Return institutions of this type. You can choose between `bank`, `fiscal`, or `employment`.", "schema": { "type": "string", "enum": [ "bank", "fiscal", "employment" ], "example": "fiscal" } }, "type__in_institutions": { "name": "type__in", "in": "query", "description": "Return institutions of one of these types. You can choose between `bank`, `fiscal`, or `employment`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "bank", "fiscal", "employment" ], "example": "fiscal" } } }, "website": { "name": "website", "in": "query", "description": "Return institutions with this website URL.", "schema": { "type": "string", "example": "https://www.erebor.mx" } }, "omit": { "name": "omit", "in": "query", "description": "Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.", "schema": { "type": "string" } }, "fields": { "name": "fields", "in": "query", "description": "Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.", "schema": { "type": "string" } }, "id": { "name": "id", "in": "query", "description": "Return information only for this resource `id`.", "schema": { "type": "string", "format": "uuid", "example": "24ccab1d-3a86-4136-a6eb-e04bf52b356f" } }, "id__in": { "name": "id__in", "in": "query", "description": "Return information for these resource `id`s.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "6b3dea0f-be29-49d1-aabe-1a6d588642e6" } } }, "institution": { "name": "institution", "in": "query", "description": "Return results only for this institution (use the Belvo-designated name, such as `planet_mx_employment`).", "schema": { "type": "string", "pattern": "^[a-z_]{1,40}$", "minLength": 1, "maxLength": 40, "example": "planet_mx_retail" } }, "institution__in": { "name": "institution__in", "in": "query", "description": "Return results only for these institutions (use the Belvo-designated names, such as `ofmockbank_br_retail` and `planet_mx_employment`).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]{1,40}$", "minLength": 1, "maxLength": 40, "example": "planet_mx_retail" } } }, "access_mode": { "name": "access_mode", "in": "query", "description": "Return links only with this access mode. Can be either `single` or `recurrent`.", "example": "single", "schema": { "type": "string", "enum": [ "single", "recurrent" ], "example": "single" } }, "created_at": { "name": "created_at", "in": "query", "description": "Return items that were last updated in Belvo's database on this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "created_at__gt": { "name": "created_at__gt", "in": "query", "description": "Return items that were last updated in Belvo's database after this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "created_at__gte": { "name": "created_at__gte", "in": "query", "description": "Return items that were last updated in Belvo's database after or on this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "created_at__lt": { "name": "created_at__lt", "in": "query", "description": "Return items that were last updated in Belvo's database before this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-04-01" } }, "created_at__lte": { "name": "created_at__lte", "in": "query", "description": "Return items that were last updated in Belvo's database before or on this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-03-30" } }, "created_at__range": { "name": "created_at__range", "in": "query", "description": "Return accounts that were last updated in Belvo's database between two dates (in `YYYY-MM-DD` format). The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-03-03" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "created_by__not_in": { "name": "created_by__not_in", "in": "query", "description": "Return links that were not created by these Belvo users.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "d9475f4d-c511-4732-9ef0-93b5672f43d3" } } }, "external_id": { "name": "external_id", "in": "query", "description": "Return links with this external ID.", "schema": { "type": "string", "minLength": 3, "maxLength": 256, "example": "InternalUser4000" } }, "external_id__in": { "name": "external_id__in", "in": "query", "description": "Return links with these external IDs.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 256, "example": "InternalUser4001" } } }, "institution_user_id": { "name": "institution_user_id", "in": "query", "description": "Return links with this specific institution user ID.", "schema": { "type": "string", "example": "ezFoxjPDr7YnASnOaft5F3zt7D0kurgDNlLtZFjxUo0=" } }, "institution_user_id__in": { "name": "institution_user_id__in", "in": "query", "description": "Return links with these institution user IDs.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "ezFoxjPDr7YnASnOaft5F3zt7D0kurgDNlLtZFjxUo0=" } } }, "refresh_rate": { "name": "refresh_rate", "in": "query", "description": "Return links with this refresh rate. Choose between `6h`, `12h`, `24h`, `7d`, `30d`, or `null` (for single links).", "schema": { "type": "string", "pattern": "^((\\d{1,3}h)?(\\d{1,3}m)?(\\d{1,3}d)?|null)$", "example": "24h" } }, "status_links": { "name": "status", "in": "query", "description": "Return links with this status. Choose between `valid`, `invalid`, `unconfirmed`, or `token_required`.", "schema": { "type": "string", "example": "invalid" } }, "status__in_links": { "name": "status__in", "in": "query", "description": "Return links with these statuses. Choose between `valid`, `invalid`, `unconfirmed`, or `token_required`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "invalid" } } }, "pageSize_query": { "name": "page_size", "in": "query", "description": "Indicates how many results to return per page. By default we return 100 results per page. \n\nℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).\n", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000, "example": 100 } }, "document_number": { "name": "user_document", "required": true, "in": "query", "description": "The CPF or CNPJ number of the user you want to get consent information for.\n", "schema": { "type": "string", "minLength": 11, "maxLength": 14, "example": "12345678900" } }, "link": { "name": "link", "in": "query", "description": "The `link.id` you want to filter by.\n\nℹ️ We highly recommend adding the `link.id` filter in order to improve your performance.\n", "schema": { "type": "string", "format": "uuid", "example": "8848bd0c-9c7e-4f53-a732-ec896b11d4c4" } }, "link__in": { "name": "link__in", "in": "query", "description": "Return results only for these `link.id`s.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "5722d0ba-69d7-42dc-8ff5-33767b83c5d6" } } }, "balance__available": { "name": "balance__available", "in": "query", "description": "Return accounts that have a `balance.available` matching exactly this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4000.02 } }, "balance__available__lt": { "name": "balance__available__lt", "in": "query", "description": "Return accounts that have a `balance.available` less than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 6000.02 } }, "balance__available__lte": { "name": "balance__available__lte", "in": "query", "description": "Return accounts that have a `balance.available` less than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 5999.02 } }, "balance__available__gt": { "name": "balance__available__gt", "in": "query", "description": "Return accounts that have a `balance.available` greater than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 2000.02 } }, "balance__available__gte": { "name": "balance__available__gte", "in": "query", "description": "Return accounts that have a `balance.available` greater than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1999.02 } }, "balance__available__range": { "name": "balance__available__range", "in": "query", "description": "Return accounts that have a `balance.available` within a range of two. The first value indicates the start of the range and the second value indicates the end of the range. values.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4350.02 }, "example": [ 100, 5000 ] } }, "balance__current": { "name": "balance__current", "in": "query", "description": "Return accounts that have a `balance.current` matching exactly this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4000.02 } }, "balance__current__lt": { "name": "balance__current__lt", "in": "query", "description": "Return accounts that have a `balance.current` less than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 6000.02 } }, "balance__current__lte": { "name": "balance__current__lte", "in": "query", "description": "Return accounts that have a `balance.available` less than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 5999.02 } }, "balance__current__gt": { "name": "balance__current__gt", "in": "query", "description": "Return accounts that have a `balance.current` greater than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 2000.02 } }, "balance__current__gte": { "name": "balance__current__gte", "in": "query", "description": "Return accounts that have a `balance.available` greater than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1999.02 } }, "balance__current__range": { "name": "balance__current__range", "in": "query", "description": "Return accounts that have a `balance.current` within a range of two. The first value indicates the start of the range and the second value indicates the end of the range. values.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4350.02 }, "example": [ 100, 5000 ] } }, "category": { "name": "category", "in": "query", "description": "Return accounts only for the given category (for example, `CHECKING_ACCOUNT` and `SAVINGS_ACCOUNT`).", "schema": { "type": "string", "example": "CREDIT_ACCOUNT" } }, "category__in": { "name": "category__in", "in": "query", "description": "Return accounts only for the given categories (for example, `CHECKING_ACCOUNT` and `SAVINGS_ACCOUNT`).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "SAVINGS_ACCOUNT" } } }, "currency": { "name": "currency", "in": "query", "description": "Return results that hold finances or balances in only this three-letter currency code.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "BRA" } }, "currency__in": { "name": "currency__in", "in": "query", "description": "Return results that have funds or balances in one of these three-letter currency codes.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "BRA" } } }, "name_accounts": { "name": "name", "in": "query", "description": "Return accounts with exactly this internal (specified by the institution) name.", "schema": { "type": "string", "example": "Cuenta Perfiles- M.N. - MXN-666" } }, "name__icontains": { "name": "name__icontains", "in": "query", "description": "Return accounts partially matching this internal name (specified by the institution).", "schema": { "type": "string", "minLength": 3, "example": "Perfiles" } }, "number_accounts": { "name": "number", "in": "query", "description": "Return information only for this account number (as specified by the institution).", "schema": { "type": "string", "example": "4057068115181" } }, "number__in_accounts": { "name": "number__in", "in": "query", "description": "Return information for these account numbers (as specified by the institution).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "4057068115181" } } }, "public_identification_name": { "name": "public_identification_name", "in": "query", "description": "Return information only for this type of account ID. For example, CLABE accounts.", "schema": { "example": "CLABE", "type": "string" } }, "public_identification_value": { "name": "public_identification_value", "in": "query", "description": "Return information only for this account ID. For example, the account number for a CLABE account.", "schema": { "example": "150194683119900273", "type": "string" } }, "type_accounts": { "name": "type", "in": "query", "description": "Return information only for accounts matching this account type, as designated by the institution.", "schema": { "type": "string", "example": "Cuentas de efectivo" } }, "link__required": { "name": "link", "in": "query", "required": true, "description": "The `link.id` you want to filter by.\n", "schema": { "type": "string", "format": "uuid", "example": "8848bd0c-9c7e-4f53-a732-ec896b11d4c4" } }, "account": { "name": "account", "in": "query", "description": "The `account.id` you want to filter by.\n\nℹ️ We highly recommend adding either the `link.id` or the `account.id` filters in order to improve your performance.\n", "schema": { "type": "string", "format": "uuid", "example": "8848bd0c-9c7e-4f53-a732-ec896b11d4c4" } }, "account__in": { "name": "account__in", "in": "query", "description": "Return results only for these `account.id`s.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "85b77707-90ef-46fd-9059-5a757f24247a" } } }, "collected_at": { "name": "collected_at", "in": "query", "description": "Return items that were retrieved from the institution on this date (`YYYY-MM-DD` or full `ISO-8601` timestamp).", "schema": { "type": "string", "format": "date", "example": "2022-05-01" } }, "collected_at__gt": { "name": "collected_at__gt", "in": "query", "description": "Return items that were retrieved from the institution after this date (`YYYY-MM-DD` or full `ISO-8601` timestamp).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "collected_at__gte": { "name": "collected_at__gte", "in": "query", "description": "Return items that were retrieved from the institution after or on this date (`YYYY-MM-DD` or full `ISO-8601` timestamp).", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "collected_at__lt": { "name": "collected_at__lt", "in": "query", "description": "Return items that were retrieved from the institution before this date (`YYYY-MM-DD` or full `ISO-8601` timestamp).", "schema": { "type": "string", "format": "date", "example": "2022-04-01" } }, "collected_at__lte": { "name": "collected_at__lte", "in": "query", "description": "Return items that were retrieved from the institution before or on this date (`YYYY-MM-DD` or full `ISO-8601` timestamp).", "schema": { "type": "string", "format": "date", "example": "2022-03-30" } }, "collected_at__range": { "name": "collected_at__range", "in": "query", "description": "Return items that were retrieved from the institution between two dates (`YYYY-MM-DD` or full `ISO-8601` timestamp). The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-04" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "account__balance__available": { "name": "account__balance__available", "in": "query", "description": "Return transactions that have a `account.balance.available` matching exactly this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4000.02 } }, "account__balance__available__lt": { "name": "account__balance__available__lt", "in": "query", "description": "Return transactions that have a `account.balance.available` less than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 6000.02 } }, "account__balance__available__lte": { "name": "account__balance__available__lte", "in": "query", "description": "Return transactions that have a `account.balance.available` less than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 5999.02 } }, "account__balance__available__gt": { "name": "account__balance__available__gt", "in": "query", "description": "Return transactions that have a `account.balance.available` more than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 6000.02 } }, "account__balance__available__gte": { "name": "account__balance__available__gte", "in": "query", "description": "Return transactions that have a `account.balance.available` more than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 5999.02 } }, "account__balance__available__range": { "name": "account__balance__available__range", "in": "query", "description": "Return transactions that have a `account.balance.available` within a. The first value indicates the start of the range and the second value indicates the end of the range. range of two values.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4350.02 }, "example": [ 100, 5000 ] } }, "account__balance__current": { "name": "account__balance__current", "in": "query", "description": "Return transactions that have a `account.balance.current` matching exactly this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4000.02 } }, "account__balance__current__gt": { "name": "account__balance__current__gt", "in": "query", "description": "Return transactions that have a `account.balance.current` greater than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4020.02 } }, "account__balance__current__gte": { "name": "account__balance__current__gte", "in": "query", "description": "Return transactions that have a `account.balance.current` greater than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 4019.02 } }, "account__balance__current__lt": { "name": "account__balance__current__lt", "in": "query", "description": "Return transactions that have a `account.balance.current` less than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 3000.02 } }, "account__balance__current__lte": { "name": "account__balance__current__lte", "in": "query", "description": "Return transactions that have a `account.balance.current` less than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 2999.02 } }, "account__balance__current__range": { "name": "account__balance__current__range", "in": "query", "description": "Return transactions that have a `account.balance.current` within a range. The first value indicates the start of the range and the second value indicates the end of the range. of two values.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "number", "example": 4350 }, "example": [ 100, 5000 ] } }, "account_type": { "name": "account_type", "in": "query", "description": "Return information only for transactions matching this account type, as designated by the institution.", "schema": { "type": "string", "example": "Cuentas de efectivo" } }, "account_type__in": { "name": "account_type__in", "in": "query", "description": "Return information only for transactions matching these account types, as designated by the institution.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "Depositos Ahorro" } } }, "accounting_date": { "name": "accounting_date", "in": "query", "description": "Return transactions that were processed by the institution on exactly this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "accounting_date__gt": { "name": "accounting_date__gt", "in": "query", "description": "Return transactions that were processed by the institution after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-06" } }, "accounting_date__gte": { "name": "accounting_date__gte", "in": "query", "description": "Return transactions that were processed by the institution on this date (`YYYY-MM-DD`) or later.", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "accounting_date__lt": { "name": "accounting_date__lt", "in": "query", "description": "Return transactions that were processed by the institution before this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-03-02" } }, "accounting_date__lte": { "name": "accounting_date__lte", "in": "query", "description": "Return transactions that were processed by the institution on this date (`YYYY-MM-DD`) or earlier.", "schema": { "type": "string", "format": "date", "example": "2022-03-01" } }, "accounting_date__range": { "name": "accounting_date__range", "in": "query", "description": "Return transactions that were processed by the institution in this date. The first value indicates the start of the range and the second value indicates the end of the range. range (`YYYY-MM-DD`).", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-06" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "amount": { "name": "amount", "in": "query", "description": "Return results only for this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1000.02 } }, "amount__gt": { "name": "amount__gt", "in": "query", "description": "Return results only for more than this amount.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1000.02 } }, "amount__gte": { "name": "amount__gte", "in": "query", "description": "Return results only for and more than this amount.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1000.02 } }, "amount__lt": { "name": "amount__lt", "in": "query", "description": "Return results only for less than this amount.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1000.02 } }, "amount__lte": { "name": "amount__lte", "in": "query", "description": "Return results only for this amount or less.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1000.02 } }, "amount__range": { "name": "amount__range", "in": "query", "description": "Return results between this amount range. The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 2000.02 }, "example": [ 100, 5000 ] } }, "credit_card_data__bill_name__in": { "name": "credit_card_data__bill_name__in", "in": "query", "description": "Return transactions for one of these bill names.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "maxLength": 50, "example": "feb-2022" } } }, "reference": { "name": "reference", "in": "query", "description": "Returns transactions with this institution-assigned reference number.", "schema": { "type": "string", "example": "085904452810319225" } }, "reference__in": { "name": "reference__in", "in": "query", "description": "Returns transactions with these institution-assigned reference numbers.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "085904452810319225" } } }, "status_transactions": { "name": "status", "in": "query", "description": "Return transactions with this status. Can be either `PENDING`, `PROCESSED`, or `UNCATEGORIZED`.", "schema": { "type": "string", "example": "PENDING" } }, "status__in_transactions": { "name": "status__in", "in": "query", "description": "Return transactions with these statuses. Can be either `PENDING`, `PROCESSED`, or `UNCATEGORIZED`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "PROCESSED" } } }, "type_transactions": { "name": "type", "in": "query", "description": "Return transactions with this type. Can be either `INFLOW` or `OUTFLOW`.", "schema": { "type": "string", "enum": [ "OUTFLOW", "INFLOW" ], "example": "OUTFLOW" } }, "type__in_transactions": { "name": "type__in", "in": "query", "description": "Return transactions with this types. Can be either `INFLOW` or `OUTFLOW`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "OUTFLOW", "INFLOW" ], "example": "INFLOW" } } }, "value_date": { "name": "value_date", "in": "query", "description": "Return results for exactly this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "value_date__gt": { "name": "value_date__gt", "in": "query", "description": "Return results that occurred after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-06" } }, "value_date__gte": { "name": "value_date__gte", "in": "query", "description": "Return results for this date (`YYYY-MM-DD`) or later.", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "value_date__lt": { "name": "value_date__lt", "in": "query", "description": "Return results for before this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-03-02" } }, "value_date__lte": { "name": "value_date__lte", "in": "query", "description": "Return results for this date (`YYYY-MM-DD`) or earlier.", "schema": { "type": "string", "format": "date", "example": "2022-03-01" } }, "value_date__range": { "name": "value_date__range", "in": "query", "description": "Return results for this date (`YYYY-MM-DD`) range. The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-06" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "async": { "name": "X-Belvo-Request-Mode", "in": "header", "description": "Recommended header parameter to make your POST request asynchronous (thus preventing timeouts and improving your data flow).\n\nWhen you make an asynchronous request, Belvo responds with a `202 - Accepted` payload, including the `request_id`. Once we have retrieved the requested information, you will receive a webhook with the link and request IDs.\n", "schema": { "type": "string", "enum": [ "async" ], "example": "async" } }, "due_date": { "name": "due_date", "in": "query", "description": "Return items thathave a `due_date` on this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-01" } }, "due_date__gt": { "name": "due_date__gt", "in": "query", "description": "Return items that have a `due_date` after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "due_date__gte": { "name": "due_date__gte", "in": "query", "description": "Return items that have a `due_date` on or after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "due_date__lt": { "name": "due_date__lt", "in": "query", "description": "Return items that have a `due_date` before this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "due_date__lte": { "name": "due_date__lte", "in": "query", "description": "Return items that have a `due_date` before or on this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "due_date__range": { "name": "due_date__range", "in": "query", "description": "Return items that have a `due_date` between two dates (`YYYY-MM-DD`). The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-04" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "email": { "name": "email", "in": "query", "description": "Returns owners whose email address match your query.", "schema": { "type": "string", "format": "email", "example": "lopes.d@gmail.com" } }, "display_name__icontains": { "name": "display_name__icontains", "in": "query", "description": "Return owners whose full display name partially matches your query. For example, `mar` will return results for Mark, Maria, Neymar, Remarque, and so on.", "schema": { "type": "string", "minLength": 3, "example": "Daniela" } }, "type_investments": { "name": "type", "in": "query", "description": "Return investments with this type. Can be either `BANCARIA`, `CREDITO`, `VARIABLE` , `FUND`, or `BOND`.", "schema": { "type": "string", "example": "VARIABLE" } }, "type__in_investments": { "name": "type__in", "in": "query", "description": "Return investments of this type. Can be either `BANCARIA`, `CREDITO`, `VARIABLE` , `FUND`, or `BOND`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "VARIABLE" } } }, "internal_identification": { "name": "internal_identification", "in": "query", "description": "The `internal_identification` you want to filter by.", "schema": { "type": "string", "example": "BLPM951331IONVGR54" } }, "internal_identification__in": { "name": "internal_identification__in", "in": "query", "description": "One or more `internal_identification`s you want to filter by.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "BLPM951331IONVGR54" } } }, "start_date": { "name": "start_date", "in": "query", "description": "Return employments that started on this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "start_date__gt": { "name": "start_date__gt", "in": "query", "description": "Return employments that started after this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-05-06" } }, "start_date__gte": { "name": "start_date__gte", "in": "query", "description": "Return employments that started on or after this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "start_date__lt": { "name": "start_date__lt", "in": "query", "description": "Return employments that started before this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-03-02" } }, "start_date__lte": { "name": "start_date__lte", "in": "query", "description": "Return employments that started on or before this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-03-01" } }, "start_date__range": { "name": "start_date__range", "in": "query", "description": "Return employments that started within these two dates, in `YYYY-MM-DD,YYYY-MM-DD` format. The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-06" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "end_date": { "name": "end_date", "in": "query", "description": "Return employments that finished on this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "end_date__gt": { "name": "end_date__gt", "in": "query", "description": "Return employments that finished after this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-05-06" } }, "end_date__gte": { "name": "end_date__gte", "in": "query", "description": "Return employments that finished on or after this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "end_date__lt": { "name": "end_date__lt", "in": "query", "description": "Return employments that finished before this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-03-02" } }, "end_date__lte": { "name": "end_date__lte", "in": "query", "description": "Return employments that finished on or before this date, in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2022-03-01" } }, "end_date__range": { "name": "end_date__range", "in": "query", "description": "Return employments that finished within these two dates, in `YYYY-MM-DD,YYYY-MM-DD` format. The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-06" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "invoice_date": { "name": "invoice_date", "in": "query", "description": "Return invoices issued exactly on this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "invoice_date__lt": { "name": "invoice_date__lt", "in": "query", "description": "Return balances issued before this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-03-02" } }, "invoice_date__lte": { "name": "invoice_date__lte", "in": "query", "description": "Return balances issued on this date or earlier (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-03-01" } }, "invoice_date__gt": { "name": "invoice_date__gt", "in": "query", "description": "Return invoices issued after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date", "example": "2022-05-06" } }, "invoice_date__gte": { "name": "invoice_date__gte", "in": "query", "description": "Return invoices issued on this date or later (`YYYY-MM-DD`)", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "invoice_date__range": { "name": "invoice_date__range", "in": "query", "description": "Return invoices issued within this date range (`YYYY-MM-DD`). The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-05-06" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "invoice_identification": { "name": "invoice_identification", "in": "query", "description": "Return an invoice with this ID (as provided by the insitution).", "schema": { "type": "string", "example": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840" } }, "invoice_identification__in": { "name": "invoice_identification__in", "in": "query", "description": "Return invoices with these IDs (as provided by the institution).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "992B9918-3G6H-4E0B-DAI9-2BE2D833B833" } } }, "status_invoice": { "name": "status", "in": "query", "description": "Return invoices with this status. Can be either `Vigente` (valid) or `Cancelado` (cancelled).", "schema": { "type": "string", "example": "Vigente" } }, "status__in_invoice": { "name": "status__in", "in": "query", "description": "Return invoices with these statuses. Can be either `Vigente` (valid) or `Cancelado` (cancelled).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "Cancelado" } } }, "type_invoice": { "name": "type", "in": "query", "description": "Return invoices of this type. Can be either `OUTFLOW` or `INFLOW`.", "schema": { "type": "string", "enum": [ "OUTFLOW", "INFLOW" ], "example": "OUTFLOW" } }, "type__in_invoice": { "name": "type__in", "in": "query", "description": "Return invoices of these types. Can be either `OUTFLOW` or `INFLOW`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "OUTFLOW", "INFLOW" ], "example": "OUTFLOW" } } }, "total_amount": { "name": "total_amount", "in": "query", "description": "Return invoices matching exactly this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 1000.02 } }, "total_amount__lt": { "name": "total_amount__lt", "in": "query", "description": "Return invoices less than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 540.02 } }, "total_amount__lte": { "name": "total_amount__lte", "in": "query", "description": "Return invoices less than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 541.02 } }, "total_amount__gt": { "name": "total_amount__gt", "in": "query", "description": "Return invoices greater than this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 520.02 } }, "total_amount__gte": { "name": "total_amount__gte", "in": "query", "description": "Return invoices greater than or equal to this value.", "schema": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 519.02 } }, "total_amount__range": { "name": "total_amount__range", "in": "query", "description": "Return invoices between these two values. The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "example": 541.02 }, "example": [ 100, 5000 ] } }, "ejercicio": { "name": "ejercicio", "in": "query", "description": "Return tax returns for exactly this year (`YYYY`).", "schema": { "type": "integer", "pattern": "^[0-9]{4}$", "minimum": 1900, "minLength": 4, "maxLength": 4, "example": 2017 } }, "ejercicio__lt": { "name": "ejercicio__lt", "in": "query", "description": "Return tax returns for before this year (`YYYY`).", "schema": { "type": "integer", "pattern": "^[0-9]{4}$", "minimum": 1900, "minLength": 4, "maxLength": 4, "example": 2017 } }, "ejercicio__lte": { "name": "ejercicio__lte", "in": "query", "description": "Return tax returns for this year and earlier (`YYYY`).", "schema": { "type": "integer", "pattern": "^[0-9]{4}$", "minimum": 1900, "minLength": 4, "maxLength": 4, "example": 2017 } }, "ejercicio__gt": { "name": "ejercicio__gt", "in": "query", "description": "Return tax returns for after this year (`YYYY`).", "schema": { "type": "integer", "pattern": "^[0-9]{4}$", "minimum": 1900, "minLength": 4, "maxLength": 4, "example": 2017 } }, "ejercicio__gte": { "name": "ejercicio__gte", "in": "query", "description": "Return tax returns for this year or later (`YYYY`).", "schema": { "type": "integer", "pattern": "^[0-9]{4}$", "minimum": 1900, "minLength": 4, "maxLength": 4, "example": 2017 } }, "ejercicio__range": { "name": "ejercicio__range", "in": "query", "description": "Return tax returns for this range of years (`YYYY`). The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "integer", "pattern": "^[0-9]{4}$", "minimum": 1900, "minLength": 4, "maxLength": 4, "example": 2017 }, "example": [ 2015, 2021 ] } }, "tipo_declaracion": { "name": "tipo_declaracion", "in": "query", "description": "Return tax returns with this declaration type.", "schema": { "type": "string", "example": "Normal" } }, "tipo_declaracion__in": { "name": "tipo_declaracion__in", "in": "query", "description": "Return tax returns with these declaration types.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "Commercial" } } }, "name__payments": { "name": "name", "in": "query", "description": "Return an institution with this Belvo-designated name.\n\n**Note:**\n\nThis filter supports both full and partial search queries, with a minimum of three characters required.\n\nFor example, searching for `itau` may match the following values:\n\n - `itau_unibanco_retail`\n - `itau_unibanco_business`\n - `itau_retail`\n - `itau_business`\n - `superdigital_retail`\n - `superdigital_business`\n", "schema": { "type": "string", "minLength": 3, "example": "itau" } }, "institution_type": { "name": "institution_type", "in": "query", "description": "Return results only for this institution type. Can be either `INDIVIDUAL` or `BUSINESS`.", "schema": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "example": "INDIVIDUAL" } }, "institution_id__in": { "name": "id__in", "in": "query", "description": "Return information for these institution `id`s.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "6b3dea0f-be29-49d1-aabe-1a6d588642e6" } } }, "payment_intent": { "name": "payment_intent", "in": "query", "description": "The `payment-intent.id` you want to get results for.", "schema": { "type": "string", "format": "uuid", "example": "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d" } }, "payment_intent__in": { "name": "payment_intent__in", "in": "query", "description": "One or more `payment-intent.id`s that you want to get results for.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "cb320adc-9a6b-4224-933a-5b08cf771ac7" } } }, "status_charges": { "name": "status", "in": "query", "description": "Return transactions with this status. Can be either `CANCELED`, `FAILED`, `PENDING`, `SCHEDULED`, or `SUCCEEDED`.", "schema": { "type": "string", "example": "PENDING" } }, "status__in_charges": { "name": "status__in", "in": "query", "description": "Return transactions with these statuses (comma separated). Can be either `CANCELED`, `FAILED`, `PENDING`, `SCHEDULED`, or `SUCCEEDED`.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "SUCCEEDED" } } }, "header_version": { "name": "X-Belvo-API-Resource-Version", "in": "header", "description": "Header indicating which version of the Payment API you want to use. Currently this is only applicable for Bank Accounts, Customers, and Payment Authorizations in Brazil. In the case that you are using our Payment Authorizations product, then you **must** send through this header set to `Payments-BR.V2`.\n\n{% admonition type=\"warning\" name=\"Coming Soon\" %}\n This version is in Coming Soon. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.\n{% /admonition %}\n", "schema": { "type": "string", "enum": [ "Payments-BR.V2" ], "example": "Payments-BR.V2" } }, "customer__type": { "name": "customer__type", "in": "query", "description": "Return results only for this customer type (either `INDIVIDUAL` or `BUSINESS`).", "schema": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "example": "INDIVIDUAL" } }, "external_id__payments": { "name": "external_id", "in": "query", "description": "Return objects with this external ID.", "schema": { "type": "string", "format": "uuid", "example": "295ebb46-65b8-47de-85cd-34ffbc327c09" } }, "external_id__in__payments": { "name": "external_id__in", "in": "query", "description": "Return objects with these external IDs.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "446bdd9f-5b3e-4c05-9159-7a5c87cfc810" } } }, "search": { "name": "search", "in": "query", "description": "Return results that match the description you searched for. \n\n**Note:**\n\nThis filter supports both full and partial search queries, with a minimum of three characters required.\n\nFor example, searching for `trai` may match the following values:\n\n - `Awesome training sneakers` \n - `Training equipment`\n\nSearching for `car` may match the following values:\n\n - `Carlos Vives`\n - `Carmen Domínguez` \n - `carlos.vives@musicabrazil.br`\n", "schema": { "type": "string", "minLength": 3, "example": "trai" } }, "number": { "name": "number", "in": "query", "description": "Return results that exactly match this value.", "schema": { "type": "string", "example": "1231564526" } }, "number__in": { "name": "number__in", "in": "query", "description": "Return results for these bank account numbers.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "1231564526" } } }, "customer": { "name": "customer", "in": "query", "description": "The `customer.id` you want to get results for.", "schema": { "type": "string", "format": "uuid", "example": "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d" } }, "holder__type": { "name": "holder__type", "in": "query", "description": "Return results for the provided holder type.", "schema": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "example": "INDIVIDUAL" } }, "holder__type__in": { "name": "holder__type__in", "in": "query", "description": "Return results for listed holder types.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "example": "INDIVIDUAL" } } }, "customer__in": { "name": "customer__in", "in": "query", "description": "One or more `customer.id`s that you want to get results for.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "cb320adc-9a6b-4224-933a-5b08cf771ac7" } } }, "ordering__payment-intents": { "name": "ordering", "in": "query", "description": "Return results in a specified time order.\n\nCan be either:\n - `updated_at`: returns payment intents from most recently updated to last (in ascending order).\n - `-updated_at`: returns payment intents from last updated to most recently updated (in descending order).\n", "schema": { "enum": [ "updated_at", "-updated_at" ], "example": "updated_at", "type": "string" } }, "provider": { "name": "provider", "in": "query", "description": "Return results only for this provider. At present, you can only be `belvo`.", "schema": { "type": "string", "enum": [ "belvo" ], "example": "belvo" } }, "payment_method_type": { "name": "payment_method_type", "in": "query", "description": "Return results only for this payment method type. Can be either `open_finance` or `open_finance_biometric_pix`.", "schema": { "type": "string", "enum": [ "open_finance", "open_finance_biometric_pix" ], "example": "open_finance" } }, "status_payment-intents": { "name": "status", "in": "query", "description": "Return results only for this value.", "schema": { "type": "string", "example": "SUCCEEDED" } }, "status__in_payment-intents": { "name": "status__in", "in": "query", "description": "Return payment intents one of these statuses.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "PROCESSING" } } }, "updated_at": { "name": "updated_at", "in": "query", "description": "Return items that were last updated in Belvo's database on this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "updated_at__gt": { "name": "updated_at__gt", "in": "query", "description": "Return items that were last updated in Belvo's database after this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-05-05" } }, "updated_at__gte": { "name": "updated_at__gte", "in": "query", "description": "Return items that were last updated in Belvo's database after or on this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-05-04" } }, "updated_at__lt": { "name": "updated_at__lt", "in": "query", "description": "Return items that were last updated in Belvo's database before this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-04-01" } }, "updated_at__lte": { "name": "updated_at__lte", "in": "query", "description": "Return items that were last updated in Belvo's database before or on this date (in `YYYY-MM-DD` format).", "schema": { "type": "string", "format": "date", "example": "2022-03-30" } }, "updated_at__range": { "name": "updated_at__range", "in": "query", "description": "Return accounts that were last updated in Belvo's database between two dates (in `YYYY-MM-DD` format). The first value indicates the start of the range and the second value indicates the end of the range.", "style": "form", "explode": false, "schema": { "type": "array", "maxItems": 2, "items": { "type": "string", "format": "date", "example": "2022-03-03" }, "example": [ "2022-01-01", "2022-12-31" ] } }, "header_idempotency_key": { "name": "Belvo-Idempotency-Key", "in": "header", "description": "A UUID to ensure idempotent requests. This key helps prevent duplicate operations by allowing the server to recognize repeated requests with the same key and return the original response instead of processing the request again.\n\n{% admonition type=\"info\" name=\"Highly Recommended\" %}\n We highly recommend including this header in any request where you want to ensure idempotency, such as creating resources or performing actions that should not be duplicated.\n{% /admonition %}\n\nYou may receive the following errors in the case that there is an issue with your request:\n\n- `409` Conflict: If a previous request is still being processed with the same idempotency key. Check the response `Belvo-Idempotency-Status` header for the current state of that idempotency key.\n- `422` Unprocessable Entity: If a new request uses an idempotency key that has been previously used in another request containing a different payload. In this case, you should change the idempotency key to a new unique value.\n\n{% admonition type=\"warning\" name=\"In Beta\" %}\n This feature is currently in Beta and only available for selected customers. If you encounter any issues or are interested in using this feature, please contact your Belvo representative.\n{% /admonition %}\n", "schema": { "type": "string", "format": "uuid", "example": "82737f32-7730-4832-a985-dd86df70301c" } }, "charge": { "name": "charge", "in": "query", "description": "The `charge.id` you want to get results for.", "schema": { "type": "string", "format": "uuid", "example": "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d" } }, "charge__in": { "name": "charge__in", "in": "query", "description": "One or more `charge.id`s that you want to get results for.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "2f122ae2-fc09-4c6d-9940-b6220e8d191d" } } }, "beneficiary": { "name": "beneficiary", "in": "query", "description": "The `beneficiary.id` you want to get results for.", "schema": { "type": "string", "format": "uuid", "example": "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d" } }, "beneficiary__in": { "name": "beneficiary__in", "in": "query", "description": "One or more `beneficiary.id`s that you want to get results for.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "ee43f030-4feb-4a06-95e7-d8d8afe5b16e" } } }, "payer": { "name": "payer", "in": "query", "description": "The payer's `bank-account.id` you want to get results for.", "schema": { "type": "string", "format": "uuid", "example": "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d" } }, "payer__in": { "name": "payer__in", "in": "query", "description": "One or more payer `bank-account.id`s that you want to get results for.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "901bc024-be57-4972-b4cf-31664b369d6e" } } }, "transaction__type": { "name": "transaction__type", "in": "query", "description": "Return results for this transaction type. Can be either `INFLOW` or `OUTFLOW`.", "schema": { "type": "string", "enum": [ "INFLOW", "OUTFLOW" ], "example": "INFLOW" } }, "description": { "name": "description", "in": "query", "description": "Return results for items with this description.", "schema": { "type": "string", "example": "Training shoes" } }, "customer_identifier": { "name": "customer__identifier", "in": "query", "description": "The CPF of the customer you want to get results for.", "schema": { "type": "string", "minLength": 11, "maxLength": 14, "example": 23100299900 } }, "status_enrollments": { "name": "status", "in": "query", "description": "Return enrollments with the given status. Can be either:\n - `PENDING`\n - `SUCCEEDED`\n - `CANCELED`\n - `FAILED`\n", "schema": { "type": "string", "example": "PENDING" } }, "status__in_enrollments": { "name": "status__in", "in": "query", "description": "Return enrollments with these statuses:\n - `PENDING`\n - `SUCCEEDED`\n - `CANCELED`\n - `FAILED`\n", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "example": "PENDING" } } } }, "schemas": { "common_pagination_properties": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "The total number of results in your Belvo account.", "example": 130 }, "next": { "type": "string", "nullable": true, "format": "uri", "description": "The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is `null`.\n\nIn our documentation example, we use `{endpoint}` as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, `accounts` or `owners`).\n", "example": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2" }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "The URL to the previous page of results. If there is no previous page, the\nvalue is `null`.\n", "example": null } } }, "EnumInstitutionType": { "type": "string", "enum": [ "bank", "fiscal", "employment" ], "description": "The type of institution. We return one of the following values:\n\n - `bank`\n - `fiscal`\n - `employment`\n" }, "InstitutionsFormFieldValues": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the document.", "example": "001" }, "label": { "type": "string", "description": "The label for the field. For example:\n- Cédula de Ciudadanía\n- Cédula de Extranjería\n- Pasaporte\n", "example": "Cédula de Ciudadanía" }, "validation": { "type": "string", "description": "The type of input validation used for the field.", "example": "^.{1,}$" }, "validation_message": { "type": "string", "description": "The message displayed when an invalid input is provided in the form field.", "example": "Invalid document number" }, "placeholder": { "type": "string", "description": "The placeholder text in the form field.", "example": "DEF4444908M22" } } }, "InstitutionsFormField": { "type": "object", "properties": { "name": { "type": "string", "description": "The username, password, or username type field.", "example": "username" }, "type": { "type": "string", "description": "The input type for the form field. For example, string.", "example": "text" }, "label": { "type": "string", "description": "The label of the form field. For example:\n- Client number\n- Key Bancanet\n- Document\n", "example": "Client number" }, "validation": { "type": "string", "description": "The type of input validation used for the field.", "example": "^.{1,}$" }, "placeholder": { "type": "string", "description": "The placeholder text in the form field.", "example": "ABC333333A33" }, "validation_message": { "type": "string", "description": "The message displayed when an invalid input is provided in the form field.", "example": "Invalid client number" }, "values": { "type": "array", "description": "If the form field is for documents, the institution may require additional\ninput regarding the document type.\n", "items": { "$ref": "#/components/schemas/InstitutionsFormFieldValues" } } } }, "InstitutionsFeature": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the feature.", "example": "token_required" }, "description": { "type": "string", "description": "The description of the feature.", "example": "The institution may require a token during link creation or login" } } }, "EnumInstitutionIntegrationType": { "type": "string", "enum": [ "credentials", "openfinance" ], "description": "The type of technology used to access the institution. We return one of the following values:\n\n- `credentials`: Uses Belvo's scraping technology, combined with user credentials, to perform requests.\n- `openfinance`: Uses the bank's open finance API to perform requests.\n", "example": "credentials" }, "EnumInstitutionStatus": { "type": "string", "enum": [ "healthy", "down" ], "description": "Indicates whether Belvo's integration with the institution is currently active (`healthy`) or undergoing maintenance (`down`).\n", "example": "healthy" }, "InstitutionOpenBankingInformation": { "type": "object", "title": "Institution Open Banking Information", "description": "Information about the institution on the Open Finance environment.", "nullable": true, "properties": { "description": { "type": "string", "nullable": true, "description": "A short description of the institution on the Open Finance environment. Extracted from Open Finance regulated institutions listing.", "example": "A 1ss Bank é uma fintech fundada em janeiro de 2020, com a missão de ajudar empresas com grandes ecossistemas a se tornarem fintechs, integrando e automatizando seus processos financeiros através de APIs e plataforma white-label." }, "participants": { "type": "array", "nullable": true, "description": "List of brands' servers available from the institution in Open Finance. Extracted from Open Finance regulated institutions listing.", "items": { "type": "string" }, "example": [ "1ss Bank" ] }, "authorization_server_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The authorization server ID (UUID) of the institution on the Open Finance Environment.", "example": "aa18fcd3-2f0b-40b1-87db-8930b10b78b1" } } }, "InstitutionPublicApi": { "type": "object", "title": "Institution Object", "description": "Object detailing the aggregation institution.", "x-tags": [ "Institutions" ], "properties": { "id": { "type": "integer", "format": "int32", "description": "The ID of the institution as designated by Belvo.", "example": 1003 }, "name": { "type": "string", "example": "erebor_mx_retail", "description": "The name of the institution, as designated by Belvo." }, "type": { "$ref": "#/components/schemas/EnumInstitutionType" }, "website": { "type": "string", "nullable": true, "example": "https://www.erebor.com/", "description": "The URL of the institution's website." }, "display_name": { "type": "string", "example": "Erebor Mexico", "description": "The customer-facing name of the institution." }, "country_codes": { "type": "array", "description": "The country codes where the institution is available, for example:\n- 🇧🇷 BR (Brazil)\n- 🇨🇴 CO (Colombia)\n- 🇲🇽 MX (Mexico) \n", "items": { "type": "string", "example": "MX" } }, "primary_color": { "type": "string", "example": "#056dae", "description": "The primary color on the institution's website." }, "logo": { "type": "string", "nullable": true, "example": "https://belvo-api-media.s3.amazonaws.com/logos/erebor_logo.svg", "description": "The URL of the institution's logo." }, "icon_logo": { "type": "string", "nullable": true, "example": "https://statics.belvo.io/widget/images/institutions/erebor.svg", "description": "The URL of the institution's icon logo." }, "text_logo": { "type": "string", "nullable": true, "example": "https://statics.belvo.io/widget/images/institutions/erebor.svg", "description": "The URL of the institution's text logo." }, "code": { "type": "string", "deprecated": true, "nullable": true, "example": null, "description": "This field is **deprecated** and will be removed in a future release. Please use the `id` field instead, which is the unique identifier for the institution." }, "form_fields": { "type": "array", "items": { "$ref": "#/components/schemas/InstitutionsFormField" } }, "features": { "type": "array", "description": "The features that the institution supports. If the institution has no special features, then Belvo returns an empty array.\n\nHere is a list of the available features:\n- `token_required` indicates that the institution may require a token during link creation or when making any other requests.\n", "items": { "$ref": "#/components/schemas/InstitutionsFeature" } }, "resources": { "type": "array", "description": "A list of Belvo resources that you can use with the institution. This list includes one or more of the following resources:\n\n - `ACCOUNTS`\n - `BALANCES`\n - `BILLS`\n - `EMPLOYMENTS`\n - `EMPLOYMENT_RECORDS`\n - `FINANCIAL_STATEMENTS`\n - `INCOMES`\n - `INVESTMENTS`\n - `INVESTMENT_TRANSACTIONS`\n - `INVOICES`\n - `OWNERS`\n - `RECURRING_EXPENSES`\n - `RISK_INSIGHTS`\n - `TRANSACTIONS`\n - `TAX_COMPLIANCE_STATUS`\n - `TAX_RETENTIONS`\n - `TAX_RETURNS`\n - `TAX_STATUS`\n", "items": { "type": "string", "description": "A Belvo resource that the institution supports.", "example": "ACCOUNTS" }, "example": [ "ACCOUNTS", "BALANCES", "INCOMES", "OWNERS", "RECURRING_EXPENSES", "RISK_INSIGHTS", "TRANSACTIONS" ] }, "integration_type": { "$ref": "#/components/schemas/EnumInstitutionIntegrationType" }, "status": { "$ref": "#/components/schemas/EnumInstitutionStatus" }, "openbanking_information": { "$ref": "#/components/schemas/InstitutionOpenBankingInformation" } } }, "request_id": { "type": "string", "pattern": "[a-f0-9]{32}", "description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo support team to accelerate investigations.\n", "example": "9e7b283c6efa449c9c028a16b5c249fb" }, "UnauthorizedError": { "type": "object", "title": "Unauthorized Error", "description": "This error occurs when you try to make an API call using incorrect Belvo API credentials (either your secret key or secret password, or both, are incorrect).\n", "properties": { "code": { "type": "string", "description": "A unique error code (`authentication_failed`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 401 authentication_failed errors.\n", "example": "authentication_failed" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `authentication_failed` errors, the description is:\n\n - `Invalid Secret Keys`.\n", "example": "Invalid Secret Keys" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "ConsentWithoutAccountsError": { "type": "object", "title": "Consent Without Accounts", "description": "This error occurs when your user has removed accounts associated with the consent they provided. For example, when your user first generated their consent, they had a checking and a loan account at the institution but has closed those accounts since then.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`consent_without_accounts`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 401 consent_without_accounts errors.\n", "example": "consent_without_accounts" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `invalid` errors relating to `fetch_resources`, the description is:\n \n - `The institution only supports the following resources: (comma-separated list of supported resources)`.\n", "example": "The institution only supports the following resources: EMPLOYMENT_RECORDS, OWNERS" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "AccessToResourceDenied": { "type": "object", "title": "Access to Belvo API denied", "description": "This error occurs when you try to access Belvo's resource without the correct permissions.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`access_to_resource_denied`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.\n", "example": "access_to_resource_denied" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `access_to_resource_denied` errors, the description is:\n \n - `You don't have access to this resource.`.\n", "example": "You don't have access to this resource." }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "NotFoundError": { "type": "object", "title": "Not Found", "properties": { "code": { "type": "string", "description": "A unique error code (`not_found`) that allows you to classify and handle the error programmatically.\n", "example": "not_found" }, "message": { "type": "string", "description": "A short description of the error.\n\n\nFor `not_found` errors, the description is:\n\n - `Not found`\n", "example": "Not found" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "RequestTimeoutError": { "type": "object", "title": "Request Timeout", "description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`request_timeout`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.\n", "example": "request_timeout" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `request_timeout` errors, the description is:\n \n - `The request timed out, you can retry asking for less data by changing your query parameters`.\n", "example": "The request timed out, you can retry asking for less data by changing your query parameters" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "UnexpectedError": { "type": "object", "title": "Unexpected Error", "description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`unexpected_error`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.\n", "example": "unexpected_error" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `unexpected_error` errors, the description is:\n \n - `Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution`.\n", "example": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "id": { "type": "string", "format": "uuid", "description": "Belvo's unique identifier for the current item.\n", "example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d" }, "EnumLinkAccessModeResponse": { "type": "string", "nullable": true, "enum": [ "single", "recurrent", null ], "description": "The link type.\nFor more information, see our Links article.\nWe return one of the following enum values:\n - `single`\n - `recurrent`\n - `null`\n", "example": "recurrent" }, "last_accessed_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.\n", "example": "2021-03-09T10:28:40.000Z" }, "created_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the data point was created in Belvo's database.\n", "example": "2022-02-09T08:45:50.406032Z" }, "external_id": { "type": "string", "minLength": 3, "maxLength": 256, "description": "An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long.\n\n\nIf we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article.\n", "example": "56ab5706-6e00-48a4-91c9-ca55968678d9" }, "EnumLinkStatus": { "type": "string", "enum": [ "valid", "invalid", "unconfirmed", "token_required" ], "description": "The current status of the link. For more information, see our Link article in the devportal.\nWe return one of the following values:\n - `valid`\n - `invalid`\n - `unconfirmed`\n - `token_required`\n", "example": "valid" }, "created_by": { "type": "string", "format": "uuid", "description": "The unique ID for the user that created this item.", "example": "bcef7f35-67f2-4b19-b009-cb38795faf09" }, "EnumLinkRefreshRate": { "type": "string", "nullable": true, "default": "7d", "enum": [ "6h", "12h", "24h", "7d", "30d", null ], "description": "The update refresh rate for the recurrent link. For more information, check out our recurrent link documentation in our DevPortal.\nWe return one of the following enum values:\n - `6h`\n - `12h`\n - `24h`\n - `7d` (default)\n - `30d` (once a month)\n - `null` (for single links)\n", "example": "7d" }, "credentials_storage": { "type": "string", "pattern": "^(store|nostore|\\d{1,3}d)$", "description": "Indicates whether or not to store credentials (and the duration for which to store the credentials).\n\n- For recurrent links, this is set to `store` by default (and cannot be changed). \n- For single links, this is set to `365d` by default.\n\nCan be either:\n - `store` to store credentials (until the link is deleted)\n - `nostore` to not store credentials\n - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored.\n\n For more information, check out the credentials_storage section of our Data retention controls article.\n", "example": "27d" }, "stale_in": { "type": "string", "pattern": "^\\d{1,3}d$", "description": "Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article.\n\n> 📘 Info\n>\n> Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`.\n\nBy default Belvo stores user data for 365 days, unless the link is deleted.\n", "example": "42d" }, "Link": { "type": "object", "x-tags": [ "Links" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "institution": { "type": "string", "description": "Belvo's name for the institution.\n", "example": "erebor_mx_retail" }, "access_mode": { "$ref": "#/components/schemas/EnumLinkAccessModeResponse" }, "last_accessed_at": { "$ref": "#/components/schemas/last_accessed_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "institution_user_id": { "type": "string", "pattern": "[A-Za-z0-9\\-=_]{44}", "description": "> 📘 Info\n>\n> Only applicable for links created **after 08-02-2022**.\n\n\nA unique 44-character string that can be used to identify a user at a given institution.\n\n\n📚 Check out our Avoiding duplicated links DevPortal article for more information and tips on how to use it.\n", "example": "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c=" }, "status": { "$ref": "#/components/schemas/EnumLinkStatus" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "refresh_rate": { "$ref": "#/components/schemas/EnumLinkRefreshRate" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "fetch_resources": { "type": "array", "description": "An array of resources that you will receive a historical update for.\n", "items": { "type": "string", "description": "A Belvo resource that the institution supports.", "example": "ACCOUNTS" }, "example": [ "ACCOUNTS", "TRANSACTIONS" ] }, "stale_in": { "$ref": "#/components/schemas/stale_in" } } }, "EnumLinkAccessModeRequest": { "type": "string", "enum": [ "single", "recurrent" ], "description": "The type of link to create.\n\n- Use `single` to do ad hoc one-time POST requests for accounts, owners, and transactions.\n- Use `recurrent` to have Belvo access information on a recurrent basis so you always have fresh account, owner, balance, and transaction data.\n\nFor more information, see our Links article.\n", "default": "recurrent" }, "fetch_resources_employment_brazil": { "type": "array", "description": "An array of resources that you would like to receive a historical update for.\n\nFor **Employments Brazil** (INSS), you can select the following resources:\n - `EMPLOYMENTS`\n - `OWNERS`\n", "items": { "type": "string", "enum": [ "EMPLOYMENTS", "OWNERS" ] }, "example": [ "EMPLOYMENTS", "OWNERS" ] }, "LinksRequestEmploymentBrazil": { "type": "object", "title": "Employment Links (Brazil)", "description": "The request body to create a link for employment institutions in Brazil.", "required": [ "institution", "username", "password" ], "properties": { "institution": { "type": "string", "pattern": "[a-z]+_[a-z]{2}_[a-z]+", "description": "The Belvo name for the institution. For employment institutions in Brazil, you can select the following institutions:\n\n- `inss_br_employment`\n", "example": "inss_br_employment" }, "username": { "type": "string", "pattern": "^^(\\d{11}$)|(\\d{3}\\.){2}\\d{3}(-\\d{2})$", "description": "The user's CPF (ID) used to log in to the institution. You can provide this either as 11 characters or with the format `XXX.XXX.XXX-XX`.", "example": "231.002.999-00" }, "password": { "type": "string", "format": "password", "pattern": "^.{8,70}$", "description": "The user's password used to log in to the institution.\n", "example": "1234B789C234AGH" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "access_mode": { "$ref": "#/components/schemas/EnumLinkAccessModeRequest" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_employment_brazil" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "stale_in": { "$ref": "#/components/schemas/stale_in" } } }, "fetch_resources_employment_mexico": { "type": "array", "description": "An array of resources that you would like to receive a historical update for.\n\nFor **Employment Records Mexico** (IMSS and ISSSTE), you can select the following resources:\n - `EMPLOYMENT_RECORDS`\n\nAdditionally, you can opt-in to the following Employment Record specific resources (contact your representative as additional costs apply):\n - `CURRENT_EMPLOYMENTS` (IMSS only)\n - `EMPLOYMENT_METRICS` (IMSS only)\n", "items": { "type": "string", "enum": [ "EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS", "EMPLOYMENT_METRICS" ] }, "example": [ "EMPLOYMENT_RECORDS" ] }, "LinksRequestEmploymentMexico": { "type": "object", "title": "Employment Links (Mexico)", "description": "The request body to create a link for employment institutions in Mexico.", "required": [ "institution", "username" ], "properties": { "institution": { "type": "string", "pattern": "[a-z]+_[a-z]{2}_[a-z]+", "description": "The Belvo name for the institution. For employment institutions in Mexico, you can select the following institutions:\n\n- `imss_mx_employment`\n- `issste_mx_employment`\n- `planet_mx_employment` (Sandbox institution)\n", "example": "imss_mx_employment" }, "username": { "type": "string", "pattern": "^([A-Z]{4})([0-9]{6})([A-Z]{6})([A-Z0-9]{2})$", "description": "The user's CURP (ID) used to log in to the institution.", "example": "BLPM951331IONVGR54" }, "username2": { "type": "string", "description": "The user's email address used to log in to the institution. Note required for `issste_mx_employment`.", "example": "carlos@bex.com" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "access_mode": { "$ref": "#/components/schemas/EnumLinkAccessModeRequest" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_employment_mexico" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "stale_in": { "$ref": "#/components/schemas/stale_in" } } }, "fetch_resources_fiscal_mexico": { "type": "array", "description": "An array of resources that you would like to receive a historical update for.\n\nFor **Fiscal Mexico** (SAT), you can select the following resources:\n - `FINANCIAL_STATEMENTS`\n - `INVOICES`\n - `TAX_COMPLIANCE_STATUS`\n - `TAX_RETENTIONS`\n - `TAX_RETURNS`\n - `TAX_STATUS`\n", "items": { "type": "string", "enum": [ "FINANCIAL_STATEMENTS", "INVOICES", "TAX_COMPLIANCE_STATUS", "TAX_RETENTIONS", "TAX_RETURNS", "TAX_STATUS" ] }, "example": [ "FINANCIAL_STATEMENTS", "INVOICES", "TAX_COMPLIANCE_STATUS", "TAX_RETENTIONS", "TAX_RETURNS", "TAX_STATUS" ] }, "LinksRequestFiscalMexico": { "type": "object", "title": "Fiscal Links (Mexico)", "description": "The request body to create a link for fiscal institutions in Mexico.", "required": [ "institution", "username", "password" ], "properties": { "institution": { "type": "string", "pattern": "[a-z]+_[a-z]{2}_[a-z]+", "description": "The Belvo name for the institution. For fiscal institutions in Mexico, you can select the following institutions:\n\n- `sat_mx_fiscal`\n- `tatooine_mx_fiscal` (Sandbox institution)\n", "example": "sat_mx_fiscal" }, "username": { "type": "string", "pattern": "^.{12,13}$", "description": "The user's RFC (tax ID) used to log in to the institution.", "example": "123456789101" }, "password": { "type": "string", "format": "password", "pattern": "^[a-zA-Z0-9]{8}", "description": "The user's password used to log in to the institution.\n", "example": "passw0rd" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "access_mode": { "$ref": "#/components/schemas/EnumLinkAccessModeRequest" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_fiscal_mexico" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "stale_in": { "$ref": "#/components/schemas/stale_in" } } }, "TooManySessionsError": { "type": "object", "title": "Too Many Sessions", "description": "This error occurs when:\n\n - a user is attempting to log in to their institution via Belvo while also already being logged in to their institution on a web browser or mobile app.\n - you make a request for information while Belvo is scraping data from the institution for that user.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`too_many_sessions`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 too_many_sessions errors.\n", "example": "too_many_sessions" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `too_many_sessions` errors, the description is:\n \n - `Impossible to login, a session is already opened with the institution for these credentials`.\n", "example": "Impossible to login, a session is already opened with the institution for these credentials" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "LoginError": { "type": "object", "title": "Login Error", "description": "This error can occur when:\n\n - the credentials that your user provides are incorrect or missing.\n - the MFA token your user provides is not supported by Belvo.\n - there is an issue with the institution that prevents logins.\n - the user's account is either locked or the user does not have permission to access their internet banking.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`login_error`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 login_error errors.\n", "example": "login_error" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `login_error` errors, the description can be one of the following:\n\n - `Invalid credentials provided to login to the institution`\n - `A MFA token is required by the institution, but it's not supported yet by Belvo.`\n - `Impossible to login, something unexpected happened while logging into the institution. Try again later.`\n - `Login not attempted due to invalid credentials`\n - `Missing credentials to login to the institution`\n - `The user account access was forbidden by the institution`\n - `The user account is locked, user needs to contact the institution to unlock it`\n \n", "example": "Invalid credentials provided to login to the institution" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "SessionExpiredError": { "type": "object", "title": "Session Expired", "description": "This error occurs when you try to resume a request session that has already expired. This is usually because the user took too long to provide their authentication token.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`session_expired`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 session_expired errors.\n", "example": "session_expired" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `session_expired` errors, the description is:\n \n - `The session you are trying to resume has expired, please start again from register/retrieve endpoint`.\n", "example": "The session you are trying to resume has expired, please start again from register/retrieve endpoint" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "ValidationError": { "type": "object", "title": "Validation Error", "description": "This error occurs when make a request that does not include all the required fields or includes invalid data.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`null`, `does_not_exist`, `required`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle:\n - 400 blank errors\n - 400 null errors\n - 400 does_not_exist errors\n - 400 required errors\n", "example": "required" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor validation errors, the description can be (among others):\n \n - `This field is required.`\n - `Object with name=narnia does not exist.`\n - `This field may not be null.`\n - `This field may not be blank.`\n", "example": "This field is required." }, "request_id": { "$ref": "#/components/schemas/request_id" }, "field": { "type": "string", "nullable": true, "description": "Name of the field where the error was encountered.\n", "example": "link" } } }, "InstitutionDownError": { "type": "object", "title": "Institution Down", "description": "This error occurs when the institution's website that you're trying to access is down due to maintenance or other issues, which means Belvo is unable to create new links or retrieve new data.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`institution_down`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 institution_down errors.\n", "example": "institution_down" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `institution_down` errors, the description is:\n \n - `The financial institution is down, try again later`.\n", "example": "The financial institution is down, try again later" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InstitutionUnavailableError": { "type": "object", "title": "Institution Unavailable", "description": "This error occurs when the institution's website that you're trying to access is down due to maintenance or other issues, which means Belvo is unable to create new links or retrieve new data.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`institution_unavailable`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how handle 400 institution_unavailable errors.\n", "example": "institution_unavailable" }, "message": { "type": "string", "description": "A short description of the error.\n\n\nFor `institution_unavailable` errors, the description is:\n \n - `The financial institution is unavailable`.\n", "example": "The financial institution is unavailable" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InstitutionInactiveError": { "type": "object", "title": "Institution Inactive", "description": "This error occurs when we (Belvo) have deactivated the institution in our API.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`institution_inactive`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 institution_inactive errors.\n", "example": "institution_inactive" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `institution_inactive` errors, the description is:\n \n - `The institution has been temporarily deactivated`.\n", "example": "The institution has been temporarily deactivated" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InvalidLinkError": { "type": "object", "title": "Invalid Link", "description": "This error occurs when you try to access an account but the user credentials are no longer valid, prompting an error from the institution.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`invalid_link`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 invalid_link errors.\n", "example": "invalid_link" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `invalid_link` errors, the description is:\n \n - `The link has been invalidated. You may need to update link credentials`.\n", "example": "The link has been invalidated. You may need to update link credentials" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InvalidCredentialsStorageError": { "type": "object", "title": "Invalid Credentials Storage", "description": "This error occurs when you attempted to create a **recurrent** link where you set `credentials_storage` to either `nostore` or to a date range between `1d` to `365d`.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`invalid_credentials_storage`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 invalid_credentials_storage errors.\n", "example": "login_error" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `invalid_credentials_storage` errors, the description can be one of the following:\n\n - `Recurrent links must store the credentials`\n \n", "example": "Recurrent links must store the credentials" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InvalidFetchHistorical": { "type": "object", "title": "Invalid Fetch Resources", "description": "This error occurs when you attempted to create a link where you set `credentials_storage` to `nostore` and did not send any resources in the `fetch_resources`. For links where we don't store credentials, you must send through an array of resources in `fetch_resources`.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`invalid_fetch_resources`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 invalid_fetch_resources errors.\n", "example": "invalid_fetch_resources" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `invalid_fetch_resources` errors, the description can be one of the following:\n\n - `Single links without stored credentials must fetch resources`\n \n", "example": "Single links without stored credentials must fetch resources" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InvalidResourcesError": { "type": "object", "title": "Invalid Resources", "description": "This error occurs when you attempted to create a link where you added resources in `fetch_resources` that are unsupported by the institution.\n", "properties": { "field": { "type": "string", "description": "The request parameter that is causing the error. For invalid resources, this will be set to `resources`.\n", "example": "resources" }, "code": { "type": "string", "description": "A unique error code (`invalid`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 invalid_period errors.\n", "example": "invalid" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `invalid` errors relating to `fetch_resources`, the description is:\n \n - `The institution only supports the following resources: (comma-separated list of supported resources)`.\n", "example": "The institution only supports the following resources: EMPLOYMENT_RECORDS, OWNERS" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "UnconfirmedLinkError": { "type": "object", "title": "Unconfirmed Link", "description": "This error occurs when you try to access a link that was paused previously (and as such is not active now).\n\nA Link's status is set to `unconfirmed_link` when your user has not completed the Link creation process successfully (for example, they might not provide a valid MFA token).\n", "properties": { "code": { "type": "string", "description": "A unique error code (`unconfirmed_link`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 unconfirmed_link errors.\n", "example": "unconfirmed_link" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `unconfirmed_link` errors, the description is:\n \n - `The link creation has not been completed yet`.\n", "example": "The link creation has not been completed yet" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "UnsupportedOperationError": { "type": "object", "title": "Unsupported Operation", "description": "This error occurs when you try to access some data operation that Belvo does not support for an institution. For example, trying to access the Balances resource for fiscal institutions.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`unsupported_operation`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 unsupported_operation errors.\n", "example": "unsupported_operation" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `unsupported_operation` errors, the description is:\n \n - `The resource you are trying to access is not supported by this institution`.\n", "example": "The resource you are trying to access is not supported by this institution" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "InvalidPeriodError": { "type": "object", "title": "Invalid Period", "description": "This error occurs when you request incomes for a link within a given date range, however, the period between `date_from` and `date_to` is less than 90 days.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`invalid_period`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 400 invalid_period errors.\n", "example": "invalid_period" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `invalid_period` errors, the description is:\n \n - `The number of days between date_from and date_to must be at least 90 days`.\n", "example": "The number of days between date_from and date_to must be at least 90 days" }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "TokenRequiredResponse": { "type": "object", "description": "MFA Token Required", "properties": { "code": { "type": "string", "description": "A unique error code (`token_required`) that allows you to classify and handle the error programmatically.\nℹ️ Check our DevPortal for more information on how to handle 428 token_required errors.\n", "example": "token_required" }, "message": { "type": "string", "description": "A short description of the error. \nFor `token_required` errors, the description is:\n \n - `A MFA token is required by the institution to login`.\n", "example": "A MFA token is required by the institution to login" }, "request_id": { "$ref": "#/components/schemas/request_id" }, "session": { "type": "string", "pattern": "[a-f0-9]{32}", "description": "A 32-character unique ID of the login session (matching a regex pattern of: `[a-f0-9]{32}`).\n", "example": "2675b703b9d4451f8d4861a3eee54449" }, "expiry": { "type": "integer", "format": "int32", "description": "Session duration time in seconds.", "example": 9600 }, "link": { "type": "string", "format": "uuid", "description": "Unique identifier created by Belvo, used to reference the current\nLink.\n", "example": "30cb4806-6e00-48a4-91c9-ca55968576c8" }, "token_generation_data": { "type": "object", "description": "Details on how to generate the token.", "properties": { "instructions": { "type": "string", "description": "Instructions for token generation.", "example": "Use this code to generate the token" }, "type": { "type": "string", "description": "Type of the data to generate the token (QR code, numeric\nchallenge).\n", "example": "numeric" }, "value": { "type": "string", "description": "Value to use to generate the token.", "example": "12345" }, "expects_user_input": { "type": "boolean", "description": "Indicates whether the user needs to provide input in order to complete the authentication.\nWhen set to `false`, your user may need to:\n- confirm the login on another device\n- scan a QR code\nYou will still need to make a PATCH call to complete the request.\n", "example": true, "default": true } } } } }, "token": { "type": "string", "description": "The MFA token generated by the institution which is required to continue a session.", "example": "1234ab" }, "save_data": { "type": "boolean", "default": true, "description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n", "example": true }, "PatchBody": { "type": "object", "description": "A JSON object containing a session UUID and a MFA token", "required": [ "session", "link" ], "properties": { "session": { "type": "string", "pattern": "[a-f0-9]{32}", "description": "The session you want to resume. You need to use the `session` value\nthat is provided in the 428 Token Required response that you receive\nafter you make your POST request.\n", "example": "6e7b283c6efa449c9c028a16b5c249fa" }, "token": { "$ref": "#/components/schemas/token" }, "link": { "type": "string", "format": "uuid", "description": "The `link.id` you want to resume. Must be the same `link.id` as the\none you receive in the 428 Token Required response that contains the\n`session` ID.\n", "example": "683005d6-f45c-4adb-b289-f1a12f50f80c" }, "save_data": { "$ref": "#/components/schemas/save_data" } } }, "LinksPutRequest": { "type": "object", "required": [ "institution", "username", "password" ], "properties": { "password": { "type": "string", "description": "The end-user's password used to log in to the institution.", "example": "password" }, "password2": { "type": "string", "description": "The end-user's second password used to log in to the\ninstitution.\n\n\n> 📘 Info\n>\n> This is only required by some institutions. To know which\ninstitutions require a second password, see our List institution request and check the `form_fields` array in the\nresponse.\n", "example": "pin" }, "token": { "$ref": "#/components/schemas/token" } } }, "ChangeAccessMode": { "type": "object", "description": "Request body to change the access mode, stale_in, or fetch_resources of a link.", "properties": { "access_mode": { "$ref": "#/components/schemas/EnumLinkAccessModeRequest" }, "stale_in": { "$ref": "#/components/schemas/stale_in" }, "fetch_resources": { "type": "array", "description": "An array of resources that you would like to receive a historical update for.\n\nFor banking institutions, you can select the following resources:\n - `ACCOUNTS`\n - `OWNERS`\n - `TRANSACTIONS`\n - `BILLS`\n - `INVESTMENTS`\n - `INVESTMENT_TRANSACTIONS`\n - `INCOMES`\n - `RECURRING_EXPENSES`\n - `RISK_INSIGHTS`\n\n\nFor fiscal institutions, you can select the following resources:\n - `FINANCIAL_STATEMENTS`\n - `INVOICES`\n - `TAX_COMPLIANCE_STATUS`\n - `TAX_RETENTIONS`\n - `TAX_RETURNS`\n - `TAX_STATUS`\n\nFor employment institutions, you can select the following resources:\n - `EMPLOYMENT_RECORDS`(For Mexico's IMSS and ISSTE only)\n - `EMPLOYMENT_METRICS` (For Mexico's IMSS only)\n - `EMPLOYMENTS` (For Brazil's INSS only)\n \n", "items": { "type": "string", "description": "A Belvo resource that the institution supports.", "example": "ACCOUNTS" }, "example": [ "ACCOUNTS", "TRANSACTIONS" ] } } }, "LinkAlreadyRefreshedError": { "type": "object", "title": "Link Already Refreshed Error", "properties": { "code": { "type": "string", "description": "A unique error code (`link_refreshed`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle 409 link_refreshed errors.\n", "example": "link_refreshed" }, "message": { "type": "string", "description": "A short description of the error. \n\n\nFor `link_refreshed` errors, the description is:\n \n - `The link has already been refreshed. Please wait X minutes before trying again.`\n", "example": "The link has already been refreshed. Please wait 7 minutes before trying again." }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "EnumConsentStatus": { "type": "string", "nullable": true, "enum": [ "AUTHORISED", "AWAITING_AUTHORISATION_CONFIRMATION", "AWAITING_AUTHORISATION", "REJECTED", "EXPIRED", null ], "description": "The status of the consent in the open finance network. Can be either:\n\n - `AUTHORISED`: The consent is still valid for use until the `expired_at` date.\n - `AWAITING_AUTHORISATION_CONFIRMATION`: The user must confirm within their institution.\n - `AWAITING_AUTHORISATION`: The user has been redirected to their institution to grant consent.\n - `REJECTED`: The user has not granted consent within their institution.\n - `EXPIRED`: The consent has expired as of the `expired_at` date.\n - `null`\n", "example": "AUTHORISED" }, "Consents": { "type": "object", "description": "The OFDA consents schema", "title": "Consents Object (Brazil)", "x-tags": [ "Consents" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "display_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The full name of the individual that initiated the consent, as provided by the institution.\n", "example": "Jack Oswald White" }, "document_number": { "type": "string", "description": "The document number (CPF) of the individual.\n", "example": "76109277673" }, "belvo_institution_name": { "type": "string", "description": "Belvo's name for the open finance institution that the consent is related to.\n", "example": "ofmockbank_br_retail" }, "institution_display_name": { "type": "string", "description": "The display name of the banking institution that the consent is related to.\n", "example": "Mock Bank" }, "institution_icon_logo": { "type": "string", "description": "The URL to the banking institution's logo.\n", "example": "https://assets.belvo.io/institutions/mockbank/logo.svg" }, "belvo_organization_name": { "type": "string", "description": "The name registered in Belvo of the organization that created the link.\n", "example": "ACME Corporation" }, "link_id": { "type": "string", "format": "uuid", "description": "The Belvo link ID that the consent belongs to.\n", "example": "2e5d2c5e-6b3a-4b5c-8d1e-9f0a1b2c3d4e" }, "user_name": { "type": "string", "nullable": true, "description": "The name provided in `consent.identification_info.name` during the initial Widget Access Token Request.\n", "example": "Jack White" }, "expired_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp when the consent will expire. In the case that `undefined_consent_expiration` is `true`, this field will be `null`.", "example": "2021-02-27T13:01:41.941Z" }, "undefined_consent_expiration": { "type": "boolean", "description": "Indicated whether the consent is for an undefined period, that is, that there is no expiration for the consent.", "example": false }, "consent_duration": { "type": "integer", "nullable": true, "description": "The duration of the consent in days. In the case that `undefined_consent_expiration` is `true`, this field will be `null`.\n\nPossible values:\n- `92` (3 months)\n- `183` (6 months)\n- `275` (9 months)\n- `366` (12 months)\n", "example": 366 }, "created_at": { "$ref": "#/components/schemas/created_at" }, "status": { "$ref": "#/components/schemas/EnumConsentStatus" }, "permissions": { "type": "object", "description": "Details regarding the permissions attached to the consent.", "properties": { "ACCOUNTS": { "type": "array", "description": "A list of of open banking permissions relating to accessing account information.", "items": { "type": "string", "example": "ACCOUNTS_OVERDRAFT_LIMITS_READ" }, "example": [ "ACCOUNTS_OVERDRAFT_LIMITS_READ", "ACCOUNTS_READ", "ACCOUNTS_TRANSACTIONS_READ", "ACCOUNTS_BALANCES_READ" ] }, "CREDIT_CARDS": { "type": "array", "description": "A list of of open banking permissions relating to accessing credit card information.", "items": { "type": "string", "example": "CREDIT_CARDS_ACCOUNTS_LIMITS_READ" }, "example": [ "CREDIT_CARDS_ACCOUNTS_LIMITS_READ", "CREDIT_CARDS_ACCOUNTS_BILLS_READ", "CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ", "CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ", "CREDIT_CARDS_ACCOUNTS_READ" ] }, "CREDIT_OPERATIONS": { "type": "array", "description": "A list of of open banking permissions relating to accessing credit product information.", "items": { "type": "string", "example": "LOANS_READ" }, "example": [ "LOANS_READ", "LOANS_WARRANTIES_READ", "LOANS_SCHEDULED_INSTALMENTS_READ", "LOANS_PAYMENTS_READ", "FINANCINGS_READ", "FINANCINGS_WARRANTIES_READ", "FINANCINGS_SCHEDULED_INSTALMENTS_READ", "FINANCINGS_PAYMENTS_READ", "UNARRANGED_ACCOUNTS_OVERDRAFT_READ", "UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ", "UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ", "UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ", "INVOICE_FINANCINGS_READ", "INVOICE_FINANCINGS_WARRANTIES_READ", "INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ", "INVOICE_FINANCINGS_PAYMENTS_READ" ] }, "REGISTER": { "type": "array", "description": "A list of of open banking permissions relating to accessing personal information.", "items": { "type": "string", "example": "CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ" }, "example": [ "CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ", "CUSTOMERS_PERSONAL_ADITTIONALINFO_READ" ] }, "RESOURCES": { "type": "array", "description": "A list of functional permissions required to interact with the permissions.", "items": { "type": "string", "example": "RESOURCES_READ" }, "example": [ "RESOURCES_READ" ] }, "INVESTMENTS": { "type": "array", "description": "A list of open banking permissions relating to accessing investment information.", "items": { "type": "string", "example": "BANK_FIXED_INCOMES_READ" }, "example": [ "BANK_FIXED_INCOMES_READ", "CREDIT_FIXED_INCOMES_READ", "FUNDS_READ", "VARIABLE_INCOMES_READ", "TREASURE_TITLES_READ" ] } } } } }, "fetch_resources_ofda_brazil": { "type": "array", "description": "An array of resources that you would like to receive a historical update for.\n\n{% admonition type=\"warning\" name=\"Wait for Webhooks Before Retrieving Data\" %}\n After requesting resources using `fetch_resources`, you **must** wait for the historical update webhook from Belvo before retrieving the data. Making requests before receiving the webhook (GET or POST) will return empty or incomplete results.\n{% /admonition %}\n\nFor OFDA Brazil, you can select the following resources:\n - `ACCOUNTS`\n - `OWNERS`\n - `TRANSACTIONS`\n - `BILLS`\n\nAdditionally, you can opt-in to the following Open Finance specific resources (contact your representative as additional costs apply):\n - `INVESTMENTS`\n - `INVESTMENT_TRANSACTIONS`\n - `EXCHANGES`\n\nFor OFDA, you can enable Enrichment resources for extended insights (contact your representative as additional costs apply):\n - `INCOMES`\n - `RECURRING_EXPENSES`\n - `RISK_INSIGHTS`\n\n{% admonition type=\"info\" name=\"Enrichment Resources Require Transaction Data\" %}\n To calculate enrichment resources (`INCOMES`, `RECURRING_EXPENSES`, `RISK_INSIGHTS`), you must also include `ACCOUNTS` and `TRANSACTIONS` in your `fetch_resources` array. Without these foundational resources, enrichment calculations will be incomplete or may not be generated.\n{% /admonition %}\n", "items": { "type": "string", "enum": [ "ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS", "EXCHANGES", "INCOMES", "RECURRING_EXPENSES", "RISK_INSIGHTS" ] }, "example": [ "ACCOUNTS", "TRANSACTIONS", "OWNERS", "BILLS" ] }, "WidgetTokenRequestBankingBrazil": { "type": "object", "title": "OFDA 🇧🇷 Brazil Access Token", "required": [ "id", "password", "scopes", "stale_in", "fetch_resources", "widget" ], "properties": { "id": { "type": "string", "description": "Your Belvo secretId." }, "password": { "type": "string", "description": "Your Belvo secretPassword." }, "scopes": { "type": "string", "description": "The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown.\n", "example": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_ofda_brazil" }, "stale_in": { "$ref": "#/components/schemas/stale_in" }, "widget": { "type": "object", "description": "The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. \n", "required": [ "openfinance_feature", "callback_urls", "branding", "consent" ], "properties": { "openfinance_feature": { "type": "string", "description": "The `openfinance_feature` parameter indicates that the end user will go through the OFDA flow. It must be set to `consent_link_creation`", "example": "consent_link_creation" }, "callback_urls": { "type": "object", "description": "In the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases:\n\n- success (your user successfully connected their accounts)\n- exit (your user exited the widget before they completed the process)\n- event (an error occurred during the connection process)\n\nFor more information, check out the callback_urls section in our Hosted Widget (OFDA) guide.\n\n> 📘 Callback Events\n>\n> Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (OFDA) guide.\n", "required": [ "success", "exit", "event" ], "properties": { "success": { "type": "string", "description": "The URL your user is redirected to when they successfully connects their account.", "example": "your_deeplink_here://success" }, "exit": { "type": "string", "description": "The URL your user is redirected to when they exit the process before connecting their account.", "example": "your_deeplink_here://exit" }, "event": { "type": "string", "description": "The URL your user is redirected to when they encounter an error while connecting their account.", "example": "your_deeplink_here://error" } } }, "branding": { "type": "object", "description": "In the `branding` object, you **must** add your:\n- company_icon\n- company_logo\n- company_name\n- company_terms_url\n\nYou can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected.\n\nFor more information about the branding and customization options of the widget, check out our dedicated guide.\n", "required": [ "company_icon", "company_logo", "company_name", "company_terms_url" ], "properties": { "company_icon": { "type": "string", "format": "uri", "description": "You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (OFDA) guide.", "example": "https://mysite.com/icon.svg" }, "company_logo": { "type": "string", "format": "uri", "description": "You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (OFDA) guide.", "example": "https://mysite.com/logo.svg" }, "company_name": { "type": "string", "description": "You can add your company name to be displayed when the widget first starts. By default, it'll just display \"Link your account\". When you add your company name, the message will follow the format \"[company_name] uses Belvo to connect your account\". For more information, see the company_name section of our Branding and customization (OFDA) guide.", "example": "ACME" }, "company_terms_url": { "type": "string", "format": "uri", "description": "You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (OFDA) guide.", "example": "https://belvo.com/terms-service/" }, "overlay_background_color": { "type": "string", "description": "You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (OFDA) guide.", "example": "#F0F2F4" }, "social_proof": { "type": "boolean", "description": "You can choose to hide the \"Mais de 5 milhões de usuários já conectaram com segurança suas contas.\" message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (OFDA) guide.", "example": true }, "show_belvo_middle_logo": { "type": "boolean", "description": "You can choose to display the Belvo logo between your company logo and the institution logo on the initial connect screen. When set to `true`, the Belvo logo will be displayed. Defaults to `false`. For more information, see the show_belvo_middle_logo section of our OFDA Widget Branding and Customization guide.", "example": false } } }, "theme": { "type": "array", "description": "You can optionally add your brand colors to the widget using the `theme` parameter. \n\nFor more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide.\n", "items": { "type": "object", "required": [ "css_key", "value" ], "properties": { "css_key": { "type": "string", "description": "CSS variable name. Possible values include:\n- `--color-primary-base`\n- `--nav-bar-title-color`\n- `--nav-bar-icon-color`\n", "example": "--color-primary-base" }, "value": { "type": "string", "description": "The HEX code for the `css_key`.", "example": "#907AD6" } } } }, "consent": { "type": "object", "description": "The `consent` object is unique to the OFDA widget and must be sent through.", "required": [ "purpose", "terms_and_conditions_url", "permissions", "identification_info" ], "properties": { "purpose": { "type": "string", "maxLength": 140, "description": "In the `purpose` parameter, you can customize the messaging that is displayed to your user regarding for what use case you are requesting their data\nFor more information, check out the purpose section in our Hosted Widget (OFDA) guide.\n", "example": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito." }, "terms_and_conditions_url": { "type": "string", "format": "uri", "description": "In the `terms_and_conditions_url` parameter, you **must** provide a link to your company's terms and conditions.", "example": "https://www.your_terms_and_conditions.com" }, "permissions": { "type": "array", "minItems": 4, "maxItems": 4, "uniqueItems": true, "description": "The `permissions` parameter contains the resources that you want to extract from Brazil's Open Finance Network for the user. This value **must** be set to `[\"REGISTER\", \"ACCOUNTS\", \"CREDIT_CARDS\",\"CREDIT_OPERATIONS\"]`.\n", "items": { "type": "string", "enum": [ "REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS" ] }, "example": [ "REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS" ] }, "identification_info": { "type": "array", "minItems": 1, "maxItems": 2, "description": "In the `identification_info` array, you need to provide the identification information of the user that you want to retrieve information for. The information that you provide here must match the information that the regulated institution has for the user (for example, for businesses, the CPF and name must be for a user with access to the business account).\n\n- For individuals, you just need to provide the CPF and name. \n- For businesses, you need to provide both the CPF and CNPJ information. \n\nFor more information, check out the identification_info section of our Hosted Widget (OFDA) guide.\n", "items": { "type": "object", "required": [ "type", "number", "name" ], "properties": { "type": { "type": "string", "description": "The identifier type. Can be either `CPF` or `CNPJ`.", "example": "CPF" }, "number": { "type": "string", "description": "The CPF or CNPJ number of the individual or company associated with the identification.", "example": 76109277673 }, "name": { "type": "string", "description": "Name of the individual or company associated with the identification.", "example": "Ralph Bragg" } } } }, "default_consent_duration_days": { "type": "number", "description": "You can preselect the consent duration in the dropdown menu. The `default_consent_duration_days` parameter accepts `366`, `275`, `183`, or `92` days (corresponding to 12, 9, 6, or 3 months). If you provide any other value, the dropdown will default to \"Indeterminado\" (indefinite). For more information, see the default_consent_duration_days section of our OFDA Widget Branding and Customization guide.\n", "example": 183, "enum": [ 92, 183, 275, 366 ] } } } } } } }, "WidgetTokenRequestEmploymentBrazil": { "type": "object", "title": "Employments 🇧🇷 Brazil Access Token", "required": [ "id", "password", "scopes", "stale_in", "fetch_resources", "widget" ], "properties": { "id": { "type": "string", "description": "Your Belvo secretId." }, "password": { "type": "string", "description": "Your Belvo secretPassword." }, "scopes": { "type": "string", "description": "The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown.\n", "example": "read_institutions,write_links" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_employment_brazil" }, "stale_in": { "$ref": "#/components/schemas/stale_in" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "widget": { "type": "object", "description": "The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. \n", "required": [ "branding" ], "properties": { "callback_urls": { "type": "object", "description": "> 📘 Only required for the Hosted Widget.\n\nIn the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases:\n\n- success (your user successfully connected their accounts)\n- exit (your user exited the widget before they completed the process)\n- event (an error occurred during the connection process)\n\nFor more information, check out the callback_urls section in our Hosted Widget (Multi-Region) guide.\n\n> 📘 Callback Events\n>\n> Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (Multi-Region) guide.\n", "required": [ "success", "exit", "event" ], "properties": { "success": { "type": "string", "description": "The URL your user is redirected to when they successfully connects their account.", "example": "your_deeplink_here://success" }, "exit": { "type": "string", "description": "The URL your user is redirected to when they exit the process before connecting their account.", "example": "your_deeplink_here://exit" }, "event": { "type": "string", "description": "The URL your user is redirected to when they encounter an error while connecting their account.", "example": "your_deeplink_here://error" } } }, "branding": { "type": "object", "description": "In the `branding` object, you **must** add your:\n- company_icon\n- company_logo\n- company_name\n- company_terms_url\n\nYou can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected.\n\nFor more information about the branding and customization options of the widget, check out our dedicated guide.\n", "required": [ "company_icon", "company_logo", "company_name", "company_terms_url" ], "properties": { "company_icon": { "type": "string", "format": "uri", "description": "You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide.", "example": "https://mysite.com/icon.svg" }, "company_logo": { "type": "string", "format": "uri", "description": "You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide.", "example": "https://mysite.com/logo.svg" }, "company_name": { "type": "string", "description": "You can add your company name to be displayed when the widget first starts. By default, it'll just display \"Link your account\". When you add your company name, the message will follow the format \"[company_name] uses Belvo to connect your account\". For more information, see the company_name section of our Branding and customization (Multi-Region) guide.", "example": "ACME" }, "company_terms_url": { "type": "string", "format": "uri", "description": "You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (Multi-Region) guide.", "example": "https://belvo.com/terms-service/" }, "company_terms_version": { "type": "string", "description": "The version of your terms and conditions. Use this parameter alongside `company_terms_url` to track which version of your T&C the user accepted during the widget flow.", "example": "20260323" }, "overlay_background_color": { "type": "string", "description": "You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (Multi-Region) guide.", "example": "#F0F2F4" }, "social_proof": { "type": "boolean", "description": "You can choose to hide the \"Mais de 5 milhões de usuários já conectaram com segurança suas contas.\" message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (Multi-Region) guide.", "example": true } } }, "theme": { "type": "array", "description": "You can optionally add your brand colors to the widget using the `theme` parameter. \n\nFor more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide.\n", "items": { "type": "object", "required": [ "css_key", "value" ], "properties": { "css_key": { "type": "string", "description": "CSS variable name. Possible values include:\n- `--color-primary-base`\n- `--nav-bar-title-color`\n- `--nav-bar-icon-color`\n", "example": "--color-primary-base" }, "value": { "type": "string", "description": "The HEX code for the `css_key`.", "example": "#907AD6" } } } } } } } }, "WidgetTokenRequestEmploymentMexico": { "type": "object", "title": "Employment Records 🇲🇽 Mexico Access Token", "required": [ "id", "password", "scopes", "stale_in", "fetch_resources", "widget" ], "properties": { "id": { "type": "string", "description": "Your Belvo secretId." }, "password": { "type": "string", "description": "Your Belvo secretPassword." }, "scopes": { "type": "string", "description": "The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown.\n", "example": "read_institutions,write_links" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_employment_mexico" }, "stale_in": { "$ref": "#/components/schemas/stale_in" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "widget": { "type": "object", "description": "The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. \n", "required": [ "branding" ], "properties": { "callback_urls": { "type": "object", "description": "> 📘 Only required for the Hosted Widget.\n\nIn the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases:\n\n- success (your user successfully connected their accounts)\n- exit (your user exited the widget before they completed the process)\n- event (an error occurred during the connection process)\n\nFor more information, check out the callback_urls section in our Hosted Widget (Multi-Region) guide.\n\n> 📘 Callback Events\n>\n> Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (Multi-Region) guide.\n", "required": [ "success", "exit", "event" ], "properties": { "success": { "type": "string", "description": "The URL your user is redirected to when they successfully connects their account.", "example": "your_deeplink_here://success" }, "exit": { "type": "string", "description": "The URL your user is redirected to when they exit the process before connecting their account.", "example": "your_deeplink_here://exit" }, "event": { "type": "string", "description": "The URL your user is redirected to when they encounter an error while connecting their account.", "example": "your_deeplink_here://error" } } }, "branding": { "type": "object", "description": "In the `branding` object, you **must** add your:\n- company_icon\n- company_logo\n- company_name\n- company_terms_url\n\nYou can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected.\n\nFor more information about the branding and customization options of the widget, check out our dedicated guide.\n", "required": [ "company_icon", "company_logo", "company_name", "company_terms_url" ], "properties": { "company_icon": { "type": "string", "format": "uri", "description": "You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide.", "example": "https://mysite.com/icon.svg" }, "company_logo": { "type": "string", "format": "uri", "description": "You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide.", "example": "https://mysite.com/logo.svg" }, "company_name": { "type": "string", "description": "You can add your company name to be displayed when the widget first starts. By default, it'll just display \"Link your account\". When you add your company name, the message will follow the format \"[company_name] uses Belvo to connect your account\". For more information, see the company_name section of our Branding and customization (Multi-Region) guide.", "example": "ACME" }, "company_terms_url": { "type": "string", "format": "uri", "description": "You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (Multi-Region) guide.", "example": "https://belvo.com/terms-service/" }, "company_terms_version": { "type": "string", "description": "The version of your terms and conditions. Use this parameter alongside `company_terms_url` to track which version of your T&C the user accepted during the widget flow.", "example": "20260323" }, "overlay_background_color": { "type": "string", "description": "You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (Multi-Region) guide.", "example": "#F0F2F4" }, "social_proof": { "type": "boolean", "description": "You can choose to hide the \"Mais de 5 milhões de usuários já conectaram com segurança suas contas.\" message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (Multi-Region) guide.", "example": true } } }, "theme": { "type": "array", "description": "You can optionally add your brand colors to the widget using the `theme` parameter. \n\nFor more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide.\n", "items": { "type": "object", "required": [ "css_key", "value" ], "properties": { "css_key": { "type": "string", "description": "CSS variable name. Possible values include:\n- `--color-primary-base`\n- `--nav-bar-title-color`\n- `--nav-bar-icon-color`\n", "example": "--color-primary-base" }, "value": { "type": "string", "description": "The HEX code for the `css_key`.", "example": "#907AD6" } } } } } } } }, "WidgetTokenRequestFiscalMexico": { "type": "object", "title": "Fiscal 🇲🇽 Mexico Access Token", "required": [ "id", "password", "scopes", "stale_in", "fetch_resources", "widget" ], "properties": { "id": { "type": "string", "description": "Your Belvo secretId." }, "password": { "type": "string", "description": "Your Belvo secretPassword." }, "scopes": { "type": "string", "description": "The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown.\n", "example": "read_institutions,write_links" }, "fetch_resources": { "$ref": "#/components/schemas/fetch_resources_fiscal_mexico" }, "stale_in": { "$ref": "#/components/schemas/stale_in" }, "credentials_storage": { "$ref": "#/components/schemas/credentials_storage" }, "widget": { "type": "object", "description": "The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. \n", "required": [ "branding" ], "properties": { "callback_urls": { "type": "object", "description": "> 📘 Only required for the Hosted Widget.\n\nIn the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases:\n\n- success (your user successfully connected their accounts)\n- exit (your user exited the widget before they completed the process)\n- event (an error occurred during the connection process)\n\nFor more information, check out the callback_urls section in our Hosted Widget (Multi-Region) guide.\n\n> 📘 Callback Events\n>\n> Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (Multi-Region) guide.\n", "required": [ "success", "exit", "event" ], "properties": { "success": { "type": "string", "description": "The URL your user is redirected to when they successfully connects their account.", "example": "your_deeplink_here://success" }, "exit": { "type": "string", "description": "The URL your user is redirected to when they exit the process before connecting their account.", "example": "your_deeplink_here://exit" }, "event": { "type": "string", "description": "The URL your user is redirected to when they encounter an error while connecting their account.", "example": "your_deeplink_here://error" } } }, "branding": { "type": "object", "description": "In the `branding` object, you **must** add your:\n- company_icon\n- company_logo\n- company_name\n- company_terms_url\n\nYou can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected.\n\nFor more information about the branding and customization options of the widget, check out our dedicated guide.\n", "required": [ "company_icon", "company_logo", "company_name", "company_terms_url" ], "properties": { "company_icon": { "type": "string", "format": "uri", "description": "You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide.", "example": "https://mysite.com/icon.svg" }, "company_logo": { "type": "string", "format": "uri", "description": "You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide.", "example": "https://mysite.com/logo.svg" }, "company_name": { "type": "string", "description": "You can add your company name to be displayed when the widget first starts. By default, it'll just display \"Link your account\". When you add your company name, the message will follow the format \"[company_name] uses Belvo to connect your account\". For more information, see the company_name section of our Branding and customization (Multi-Region) guide.", "example": "ACME" }, "company_terms_url": { "type": "string", "format": "uri", "description": "You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (Multi-Region) guide.", "example": "https://belvo.com/terms-service/" }, "company_terms_version": { "type": "string", "description": "The version of your terms and conditions. Use this parameter alongside `company_terms_url` to track which version of your T&C the user accepted during the widget flow.", "example": "20260323" }, "overlay_background_color": { "type": "string", "description": "You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (Multi-Region) guide.", "example": "#F0F2F4" }, "social_proof": { "type": "boolean", "description": "You can choose to hide the \"Mais de 5 milhões de usuários já conectaram com segurança suas contas.\" message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (Multi-Region) guide.", "example": true } } }, "theme": { "type": "array", "description": "You can optionally add your brand colors to the widget using the `theme` parameter. \n\nFor more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide.\n", "items": { "type": "object", "required": [ "css_key", "value" ], "properties": { "css_key": { "type": "string", "description": "CSS variable name. Possible values include:\n- `--color-primary-base`\n- `--nav-bar-title-color`\n- `--nav-bar-icon-color`\n", "example": "--color-primary-base" }, "value": { "type": "string", "description": "The HEX code for the `css_key`.", "example": "#907AD6" } } } } } } } }, "WidgetToken": { "type": "object", "properties": { "access": { "type": "string", "description": "The access token to be used to authenticate the widget.", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3MzYwMTk1LCJpYXQiOjE3MjczNTg5OTUsImp0aSI6ImRhN2Q3OTM1ZDZlZTQ0MTBhYTMwYTc3NWQ1OWMxZWIzIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJPV05FUlMiLCJFTVBMT1lNRU5UUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.DaQ8xVTEjA4BD-0SbBCQDylO3NrjhsHiWXTaoPdKWRucS2E0jxNUHC5lwrejrz73-GytgcXTeiI1fhZBYW719A" }, "refresh": { "type": "string", "description": "The refresh token to be used to authenticate the widget.", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0OTQzODk5NSwiaWF0IjoxNzI3MzU4OTk1LCJqdGkiOiI2YmUyMGFmNTcxZDU0NjQzYjA0Y2U3YTVhNjI5ZDRiMSIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiT1dORVJTIiwiRU1QTE9ZTUVOVFMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.T-tnX2BwAjQI0MaYCO686bZD6H7EMIgi_CbOWtHDexGIiTKLer0d7RJGisXJqM6oA_L4y_A_774LEj8NNb7YXQ" } } }, "link": { "type": "string", "nullable": true, "format": "uuid", "description": "The `link.id` the data belongs to.", "example": "30cb4806-6e00-48a4-91c9-ca55968576c8" }, "InstitutionAccount": { "type": "object", "description": "Details regarding the institution.", "properties": { "name": { "type": "string", "example": "erebor_mx_retail", "description": "The name of the institution, as designated by Belvo." }, "type": { "$ref": "#/components/schemas/EnumInstitutionType" } } }, "collected_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp when the data point was collected.\n", "example": "2022-02-09T08:45:50.406032Z" }, "EnumAccountCategoryOpenFinance": { "type": "string", "nullable": true, "enum": [ "ADVANCE_DEPOSIT_ACCOUNT", "CHECKING_ACCOUNT", "CREDIT_CARD", "FINANCING_ACCOUNT", "INVESTMENT_ACCOUNT", "INVOICE_FINANCING_ACCOUNT", "LOAN_ACCOUNT", "PENSION_FUND_ACCOUNT", "SAVINGS_ACCOUNT", "UNCATEGORIZED" ], "description": "The type of account.\nWe return one of the following enum values:\n - `ADVANCE_DEPOSIT_ACCOUNT`\n - `CHECKING_ACCOUNT`\n - `CREDIT_CARD`\n - `FINANCING_ACCOUNT`\n - `INVESTMENT_ACCOUNT`\n - `INVOICE_FINANCING_ACCOUNT`\n - `LOAN_ACCOUNT`\n - `PENSION_FUND_ACCOUNT`\n - `SAVINGS_ACCOUNT`\n - `UNCATEGORIZED`\n", "example": "CHECKING_ACCOUNT" }, "AccountOverdraftOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "arranged", "used", "unarranged" ], "properties": { "arranged": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The agreed upon overdraft limit between the account holder and the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `overdraft` field is available.\n", "example": 5000.5 }, "used": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The overdraft value used.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `overdraft` field is available.\n", "example": 1000.5 }, "unarranged": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The overdraft used that was not arranged between the account holder and the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `overdraft` field is available.\n", "example": 300.1 } } }, "AccountBalanceOpenFinanceBrazil": { "type": "object", "required": [ "current" ], "description": "Details regarding the current and available balances for the account.\n", "properties": { "current": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The current balance is calculated differently according to the type of account.\n\n\n- **💰 Checking and saving accounts**:\n\n\nThe user's account balance at the `collected_at` timestamp.\n\n- **💳 Credit cards**:\n\n\nThe amount the user has spent in the current card billing period (see `credit_data.cutting_date` for information on when the current billing period finishes).\n\n- **🏡 Loan accounts**:\n\n\nThe amount remaining to pay on the users's loan.\n", "example": 5874.13 }, "available": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The balance that the account owner can use.\n\n- **💰 Checking and saving accounts**:\n\n\nThe available balance may be different to the `current` balance due to pending transactions.\n\n- **💳 Credit cards**:\n\n\nThe credit amount the user still has available for the current period. The amount is calculated as `credit_data.credit_limit` minus `balance.current`.\n\n- **🏡 Loan accounts**:\n\n\nThe present value required to pay off the loan, as provided by the institution.\n\n\n**Note:** If the institution does not provide this value, we return `null`.\n", "example": 5621.12 }, "blocked": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount that is currently blocked due to pending transactions.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n", "example": 60.32 }, "automatically_invested": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount that is automatically invested (as agreed upon with the institution).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n", "example": 131.5 } } }, "EnumCreditCardLimitType": { "type": "string", "enum": [ "TOTAL_LIMIT", "MODAL_LIMIT" ], "description": "The type of limit. We return one of the following values:\n\n - `TOTAL_LIMIT`\n - `MODAL_LIMIT`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "TOTAL_LIMIT" }, "AccountCreditDataLimitsOpenFinanceBrazil": { "type": "object", "description": "Detailed information regarding the credit limits for the credit cards.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "required": [ "identification_number", "credit_limit", "used_amount", "available_amount", "is_limit_flexible", "type", "consolidation_type", "line_name", "line_name_additional_info" ], "properties": { "identification_number": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The credit card number.\n\n**Note:** Often, this is just the last four digit of the credit card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "4453" }, "credit_limit": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The limit of the credit card.\n", "example": 1000.04 }, "used_amount": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount used.\n", "example": 400.04 }, "available_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount still available.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": 600 }, "is_limit_flexible": { "type": "boolean", "description": "Boolean to indicate if the `credit_limit` is flexible.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": false }, "type": { "$ref": "#/components/schemas/EnumCreditCardLimitType" }, "consolidation_type": { "type": "string", "description": "Indicates whether or not the credit limit is consolidated or individual.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "INDIVIDUAL" }, "line_name": { "type": "string", "nullable": true, "description": "The credit limit line name.\n", "example": "CREDITO_A_VISTA" }, "line_name_additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "[\\w\\W\\s]*", "description": "Additional information about the line name.\n", "example": "Informações adicionais e complementares" } } }, "EnumAccountCreditCardNetwork": { "type": "string", "enum": [ "VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DINERS_CLUB", "HIPERCARD", "BANDEIRA_PROPRIA", "CHEQUE_ELETRONICO", "ELO", "OTHER" ], "description": "The credit network that the card is associated with. We return one of the following values:\n\n - `VISA`\n - `MASTERCARD`\n - `AMERICAN_EXPRESS`\n - `DINERS_CLUB`\n - `HIPERCARD`\n - `BANDEIRA_PROPRIA`\n - `CHEQUE_ELETRONICO`\n - `ELO`\n - `OTHER`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "MASTERCARD" }, "AccountCreditDataCardsOpenFinanceBrazil": { "type": "object", "required": [ "is_multiple", "identification_number" ], "description": "Details regarding all the cards associated with the account.", "properties": { "is_multiple": { "type": "boolean", "description": "Boolean to indicate if this account has multiple credit cards.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": false }, "identification_number": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The credit card number.\n\n**Note:** Often, this is just the last four digit of the credit card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "4453" } } }, "AccountCreditDataOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "collected_at", "credit_limit" ], "description": "Details regarding the credit cards associated with this account.", "properties": { "collected_at": { "$ref": "#/components/schemas/collected_at" }, "credit_limit": { "type": "number", "nullable": true, "format": "float", "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The upper credit limit of the card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": 192000.9 }, "limits": { "type": "array", "items": { "$ref": "#/components/schemas/AccountCreditDataLimitsOpenFinanceBrazil" } }, "cutting_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date when the credit card's bill is due.", "example": "2019-12-11" }, "minimum_payment": { "type": "number", "nullable": true, "format": "float", "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The minimum amount that the account owner needs to pay in the current credit period.\n", "example": 2400.3 }, "network": { "$ref": "#/components/schemas/EnumAccountCreditCardNetwork" }, "network_additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "[\\w\\W\\s]*", "description": "Additional information about the credit card network.\n", "example": "It's an orange card." }, "cards": { "type": "array", "minItems": 1, "description": "Details regarding the cards associated with the account.", "items": { "$ref": "#/components/schemas/AccountCreditDataCardsOpenFinanceBrazil" } }, "next_payment_date": { "type": "string", "nullable": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "no_interest_payment": { "type": "number", "nullable": true, "format": "float", "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "interest_rate": { "type": "number", "nullable": true, "format": "float", "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "monthly_payment": { "type": "number", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "last_payment_date": { "type": "string", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null } } }, "EnumAccountLoanDataInterestRateType": { "type": "string", "enum": [ "MONTHLY", "YEARLY" ], "description": "The period that the interest is applied to the loan.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "MONTHLY" }, "EnumAccountLoanDataInterestRateDataTaxType": { "type": "string", "enum": [ "NOMINAL", "EFFECTIVE" ], "description": "The type of interest rate tax. We return one of the following values:\n\n - `NOMINAL`\n - `EFFECTIVE`\n \n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "NOMINAL" }, "EnumAccountLoanDataInterestRateDataRateType": { "type": "string", "enum": [ "SIMPLE", "COMPOUND" ], "description": "The type of interest rate. We return one of the following values:\n\n - `SIMPLE`\n - `COMPOUND`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "SIMPLE" }, "EnumAccountLoanDataInterestRateDataReferenceIndexType": { "type": "string", "enum": [ "WITHOUT_INDEX_TYPE", "PRE_FIXED", "POST_FIXED", "FLOATING", "INDEXED_PRICE", "RURAL_CREDIT", "OTHER_INDEX" ], "description": "The reference index rate. We return one of the following values:\n\n - `WITHOUT_INDEX_TYPE`\n - `PRE_FIXED`\n - `POST_FIXED`\n - `FLOATING`\n - `INDEXED_PRICE`\n - `RURAL_CREDIT`\n - `OTHER_INDEX`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "FLOATING" }, "AccountLoanDataInterestRateDataOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "tax_type", "rate_type", "calculation_base", "reference_index_type", "reference_index_subtype", "reference_index_info", "pre_fixed_rate", "post_fixed_rate", "additional_info" ], "description": "Detailed information regarding the interest rate.", "properties": { "tax_type": { "$ref": "#/components/schemas/EnumAccountLoanDataInterestRateDataTaxType" }, "rate_type": { "$ref": "#/components/schemas/EnumAccountLoanDataInterestRateDataRateType" }, "type": { "$ref": "#/components/schemas/EnumAccountLoanDataInterestRateType" }, "calculation_base": { "type": "string", "pattern": "^[0-9]{2}\\/[0-9]{3}$", "description": "The base calculation for the interest rate.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "30/360" }, "reference_index_type": { "$ref": "#/components/schemas/EnumAccountLoanDataInterestRateDataReferenceIndexType" }, "reference_index_subtype": { "type": "string", "nullable": true, "description": "The subtype of the reference index rate.\n", "example": "TR_TBF" }, "reference_index_info": { "type": "string", "nullable": true, "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "Additional information regarding the reference index rate.\n", "example": "Additional information" }, "pre_fixed_rate": { "type": "number", "format": "float", "pattern": "^[01]\\.\\d{6}$", "description": "The pre-fixed percentage rate of the interest rate.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": 0.062 }, "post_fixed_rate": { "type": "number", "format": "float", "pattern": "^[01]\\.\\d{6}$", "description": "The post-fixed percentage rate of the interest rate.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": 0.062 }, "additional_info": { "type": "string", "nullable": true, "maxLength": 1200, "pattern": "[\\w\\W\\s]*", "description": "Additional information regarding the interest rate.\n", "example": "Additional information" } } }, "AccountLoanDataInterestRateOpenFinanceBrazil": { "type": "object", "required": [ "name", "type", "value", "interest_rate_data" ], "description": "Breakdown of the interest applied to the loan. With OF Brazil, we highly recommend using the `interest_rate_data` object for in-depth information.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "properties": { "name": { "type": "string", "nullable": true, "description": "The name of the type of interest rate applied to the loan.\n\n**Note:** For OFDA Brazil, we recommend you use the `interest_rate_data.tax_type` parameter.\n", "example": "NOMINAL" }, "type": { "$ref": "#/components/schemas/EnumAccountLoanDataInterestRateType" }, "value": { "type": "number", "nullable": true, "format": "float", "description": "The interest rate (in percent or currency value).\n\n**Note:** For OFDA Brazil, we recommend you use the `interest_rate_data.pre_fixed_rate` and `interest_rate_data.post_fixed_rate`parameter.\n", "example": 7.85 }, "interest_rate_data": { "$ref": "#/components/schemas/AccountLoanDataInterestRateDataOpenFinanceBrazil" } } }, "EnumAccountLoanDataFeeType": { "type": "string", "nullable": true, "enum": [ "OPERATION_FEE", "INSURANCE_FEE", "OTHERS", null ], "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "EnumAccountLoanDataFeeChargeType": { "type": "string", "enum": [ "SINGLE", "PER_INSTALLMENT" ], "description": "Indicates the type of charge. We return one of the following values:\n\n - `SINGLE`\n - `PER_INSTALLMENT`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n", "example": "SINGLE" }, "EnumAccountLoanDataFeeCharge": { "type": "string", "enum": [ "MINIMUM", "MAXIMUM", "FIXED", "PERCENTAGE" ], "description": "Billing method, as agreed upon with the institution. We return one of the following values:\n\n - `MINIMUM`\n - `MAXIMUM`\n - `FIXED`\n - `PERCENTAGE`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n", "example": "FIXED" }, "AccountLoanDataFeesOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "type", "value", "name", "code", "fee_charge_type", "fee_charge", "rate" ], "description": "Breakdown of the fees applied to the loan.", "properties": { "type": { "$ref": "#/components/schemas/EnumAccountLoanDataFeeType" }, "value": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total value of the fee. Same currency as the loan.\n", "example": 5.6 }, "name": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "The fee name.\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n", "example": "Renovação de cadastro" }, "code": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "The fee code.\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `fees` field is available.\n", "example": "CADASTRO" }, "fee_charge_type": { "$ref": "#/components/schemas/EnumAccountLoanDataFeeChargeType" }, "fee_charge": { "$ref": "#/components/schemas/EnumAccountLoanDataFeeCharge" }, "rate": { "type": "number", "nullable": true, "format": "float", "pattern": "^[01]\\.\\d{6}$", "description": "The percentage rate of the fee. Required when `fee_charge` is set to `PERCENTAGE`.\n", "example": 0.062 } } }, "EnumAccountLoanDataContractedChargeType": { "type": "string", "enum": [ "LATE_PAYMENT_INTEREST_FEE", "LATE_PAYMENT_PENALTY_FEE", "DEFAULT_INTEREST_FEE", "LOAN_CONTRACT_TAX", "LATE_PAYMENT_TAX", "NO_CHARGE", "OTHER" ], "description": "The type of contracted charge. We return one of the following values:\n\n - `LATE_PAYMENT_INTEREST_FEE`\n - `LATE_PAYMENT_PENALTY_FEE`\n - `DEFAULT_INTEREST_FEE`\n - `LOAN_CONTRACT_TAX`\n - `LATE_PAYMENT_TAX`\n - `NO_CHARGE`\n - `OTHER`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network if the `contracted_charges` field is available.\n", "example": "LATE_PAYMENT_INTEREST_FEE" }, "AccountLoanDataContractedChargesOpenFinanceBrazil": { "type": "object", "nullable": true, "description": "Details regarding any contracted charges.\n", "properties": { "type": { "$ref": "#/components/schemas/EnumAccountLoanDataContractedChargeType" }, "info": { "type": "string", "nullable": true, "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "Additional information regarding the contracted charge.\n", "example": "Late fee" }, "rate": { "type": "number", "nullable": true, "format": "float", "pattern": "^[01]\\.\\d{6}$", "description": "The percentage rate of the charge, calculated based on the amount of the loan.\n", "example": 0.062 } } }, "AccountLoanDataCollateralsOpenFinanceBrazil": { "type": "object", "nullable": true, "description": "Details regarding any loan collaterals that the individual or business supplied.", "required": [ "type", "subtype", "currency", "amount" ], "properties": { "type": { "type": "string", "description": "The type of collateral, as defined by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n", "example": "OPERACOES_GARANTIDAS_PELO_GOVERNO" }, "subtype": { "type": "string", "description": "The subtype of the collateral, as defined by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n", "example": "CCR_CONVENIO_CREDITOS_RECIPROCOS" }, "currency": { "type": "string", "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n", "example": "BRL" }, "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total amount of the bill.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `collaterals` field is available.\n", "example": 45391.89 } } }, "AccountLoanDataBalloonPaymentsOpenFinanceBrazil": { "type": "object", "nullable": true, "description": "Detailed information regarding any balloon payments for the loan, if applicable.", "required": [ "due_date", "currency", "amount" ], "properties": { "due_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the balloon payment is to be paid, in `YYYY-MM-DD` format.\n", "example": "2021-09-06" }, "currency": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n", "example": "BRL" }, "amount": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total amount of the balloon payment.\n", "example": 45391.89 } } }, "EnumAccountsLoanDataContractInstallmentFrequency": { "type": "string", "nullable": true, "enum": [ "DAY", "WEEK", "MONTH", "YEAR", "NO_DEADLINE_REMAINING", null ], "description": "The frequency of contracted installment payments, as defined when the contract was first signed. We return one of the following:\n\n - `DAY`\n - `WEEK`\n - `MONTH`\n - `YEAR`\n - `NO_DEADLINE_REMAINING`\n - `null`\n", "example": "MONTH" }, "EnumAccountLoanDataInstallmentFrequency": { "type": "string", "enum": [ "IRREGULAR", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "BIMONTHLY", "QUARTERLY", "BIANNUALLY", "ANNUALLY", "OTHER" ], "description": "The frequency that the installments are paid. We return one of the following values:\n\n - `IRREGULAR`\n - `WEEKLY`\n - `FORTNIGHTLY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `QUARTERLY`\n - `BIANNUALLY`\n - `ANNUALLY`\n - `OTHER`\n\n > **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "MONTHLY" }, "EnumAccountLoanDataContractRemainingFrequency": { "type": "string", "nullable": true, "enum": [ "DAY", "WEEK", "MONTH", "YEAR", "NO_DEADLINE_REMAINING", null ], "description": "The frequency of the remaining contracted installment payments, as defined when the contract was first signed. We return one of the following:\n- `DAY`\n- `WEEK`\n- `MONTH`\n- `YEAR`\n- `NO_DEADLINE_REMAINING`\n- `null`\n", "example": "MONTH" }, "AccountLoanDataOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "collected_at", "loan_code", "contract_amount", "total_effectove_cost", "loan_type", "outstanding_balance", "interest_rates", "fees", "collaterals", "balloon_payments", "installments_contract_term_frequency", "installment_frequency", "installment_frequency_info", "first_installment_due_date", "number_of_installments_total", "number_of_installments_outstanding", "number_of_installments_paid", "number_of_installments_past_due", "disbursement_dates", "settlement_date", "contract_start_date", "contract_end_date", "contract_remaining_frequency", "contract_remaining_total", "amortization_schedule", "amortization_schedule_info", "consignee_id", "contract_number", "monthly_payment", "principal", "payment_day", "outstanding_principal", "credit_limit", "last_period_balance", "interest_rate", "limit_day", "cutting_day", "cutting_date", "last_payment_date", "no_interest_payment" ], "description": "The loan options associated with this account.", "properties": { "collected_at": { "$ref": "#/components/schemas/collected_at" }, "loan_code": { "type": "string", "minLength": 22, "maxLength": 67, "pattern": "^\\d{22,67}$", "description": "The country-specific standardized contract number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "92792126019929279212650822221989319252576" }, "contract_amount": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The initial total loan amount when the contract was signed, calculated by the institution. This amount includes the principal + interest + taxes + fees.\n", "example": 202000 }, "total_effective_cost": { "type": "number", "nullable": true, "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The initial total effective cost of the loan.\n", "example": 209000 }, "loan_type": { "type": "string", "description": "The type of the loan, according to the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "HOME_EQUITY" }, "outstanding_balance": { "type": "number", "nullable": true, "format": "float", "minLength": 4, "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount remaining to pay in total, including interest.\n", "example": 182000 }, "interest_rates": { "type": "array", "description": "Breakdown of the interest applied to the loan. With OF Brazil, we highly recommend using the information in `interest_rate_data` for in-depth information.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/AccountLoanDataInterestRateOpenFinanceBrazil" } }, "fees": { "type": "array", "nullable": true, "description": "Breakdown of the fees applied to the loan.\n", "items": { "$ref": "#/components/schemas/AccountLoanDataFeesOpenFinanceBrazil" } }, "contracted_charges": { "type": "array", "nullable": true, "description": "", "items": { "$ref": "#/components/schemas/AccountLoanDataContractedChargesOpenFinanceBrazil" } }, "collaterals": { "type": "array", "nullable": true, "description": "Details regarding any loan collaterals that the individual or business supplied.\n", "items": { "$ref": "#/components/schemas/AccountLoanDataCollateralsOpenFinanceBrazil" } }, "balloon_payments": { "type": "array", "nullable": true, "description": "Detailed information regarding any balloon payments for the loan, if applicable.\n", "items": { "$ref": "#/components/schemas/AccountLoanDataBalloonPaymentsOpenFinanceBrazil" } }, "installments_contract_term_frequency": { "$ref": "#/components/schemas/EnumAccountsLoanDataContractInstallmentFrequency" }, "installment_frequency": { "$ref": "#/components/schemas/EnumAccountLoanDataInstallmentFrequency" }, "installment_frequency_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W\\s]{0,99}$$", "description": "Additional information regarding the `installment_frequency`.\n", "example": "Both the term and requency are the same." }, "first_installment_due_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date when the first installment of the loan is to be paid, in `YYYY-MM-DD` format.\n", "example": "2020-03-01" }, "number_of_installments_total": { "type": "integer", "nullable": true, "format": "int32", "maximum": 999999999, "description": "The total number of installments required to pay the loan.\n", "example": 60 }, "number_of_installments_outstanding": { "type": "integer", "nullable": true, "format": "int32", "maximum": 999999999, "description": "The number of installments left to pay.\n", "example": 48 }, "number_of_installments_paid": { "type": "integer", "nullable": true, "format": "int32", "maximum": 999999999, "description": "The number of installments already paid.\n", "example": 32 }, "number_of_installments_past_due": { "type": "integer", "nullable": true, "format": "int32", "maximum": 999, "description": "The number of installments that are overdue.\n", "example": 2 }, "disbursement_dates": { "type": "array", "nullable": true, "minItems": 1, "description": "An array of dates when the loan was disbursed.\n", "items": { "type": "string", "nullable": true, "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the loan was disbursed, in `YYYY-MM-DD` format.\n", "example": "2021-09-23" } }, "settlement_date": { "type": "string", "nullable": true, "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the loan was settled, in `YYYY-MM-DD` format.\n", "example": "2021-09-23" }, "contract_start_date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date when the loan contract was signed, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "2020-03-01" }, "contract_end_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date when the loan is expected to be completed, in `YYYY-MM-DD` format.\n", "example": "2027-10-01" }, "contract_remaining_frequency": { "$ref": "#/components/schemas/EnumAccountLoanDataContractRemainingFrequency" }, "contract_remaining_total": { "type": "integer", "nullable": true, "format": "int32", "maximum": 999999999, "description": "The total number of installments remaining on the loan.\n", "example": 20 }, "amortization_schedule": { "type": "string", "description": "The loan amortization schedule.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "SEM_SISTEMA_AMORTIZACAO" }, "amortization_schedule_info": { "type": "string", "nullable": true, "maxLength": 200, "pattern": "[\\w\\W\\s]*", "description": "Additional information regarding the `amortization_schedule`.\n", "example": "No need for a schedule." }, "consignee_id": { "type": "string", "nullable": true, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The ID of the consignee of the loan.\n", "example": "60500998000135" }, "contract_number": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "pattern": "^\\d{1,100}$", "description": "The contract number of the loan, as given by the institution.\n", "example": "1324926521496" }, "monthly_payment": { "type": "number", "nullable": true, "format": "float", "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "principal": { "type": "number", "nullable": true, "format": "float", "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "payment_day": { "type": "string", "nullable": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "outstanding_principal": { "type": "number", "nullable": true, "format": "float", "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "credit_limit": { "type": "number", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "last_period_balance": { "type": "number", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "interest_rate": { "type": "number", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "limit_day": { "type": "string", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "cutting_day": { "type": "string", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "cutting_date": { "type": "string", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "last_payment_date": { "type": "string", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "no_interest_payment": { "type": "number", "nullable": true, "deprecated": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null } } }, "AccountOpenFinanceBrazil": { "type": "object", "nullable": true, "title": "Account Object (OFDA Brazil)", "x-tags": [ "Accounts" ], "description": "Details regarding the account.\n", "required": [ "id", "link", "institution", "collected_at", "created_at", "last_accessed_at", "category", "balance_type", "type", "subtype", "name", "number", "agency", "check_digit", "balance", "currency", "public_identification_name", "public_identification_value", "internal_identification", "credit_data", "loan_data", "funds_data" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "institution": { "$ref": "#/components/schemas/InstitutionAccount" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "last_accessed_at": { "$ref": "#/components/schemas/last_accessed_at" }, "category": { "$ref": "#/components/schemas/EnumAccountCategoryOpenFinance" }, "balance_type": { "type": "string", "nullable": true, "description": "Indicates whether this account is either an `ASSET` or a `LIABILITY`. You can consider the balance of an `ASSET` as being positive, while the balance of a `LIABILITY` as negative.\n", "example": "ASSET" }, "overdraft": { "$ref": "#/components/schemas/AccountOverdraftOpenFinanceBrazil" }, "type": { "type": "string", "description": "The account type, as designated by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "STANDARD_NACIONAL" }, "subtype": { "type": "string", "description": "The account subtype, as designated by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "FINANCIAMENTO_HABITACIONAL_SFH" }, "name": { "type": "string", "nullable": true, "description": "The account name, as given by the institution.", "example": "Cuenta Perfiles- M.N. - MXN-666" }, "number": { "type": "string", "nullable": true, "description": "The account number, as designated by the institution.\n", "example": "4057068115181" }, "agency": { "type": "string", "nullable": true, "maxLength": 4, "pattern": "^\\d{1,4}$", "description": "The branch code where the product was opened.\n", "example": "6272" }, "check_digit": { "type": "string", "nullable": true, "maxLength": 2, "pattern": "[\\w\\W\\s]*", "description": "The check digit of the product's number, if applicable.\n", "example": "7" }, "balance": { "$ref": "#/components/schemas/AccountBalanceOpenFinanceBrazil" }, "currency": { "type": "string", "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n", "example": "BRL" }, "public_identification_name": { "type": "string", "nullable": true, "description": "The public name for the type of identification. For 🇧🇷 Brazilian savings and checking accounts, this field will be `AGENCY/ACCOUNT`.\n", "example": "AGENCY/ACCOUNT" }, "public_identification_value": { "type": "string", "nullable": true, "description": "The value for the `public_identification_name`.\n\nFor 🇧🇷 OFDA Brazilian savings and checking accounts, this field will be the agency and bank account number, separated by a slash. For example: `0444/45722-0`.\n\nFor 🇧🇷 OFDA Brazilian credit card accounts, we will return a string of concatenated credit card numbers associated with the account. For example: \"8763,9076,5522\"\n", "example": "0444/45722-0" }, "internal_identification": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The institution's internal identification for the account.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `balances` field is available.\n", "example": "92792126019929279212650822221989319252576" }, "credit_data": { "$ref": "#/components/schemas/AccountCreditDataOpenFinanceBrazil" }, "loan_data": { "$ref": "#/components/schemas/AccountLoanDataOpenFinanceBrazil" }, "funds_data": { "type": "string", "nullable": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null } } }, "link_request": { "type": "string", "format": "uuid", "description": "The `link.id` you want to retrieve information for.", "example": "c81a1dea-6dd6-4999-8b9f-541ee8197058" }, "BalanceOFDA": { "type": "object", "title": "Balance Object (Brazil OFDA)", "x-tags": [ "Balances" ], "required": [ "id", "link", "account_id", "account_internal_identification", "collected_at", "created_at", "last_updated_at", "currency", "available", "blocked", "automatically_invested" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier created by Belvo used to reference the current balance.", "example": "0b94bdf9-3719-43a9-81e7-be95d2318595" }, "link": { "type": "string", "format": "uuid", "description": "The unique identifier of the link that this balance belongs to.", "example": "0b94bdf9-3719-43a9-81e7-be95d2318595" }, "account_id": { "type": "string", "format": "uuid", "description": "The Belvo `account.id` that this balance belongs to.", "example": "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321" }, "account_internal_identification": { "type": "string", "maxLength": 50, "description": "The institution's internal identification for the account.", "example": "92792126019929279212650822221989319252576" }, "collected_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp when the data point was collected.", "example": "2024-05-21T08:32:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the data point was created in Belvo's database.", "example": "2024-05-21T08:32:00Z" }, "last_updated_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when this balance was last updated by the institution.\n\n> 🚧 Warning\n>\n> The `last_updated_at` parameter depends on how the institution processes (or stores) data. In the case that the institution stores data synchronously (that is, as soon as a transaction occurs, the balance us updated), then the `last_updated_at` will reflect the balance in near real time. In the case that the institution stores data asynchronously (that is, it retrieves data in bulk and then updates the balance), the balance information can refer to hours or days ago. Additionally, in the case that the institution cannot provide the specific time (due to an internal error), the institution may provide an overall time where they last refreshed the account and balance information.\n", "example": "2021-05-21T08:30:00Z" }, "currency": { "type": "string", "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).", "example": "USD" }, "available": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "minimum": 0, "description": "The available account balance.", "example": 1000.02 }, "blocked": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "minimum": 0, "description": "The amount that is currently blocked due to, for example, pending transactions.", "example": 1000.02 }, "automatically_invested": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "minimum": 0, "description": "The amount that is automatically invested (as agreed upon with the institution).", "example": 1000.02 } } }, "account_id": { "type": "string", "format": "uuid", "description": "The Belvo `account.id` you want to retrieve information for.", "example": "e2cdb621-f44a-4558-89f6-8ab2a57add7a" }, "EnumExchangeOperationType": { "type": "string", "enum": [ "COMPRA", "VENDA" ], "description": "The type of exchange operation.\n\nWe return one of the following enum values:\n - `COMPRA` - Buy (client is buying foreign currency)\n - `VENDA` - Sell (client is selling foreign currency)\n", "example": "COMPRA" }, "EnumExchangeSettlementMethod": { "type": "string", "nullable": true, "enum": [ "CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS", "CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR", "ESPECIE_CHEQUES_VIAGEM", "CARTAO_PREPAGO", "TELETRANSMISSAO", "SEM_MOVIMENTACAO_VALORES", "DEMAIS", "CARTA_CREDITO_A_VISTA", "CARTA_CREDITO_A_PRAZO", "CONTA_DEPOSITO", "CHEQUE", "TITULOS_VALORES", "SIMBOLICA", "CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR", "CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS", "OUTRO_NAO_MAPEADO_OFB", null ], "description": "The method of delivery for the foreign currency.\n\nWe return one of the following enum values:\n - `CARTA_CREDITO_A_VISTA` (Code 10) - Sight letter of credit\n - `CARTA_CREDITO_A_PRAZO` (Code 15) - Term letter of credit\n - `CONTA_DEPOSITO` (Code 20) - Deposit account\n - `CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS` (Code 21) - Foreign currency deposit account in country\n - `CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR` (Code 22) - Exporter's deposit account maintained abroad\n - `CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR` (Code 23) - Deposit account or payment to exporter at foreign institution\n - `CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS` (Code 25) - Reciprocal payments and credits agreement\n - `CHEQUE` (Code 30) - Check\n - `ESPECIE_CHEQUES_VIAGEM` (Code 50) - Cash or traveler's checks\n - `CARTAO_PREPAGO` (Code 55) - Prepaid card\n - `TELETRANSMISSAO` (Code 65) - Wire transfer\n - `TITULOS_VALORES` (Code 75) - Securities/bonds\n - `SIMBOLICA` (Code 90) - Symbolic\n - `SEM_MOVIMENTACAO_VALORES` (Code 91) - No movement of funds\n - `DEMAIS` (Code 99) - Others\n - `OUTRO_NAO_MAPEADO_OFB` - Other not mapped by Open Finance Brazil\n - `null`\n", "example": "CARTA_CREDITO_A_PRAZO" }, "Exchange": { "type": "object", "title": "Exchange Object (Brazil)", "x-tags": [ "Exchanges" ], "additionalProperties": false, "required": [ "id", "link", "created_at", "collected_at", "operation_identifier", "operation_type", "operation_requested_at", "authorized_institution_identifier", "authorized_institution_name", "operation_due_date", "local_operation_tax_amount", "local_operation_tax_currency", "local_operation_value_amount", "local_operation_value_currency", "foreign_operation_value_amount", "foreign_operation_value_currency", "settlement_method", "operation_category_code" ], "description": "Details regarding an exchange operation in the Brazilian Open Finance Network.\n\nAn Exchange represents a currency exchange operation contracted by the customer, including the main contract details,\nexchange rates, amounts in local and foreign currencies, and settlement information.\n", "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "operation_identifier": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\-]{0,99}$", "description": "The network's unique identifier for the exchange operation.", "example": "92792126019929240" }, "operation_number": { "type": "string", "nullable": true, "maxLength": 12, "pattern": "^\\d{12}$", "description": "The 12-digit operation registration number from the Brazil Central Bank (Bacen). This can be `null` if the operation has not yet been registered.\n", "example": "393874649456" }, "operation_type": { "$ref": "#/components/schemas/EnumExchangeOperationType" }, "operation_requested_at": { "type": "string", "format": "date-time", "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)Z$", "description": "The ISO-8601 timestamp when the exchange operation was contracted.", "example": "2023-03-07T08:30:00Z" }, "authorized_institution_identifier": { "type": "integer", "format": "int64", "description": "The CNPJ of the institution authorized to conduct the operation.", "example": 11225860000140 }, "authorized_institution_name": { "type": "string", "maxLength": 80, "description": "The name of the authorized institution.", "example": "AGENCIA CORRETORA" }, "intermediary_institution_identifier": { "type": "integer", "format": "int64", "nullable": true, "description": "The CNPJ of the intermediary institution, if one was used.", "example": 11225860000140 }, "intermediary_institution_name": { "type": "string", "nullable": true, "maxLength": 80, "description": "The name of the intermediary institution. Must be present if `intermediary_institution_identifier` is available.", "example": "AGENCIA CORRETORA" }, "operation_due_date": { "type": "string", "format": "date", "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "minLength": 10, "maxLength": 10, "description": "The currently scheduled settlement date for the operation, in `YYYY-MM-DD` format. \n\n> **Note**: This field is updated if any changes are made to the exchange operation.\n", "example": "2018-02-15" }, "local_operation_tax_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{1,15}$", "description": "The exchange rate applied to the operation.", "example": 1.3 }, "local_operation_tax_currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) for the exchange rate.", "example": "BRL" }, "local_operation_value_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,17}\\.\\d{2}$", "description": "The total value of the operation in local currency.", "example": 1000.04 }, "local_operation_value_currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) for the local currency.", "example": "BRL" }, "foreign_operation_value_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,17}\\.\\d{2}$", "description": "The total value of the operation in the foreign currency.", "example": 1000.04 }, "foreign_operation_value_currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) for the foreign currency.", "example": "USD" }, "operation_outstanding_balance_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,17}\\.\\d{2}$", "description": "The outstanding balance to be settled, in the foreign currency. In the case that the exchange operation is scheduled to be settled within two days of the `operation_requested_at`, this value can be `null`.\n", "example": 1000.04 }, "operation_outstanding_balance_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The currency of the outstanding balance. Required if `operation_outstanding_balance_amount` is not `null`.", "example": "USD" }, "tev_amount_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,15}\\.\\d{1,15}$", "description": "The \"All-in Rate\" (Valor Efetivo Total/Total Effective Cost), representing the total cost of the operation. Required when the operation is scheduled to be settled within two days of the `operation_requested_at` and does not exceed $100,000 USD.\n", "example": 1000.000004 }, "tev_amount_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The currency of the VET (always BRL). Required if `tev_amount_amount` is not `null`.", "example": "BRL" }, "local_currency_advance_percentage": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1}\\.\\d{1,6}$", "description": "The percentage of the foreign currency value that was granted to the client in advance. In the case that the exchange operation is scheduled to be settled within two days of the `operation_requested_at`, this value can be `null`.\n", "example": 0.12 }, "settlement_method": { "$ref": "#/components/schemas/EnumExchangeSettlementMethod" }, "operation_category_code": { "type": "string", "maxLength": 5, "pattern": "^\\d{5}$", "description": "The 5-digit Central Bank code that classifies the \"nature\" of the operation.\n\nThis code must comply with the nature codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.\n", "example": "90302" } } }, "EnumExchangeEventType": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 9 ], "description": "The type of event that occurred for the exchange operation.\n\nWe return one of the following enum values:\n - `1` - Contract in the primary market\n - `2` - Modification of exchange operation in the primary market\n - `3` - Cancellation of exchange operation in the primary market\n - `4` - Settlement of exchange operation in the primary market\n - `5` - Write-off of outstanding amount to be settled in the primary market\n - `6` - Reinstatement of written-off outstanding amount in the primary market\n - `9` - Nullification of exchange operation in the primary market (used, for example, in the nullification of a settlement/cancellation event)\n\n> **Note**: Codes follow the messaging layout sent by institutions to the Central Bank of Brazil.\n", "example": 2 }, "ExchangeHistory": { "type": "object", "title": "Exchange History Object (Brazil)", "x-tags": [ "Exchanges" ], "additionalProperties": false, "required": [ "id", "link", "exchange_id", "created_at", "collected_at", "operation_identifier", "event_sequence_number", "event_type", "event_created_at" ], "description": "Details regarding modification events for an exchange operation in the Brazilian Open Finance Network.\n\nEach history entry represents a modification event (an audit trail) for an exchange operation. The Exchange object holds \nthe original contract data, while any changes to the contract (alterations, changes to settlements, etc.) are recorded \nas history events.\n", "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "exchange_id": { "type": "string", "format": "uuid", "description": "The Belvo-generated unique identifier for the original exchange operation.", "example": "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "operation_identifier": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\-]{0,99}$", "description": "The network's unique identifier for the exchange operation.", "example": "92792126019929240" }, "event_sequence_number": { "type": "string", "maxLength": 12, "pattern": "^\\d{12}$", "description": "The sequence number of the event record at the Central Bank (Bacen).", "example": "493874649457" }, "event_type": { "$ref": "#/components/schemas/EnumExchangeEventType" }, "event_created_at": { "type": "string", "format": "date-time", "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)Z$", "description": "The ISO-8601 timestamp when the event occurred.", "example": "2023-03-10T14:00:00Z" }, "operation_due_date": { "type": "string", "format": "date", "nullable": true, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "minLength": 10, "maxLength": 10, "description": "The date when the operation (buy or sell), after the event, is scheduled to be settled, in `YYYY-MM-DD` format.\n", "example": "2023-03-20" }, "local_operation_tax_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,15}\\.\\d{1,15}$", "description": "The exchange rate applied to the operation after the event.", "example": 1.4 }, "local_operation_tax_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) for the exchange rate.", "example": "BRL" }, "local_operation_value_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,17}\\.\\d{2}$", "description": "The total value of the operation in local currency after the event.", "example": 950 }, "local_operation_value_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) for the local currency.", "example": "BRL" }, "foreign_operation_value_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,17}\\.\\d{2}$", "description": "The total value of the operation in foreign currency after the event.", "example": 678.57 }, "foreign_operation_value_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) for the foreign currency.", "example": "USD" }, "operation_outstanding_balance_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,17}\\.\\d{2}$", "description": "The outstanding balance to be settled in foreign currency after the event.\n\nThis field is mandatory for events created (`event_created_at`) from April 15, 2024 onwards, in cases of exchange operations with future settlement.\n", "example": 678.57 }, "operation_outstanding_balance_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The currency of the outstanding balance. Required if `operation_outstanding_balance_amount` is not `null`.", "example": "USD" }, "tev_amount_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1,15}\\.\\d{1,15}$", "description": "The \"All-in Rate\" (Valor Efetivo Total/Total Effective Cost), representing the total cost of the operation after the event. \n\nThis field is required for spot exchange operations that reach up to the limit of $100,000 USD or equivalent in other currencies.\n", "example": 1002 }, "tev_amount_currency": { "type": "string", "nullable": true, "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The currency of the VET (always BRL). Required if `tev_amount_amount` is not `null`.", "example": "BRL" }, "local_currency_advance_percentage": { "type": "number", "format": "float", "nullable": true, "pattern": "^\\d{1}\\.\\d{1,6}$", "description": "The percentage of the foreign currency value that was granted to the client in advance after the event.\n\nThis field is mandatory in cases of exchange operations with future settlement.\n", "example": 0.12 }, "settlement_method": { "$ref": "#/components/schemas/EnumExchangeSettlementMethod" }, "operation_category_code": { "type": "string", "nullable": true, "maxLength": 5, "pattern": "^\\d{5}$", "description": "The 5-digit Central Bank code that classifies the \"nature\" of the operation.\n\nThis code must comply with the nature codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.\n", "example": "90302" }, "foreign_partie_relationship_code": { "type": "string", "nullable": true, "maxLength": 2, "pattern": "^\\d{2}$", "description": "The code indicating the relationship between the customer and the foreign payer/receiver.\n\nThis code must comply with the relationship codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.\n\n> **Note**: This field is optional when:\n> - The `settlement_method` field is `ESPECIE_CHEQUES_VIAGEM` or `CARTAO_PREPAGO`.\n> - The `event_type` field is different from `4` (Settlement of exchange operation in the primary market).\n>\n> If the institution has this information, it is mandatory to send it. If the information is updated after contracting, it must be sent through events.\n", "example": "50" }, "foreign_partie_name": { "type": "string", "nullable": true, "maxLength": 80, "pattern": "[\\w\\W\\s]*", "description": "The name of the foreign payer or receiver.\n\n> **Note**: This field is optional when:\n> - The `settlement_method` field is `ESPECIE_CHEQUES_VIAGEM` or `CARTAO_PREPAGO`.\n> - The `event_type` field is different from `4` (Settlement of exchange operation in the primary market).\n>\n> If the institution has this information, it is mandatory to send it. If the information is updated after contracting, it must be sent through events.\n", "example": "Global Tech Imports LLC" }, "foreign_partie_country_code": { "type": "string", "nullable": true, "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "The country code of the foreign payer or receiver, following the ISO 3166-1 standard.\n\n> **Note**: This field is optional when:\n> - The `settlement_method` field is `ESPECIE_CHEQUES_VIAGEM` or `CARTAO_PREPAGO`.\n> - The `event_type` field is different from `4` (Settlement of exchange operation in the primary market).\n>\n> If the institution has this information, it is mandatory to send it. If the information is updated after contracting, it must be sent through events.\n", "example": "US" } } }, "TransactionMerchantData": { "type": "object", "nullable": true, "description": "Additional data regarding the merchant involved in the transaction.\nWe only return merchant information for new transactions made from *checking* or *credit card* accounts.\n> **Get merchant information**\n We retrieve the merchant information for a transaction as part of our Transaction categorization product, turning raw data into actionable insights. To enable this product, just reach out to us, and we'll get right to it.\n", "properties": { "logo": { "type": "string", "nullable": true, "description": "The URL to the merchant's logo.", "example": "https://logo.clearbit.com/asesor-contable.es" }, "website": { "type": "string", "nullable": true, "description": "The URL to the merchant's website.", "example": "https://merchants-r-us.com" }, "merchant_name": { "type": "string", "description": "The name of the merchant.", "example": "Merchants R Us Global" } } }, "EnumTransactionCategory": { "type": "string", "nullable": true, "enum": [ "Bills & Utilities", "Credits & Loans", "Deposits", "Fees & Charges", "Food & Groceries", "Home & Life", "Income & Payments", "Insurance", "Investments & Savings", "Online Platforms & Leisure", "Personal Shopping", "Taxes", "Transfers", "Transport & Travel", "Unknown", "Withdrawal & ATM", null ], "description": "The name of the transaction category.\n\n> **Get transaction categorization**\nWith Transaction categorization, we clean and categorize transactions for you, turning raw data into actionable insights. To enable this feature, just reach out to us, and we'll get right to it.\n\nWe return one of the following enum values:\n\n - `Bills & Utilities`\n - `Credits & Loans`\n - `Deposits`\n - `Fees & Charges`\n - `Food & Groceries`\n - `Home & Life`\n - `Income & Payments`\n - `Insurance`\n - `Investments & Savings`\n - `Online Platforms & Leisure`\n - `Personal Shopping`\n - `Taxes`\n - `Transfers`\n - `Transport & Travel`\n - `Unknown`*\n - `Withdrawal & ATM`\n - `null`\n\n\n \\* For clients not using our Transaction Categorization product, we return `null` instead.\n", "example": "Income & Payments" }, "EnumTransactionSubcategory": { "type": "string", "nullable": true, "enum": [ "Electricity & Energy", "Rent", "Telecommunications", "Water", "Auto", "Credit Card", "Instalment", "Interest & Charges", "Mortgage", "Pay Advance", "Personal", "Adjustments", "Bank Fees", "Chargeback", "Refund", "Blocked Balances", "Alimony", "Alcohol & Tobacco", "Bakery & Coffee", "Bars & Nightclubs", "Convenience Store", "Delivery", "Groceries", "Restaurants", "Education", "Gyms & Fitness", "Hair & Beauty", "Health", "Home Decor & Appliances", "Laundry & Dry Cleaning", "Pharmacies", "Professional Services", "Veterinary Services", "Freelance", "Interest", "Retirement", "Salary", "Government", "Home Insurance", "Auto Insurance", "Health & Life Insurance", "Savings", "Fixed income", "Equity", "Investment Funds", "Derivatives", "Cryptocurrencies", "Apps, Software and Cloud Services", "Events, Parks and Museums", "Gambling", "Gaming", "Lottery", "Movie & Audio", "Books & News", "Clothing & Accessories", "Department Store", "Electronics", "E-commerce", "Gifts", "Office Supplies", "Pet Supplies", "Auto Tax & Fees", "Donation", "Government Fees", "Income Tax", "Real Estate Tax & Fees", "Tax Return", "Accommodation", "Auto Expenses", "Auto Rental", "Flights", "Gas", "Mileage Programs", "Parking & Tolls", "Public Transit", "Taxis & Rideshares", "Other", null ], "description": "The transaction subcategory.\n\n > **Get transaction categorization**\n For clients not using our Transaction categorization, we return `null` instead. To enable this feature, just reach out to us, and we'll get right to it.\n\n\nWe return one of the following enum values:\n\n - `Electricity & Energy`\n - `Rent`\n - `Telecommunications`\n - `Water`\n - `Auto`\n - `Credit Card`\n - `Instalment`\n - `Interest & Charges`\n - `Mortgage`\n - `Pay Advance`\n - `Personal`\n - `Adjustments`\n - `Bank Fees`\n - `Chargeback`\n - `Refund`\n - `Blocked Balances`\n - `Alimony`\n - `Alcohol & Tobacco`\n - `Bakery & Coffee`\n - `Bars & Nightclubs`\n - `Convenience Store`\n - `Delivery`\n - `Groceries`\n - `Restaurants`\n - `Education`\n - `Gyms & Fitness`\n - `Hair & Beauty`\n - `Health`\n - `Home Decor & Appliances`\n - `Laundry & Dry Cleaning`\n - `Pharmacies`\n - `Professional Services`\n - `Veterinary Services`\n - `Freelance`\n - `Interest`\n - `Retirement`\n - `Salary`\n - `Government`\n - `Home Insurance`\n - `Auto Insurance`\n - `Health & Life Insurance`\n - `Savings`\n - `Fixed income`\n - `Equity`\n - `Investment Funds`\n - `Derivatives`\n - `Cryptocurrencies`\n - `Apps, Software and Cloud Services`\n - `Events, Parks and Museums`\n - `Gambling`\n - `Gaming`\n - `Lottery`\n - `Movie & Audio`\n - `Books & News`\n - `Clothing & Accessories`\n - `Department Store`\n - `Electronics`\n - `E-commerce`\n - `Gifts`\n - `Office Supplies`\n - `Pet Supplies`\n - `Auto Tax & Fees`\n - `Donation`\n - `Government Fees`\n - `Income Tax`\n - `Real Estate Tax & Fees`\n - `Tax Return`\n - `Accommodation`\n - `Auto Expenses`\n - `Auto Rental`\n - `Flights`\n - `Gas`\n - `Mileage Programs`\n - `Parking & Tolls`\n - `Public Transit`\n - `Taxis & Rideshares`\n - `Other`\n - `null`\n", "example": "Freelance" }, "EnumTransactionType": { "type": "string", "nullable": true, "enum": [ "OUTFLOW", "INFLOW", null ], "description": "The direction of the transaction:\n- `INFLOW` indicates money coming into the account.\n- `OUTFLOW` indicates money going out of the account.\n- `null` when no information was present regarding the direction of the transaction.\n", "example": "INFLOW" }, "EnumTransactionStatus": { "type": "string", "nullable": true, "enum": [ "PENDING", "PROCESSED", "UNCATEGORIZED", null ], "description": "The status of the transaction. We return one of the following values:\n\n - `PROCESSED` (The transaction has been processed by the institution.)\n - `PENDING` (The institution clearly states that the transaction has not yet been processed.)\n - `UNCATEGORIZED` (deprecated)\n - `null` (deprecated)\n \n", "example": "PROCESSED" }, "EnumTransactionCreditCardDataFeeType": { "type": "string", "nullable": true, "enum": [ "ANNUAL_FEE", "NATIONAL_WITHDRAWAL", "INTERNATIONAL_WITHDRAWAL", "EMERGENCY_CREDIT_EVALUATION_FEE", "DUPLICATE_ISSUANCE_FEE", "PAYMENT_FEE", "SMS_FEE", "OTHERS", null ], "description": "The fee that can be charged for a card transaction. We return one of the following values:\n\n - `ANNUAL_FEE`\n - `NATIONAL_WITHDRAWAL`\n - `INTERNATIONAL_WITHDRAWAL`\n - `EMERGENCY_CREDIT_EVALUATION_FEE`\n - `DUPLICATE_ISSUANCE_FEE`\n - `PAYMENT_FEE`\n - `SMS_FEE`\n - `OTHERS`\n - `null`\n", "example": "NATIONAL_WITHDRAWAL" }, "EnumTransactionCreditCardDataCreditType": { "type": "string", "nullable": true, "enum": [ "REVOLVING_CREDIT", "BILL_INSTALLMENT_PAYMENT", "LOAN", "OTHERS", null ], "description": "Other types of credit that have been contracted on the card. We return one of the following values:\n\n - `REVOLVING_CREDIT`\n - `BILL_INSTALLMENT_PAYMENT`\n - `LOAN`\n - `OTHERS`\n - `null`\n", "example": "BILL_INSTALLMENT_PAYMENT" }, "TransactionCreditCardBill": { "type": "object", "nullable": true, "description": "Information regarding the bill that this transaction appears on.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier created by Belvo used to reference the current credit card bill.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n", "example": "8e9d13c2-af41-4a49-b43e-2da012bd1d11" }, "internal_identification": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The institution's internal identifier for the bill.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n", "example": "92792126019929279212650822221989319252576" } } }, "TransactionCreditCardDataOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "collected_at", "bill_name", "bill_status", "previous_bill_total", "bill_amount", "card_number", "fee_type", "fee_type_additional_info", "credits_type", "credits_type_additional_info", "installment_identifier", "number_of_installments" ], "description": "Additional data provided by the institution for credit card transactions.", "properties": { "collected_at": { "$ref": "#/components/schemas/collected_at" }, "bill_name": { "type": "string", "nullable": true, "description": "The title of the monthly credit card bill the transaction belongs to. The format of the returned value is institution specific, however, some common examples are:\n\n- diciembre-2021\n- dec-2021\n- dec-21\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n", "example": "apr-2020" }, "bill_due_date": { "type": "string", "nullable": true, "format": "date", "description": "The date that the bill is due to be paid, in `YYYY-MM-DD` format.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n", "example": "2023-06-17" }, "bill_internal_identification": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The institution's internal identifier for the bill.\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n", "example": "927921260199292792126508222219893192525A6" }, "bill_status": { "type": "string", "nullable": true, "description": "**Note:** This field is not applicable for OFDA Brazil and will return `null`.\n", "example": null }, "previous_bill_total": { "type": "string", "nullable": true, "description": "**Note:** This field is not applicable for OFDA Brazil and will return `null`.\n", "example": null }, "bill_amount": { "type": "number", "nullable": true, "format": "float", "pattern": "^-?\\d{1,15}\\.\\d{2,4}$", "description": "The bill amount, as of `collected_at`. For more information, see `credit_card_bill`.", "example": 300 }, "card_number": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The credit card number.\n\n**Note:** Often, this is just the last four digit of the credit card.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "4453" }, "fee_type": { "$ref": "#/components/schemas/EnumTransactionCreditCardDataFeeType" }, "fee_type_additional_info": { "type": "string", "nullable": true, "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "Additional information regarding the fee.\n", "example": "ATM withdrawal in Curitiba." }, "credits_type": { "$ref": "#/components/schemas/EnumTransactionCreditCardDataCreditType" }, "credits_type_additional_info": { "type": "string", "nullable": true, "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "Additional information regarding the credit type.\n", "example": "Some additional information." }, "installment_identifier": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "An identifier for the installment, according to the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "PARCELA_896" }, "number_of_installments": { "type": "integer", "nullable": true, "maximum": 999, "description": "The total number of installments for the card transaction, if applicable.\n", "example": 4 }, "credit_card_bill": { "$ref": "#/components/schemas/TransactionCreditCardBill" } } }, "EnumTransactionCounterpartyType": { "type": "string", "nullable": true, "enum": [ "INDIVIDUAL", "COMPANY", null ], "description": "The transaction counterparty type. We return one of the following values:\n\n - `INDIVIDUAL`\n - `COMPANY`\n - `null`\n", "example": "INDIVIDUAL" }, "TransactionCounterparty": { "type": "object", "nullable": true, "required": [ "type", "document_number", "clearing_code", "agency", "check_digit", "number" ], "description": "Information regarding the other party of this transaction, if available.", "properties": { "type": { "$ref": "#/components/schemas/EnumTransactionCounterpartyType" }, "document_number": { "type": "string", "nullable": true, "maxLength": 11, "pattern": "^\\d{11}$", "description": "The document number of the representative.\n\n**Note**: \n\nFor Brazil:\n - When the `type` is `INDIVIDUAL`, this is the CPF number.\n - When the `type` is `COMPANY`, this is the CNPJ number.\n", "example": "73677831148" }, "clearing_code": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^\\d{3}$", "description": "The banking clearing code.\n", "example": "001" }, "agency": { "type": "string", "nullable": true, "maxLength": 4, "pattern": "^\\d{1,4}$", "description": "The branch code where the account was opened.\n", "example": "6272" }, "check_digit": { "type": "string", "nullable": true, "maxLength": 2, "pattern": "[\\w\\W\\s]*", "description": "The check digit of the account number, if applicable.\n", "example": "7" }, "number": { "type": "string", "nullable": true, "maxLength": 20, "pattern": "^\\d{8,20}$", "description": "The account number of the product.\n", "example": "24550245" } } }, "TransactionLoanDataFees": { "type": "object", "nullable": true, "required": [ "name", "code", "amount" ], "description": "Details regarding the fees associated with this payment. Only applicable when `is_detached` = `true`.", "properties": { "name": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "The name of the fee.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `fees` field is present.\n", "example": "Reavaliação periódica do bem" }, "code": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "The institution's code for the fee.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `fees` field is present.\n", "example": "aval_bem" }, "amount": { "type": "number", "nullable": true, "format": "float", "pattern": "^-?\\d{1,15}\\.\\d{2,4}$", "description": "The amount of the fee.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `fees` field is present.\n", "example": 8903.77 } } }, "TransactionLoanDataCharges": { "type": "object", "nullable": true, "required": [ "type", "info", "amount" ], "description": "Details regarding the charges associated with this payment. Only applicable when `is_detached` = `true`.", "properties": { "type": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "The type of charge.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `charges` field is present\n", "example": "MULTA_ATRASO_PAGAMENTO" }, "info": { "type": "string", "maxLength": 140, "pattern": "^[\\w\\W\\s]{0,140}$", "description": "Additional information regarding the charge `type`.\n", "example": "Late payment charge." }, "amount": { "type": "number", "format": "float", "pattern": "^-?\\d{1,15}\\.\\d{2,4}$", "description": "The amount of the charge.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `charges` field is present\n", "example": 8903.77 } } }, "TransactionLoanDataOpenFinanceBrazil": { "type": "object", "nullable": true, "required": [ "is_detached", "installment_id", "fees", "charges" ], "description": "Information regarding the loan transactional data, if applicable.", "properties": { "is_detached": { "type": "boolean", "description": "Boolean to indicate whether or not this loan payment was part of the original payment schedule.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": true }, "installment_id": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The institution's unique ID for this payment installment.\n", "example": "WGx0aExYcEJMVm93TFRsZFcyRXRla0V0V2pBdE9Wd3RYWH" }, "fees": { "type": "array", "description": "Details regarding the fees associated with this payment. Only applicable when `is_detached` = `true`.", "items": { "$ref": "#/components/schemas/TransactionLoanDataFees" } }, "charges": { "type": "array", "minItems": 0, "description": "Details regarding the charges associated with this payment. Only applicable when `is_detached` = `true`.", "items": { "$ref": "#/components/schemas/TransactionLoanDataCharges" } } } }, "EnumTransactionPaymentType": { "type": "string", "nullable": true, "enum": [ "FULL", "INSTALLMENT", null ], "description": "The transaction payment type. We return one of the following values:\n\n - `FULL`\n - `INSTALLMENT`\n - `null`\n", "example": "FULL" }, "TransactionOpenFinanceBrazil": { "type": "object", "title": "Transaction Object (Brazil)", "x-tags": [ "Transactions" ], "required": [ "id", "internal_identification", "account", "collected_at", "created_at", "value_date", "accounting_date", "amount", "local_currency_amount", "balance", "currency", "description", "observations", "merchant", "category", "subcategory", "reference", "type", "status", "credit_card_data", "counterparty", "loan_data", "payment_type", "operation_type", "operation_type_additional_info", "mcc" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "internal_identification": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The institution's internal identification for the transaction.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "TXpRMU9UQTROMWhZV2xSU1FUazJSMDl" }, "account": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "value_date": { "type": "string", "format": "date", "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date when the transaction occurred, in `YYYY-MM-DD` format, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "2019-10-23" }, "transacted_at": { "type": "string", "format": "date-time", "pattern": "(^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)\\.(?:[0-9]){3}Z$)", "description": "The ISO-8601 timestamp of when the transaction occurred (in the UTC timezone).\n\n> **Note:** For transactions that occurred before 31.01.2024, the timestamp may only indicate the day (for example, `2016-01-29T00:00:00.000Z`). However, transactions that occurred after this date must include the date and time (`2024-02-20T12:29:03.374Z`).\n\n> **Institutions not abiding by this format:**\n> Some institutions may not provide the exact time of the transaction. In this case, the timestamp will be set to `00:00:00.000Z`.\n> Belvo has identified the following institutions as not abiding by the regulation and have raised the issue with regulators: Bradesco, Itau, and Sicoob.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **credit card and checking account transactions**.\n", "example": "2024-02-20T12:29:03.374Z" }, "accounting_date": { "type": "string", "nullable": true, "description": "The date when the transaction was processed and accounted for by the institution, in `YYYY-MM-DD` format.\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **credit card transactions**.", "example": "2019-10-23" }, "inferred_accounting_date": { "type": "string", "format": "date", "description": "In the case that the transaction occured on a weekend or public holiday, Belvo will infer the date that the transaction is accounted for by the institution. Typically, this is the next business day.\n", "example": "2019-10-23" }, "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The transaction amount.\nℹ️ The amount displayed is always positive as we indicate the direction of the transaction in the `type` parameter.\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": 2145.45 }, "local_currency_amount": { "type": "number", "nullable": true, "format": "float", "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The value of the transaction in the local currency.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **credit card transactions**.\n", "example": 7623.64 }, "balance": { "type": "number", "nullable": true, "format": "float", "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "currency": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n", "example": "BRL" }, "description": { "type": "string", "nullable": true, "description": "The description of transaction provided by the institution. Usually this\nis the text that the end user sees in the online platform.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "SEVEN BUDDHAS RFC:XXXXXXXXXX" }, "observations": { "type": "string", "nullable": true, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "merchant": { "$ref": "#/components/schemas/TransactionMerchantData" }, "category": { "$ref": "#/components/schemas/EnumTransactionCategory" }, "subcategory": { "$ref": "#/components/schemas/EnumTransactionSubcategory" }, "reference": { "type": "string", "nullable": true, "maxLength": 128, "description": "**Note:** This field is not applicable for OF Brazil and will return null.\n", "example": null }, "type": { "$ref": "#/components/schemas/EnumTransactionType" }, "status": { "$ref": "#/components/schemas/EnumTransactionStatus" }, "credit_card_data": { "$ref": "#/components/schemas/TransactionCreditCardDataOpenFinanceBrazil" }, "counterparty": { "$ref": "#/components/schemas/TransactionCounterparty" }, "loan_data": { "$ref": "#/components/schemas/TransactionLoanDataOpenFinanceBrazil" }, "payment_type": { "$ref": "#/components/schemas/EnumTransactionPaymentType" }, "operation_type": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z_]{0,50}$", "description": "The type of transaction. For example, a PIX payment or a deposit.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network for **non-loan account transactions**.\n", "example": "TRANSFERENCIA_MESMA_INSTITUICAO" }, "operation_type_additional_info": { "type": "string", "nullable": true, "maxLength": 140, "pattern": "^\\S[\\s\\S]*$", "description": "Additional information regarding the `operation_type`, if applicable.\n", "example": "Internal transfer." }, "mcc": { "type": "integer", "nullable": true, "format": "int32", "pattern": "^[0-9]{4}$", "description": "The four-digit (ISO-18245 compliant) Merchant Category Code (MCC) for the transaction. This field is only applicable for credit card transactions.\n", "example": 5137 } } }, "date_from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The date from which you want to start getting data for, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n", "example": "2020-08-05" }, "date_to": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The date you want to stop getting data for, in `YYYY-MM-DD` format.\n\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n", "example": "2020-10-05" }, "EnumBillFinanceChargeType": { "type": "string", "nullable": true, "enum": [ "LATE_PAYMENT_INTEREST", "LATE_FEE", "ARREARS_INTEREST", "IOF", "NO_CHARGE", "OTHER", null ], "description": "The type of finance charge applied to the bill. We return one of the following values:\n\n - `LATE_PAYMENT_INTEREST`\n - `LATE_FEE`\n - `ARREARS_INTEREST`\n - `IOF`\n - `NO_CHARGE`\n - `OTHER`\n - `null`\n", "example": "LATE_PAYMENT_INTEREST" }, "BillFinanceCharges": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/EnumBillFinanceChargeType" }, "additional_info": { "type": "string", "nullable": true, "maxLength": 140, "pattern": "[\\w\\W\\s]*", "description": "Additional information about the finance charge.\n", "example": "Paid 15 days late, fee applied." }, "currency": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n", "example": "BRL" }, "amount": { "type": "number", "nullable": true, "format": "float", "minLength": 1, "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount of the finance charge.\n", "example": 91.89 } } }, "EnumBillPaymentType": { "type": "string", "nullable": true, "enum": [ "INSTALLMENT", "FULL", "OTHER", null ], "description": "The type of payment. We return one of the following values:\n\n - `INSTALLMENT`\n - `FULL`\n - `OTHER`\n - `null`\n", "example": "INSTALLMENT" }, "EnumBillPaymentPaymentMode": { "type": "string", "nullable": true, "enum": [ "DIRECT_DEBIT", "BANK_SLIP", "SALARY_DEDUCTION", "PIX", null ], "description": "The method in which the payment was made. We return one of the following values:\n\n - `DIRECT_DEBIT`\n - `BANK_SLIP`\n - `SALARY_DEDUCTION`\n - `PIX`\n - `null`\n", "example": "DIRECT_DEBIT" }, "BillPayments": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/EnumBillPaymentType" }, "payment_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the payment was made, in `YYYY-MM-DD` format.\n", "example": "2021-09-04" }, "payment_mode": { "$ref": "#/components/schemas/EnumBillPaymentPaymentMode" }, "currency": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n", "example": "BRL" }, "amount": { "type": "number", "nullable": true, "format": "float", "minLength": 1, "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount of the payment.\n", "example": 500.15 } } }, "Bill": { "type": "object", "title": "Bill Object (OFDA Brazil)", "x-tags": [ "Bills" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "account": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" }, "internal_identification": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "description": "The institution's internal identifier for the bill.", "example": "92792126019929279212650822221989319252576" }, "bill_name": { "type": "string", "nullable": true, "description": "The title of the monthly credit card bill the transaction belongs to. The format of the returned value is institution specific, however, some common examples are:\n\n- diciembre-2021\n- dec-2021\n- dec-21\n\n> **Note**: This field is only returned for 'closed' bills (meaning the billing period has ended and the bill has been emitted). If the billing period is still ongoing, we return `null`.\n", "example": "apr-2020" }, "due_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the bill is to be paid, in `YYYY-MM-DD` format.\n", "example": "2021-09-06" }, "currency": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n", "example": "BRL" }, "total_amount": { "type": "number", "nullable": true, "format": "float", "minLength": 1, "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total amount of the bill.\n", "example": 45391.89 }, "minimum_amount": { "type": "number", "nullable": true, "format": "float", "minLength": 1, "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The minimum amount to pay.\n", "example": 391.89 }, "is_installment": { "type": "boolean", "nullable": true, "description": "Boolean to indicate whether this bill can be paid in installments.\n", "example": false }, "finance_charges": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BillFinanceCharges" } }, "payments": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/BillPayments" } } } }, "EnumOwnerMaritalStatus": { "type": "string", "nullable": true, "enum": [ "SINGLE", "MARRIED", "WIDOWED", "SEPARATED", "DIVORCED", "CIVIL_UNION", "OTHER" ], "description": "The individual's marital status. We return one of the following values:\n\n - `SINGLE`\n - `MARRIED`\n - `WIDOWED`\n - `SEPARATED`\n - `DIVORCED`\n - `CIVIL_UNION`\n - `OTHER`\n", "example": "SINGLE" }, "EnumOwnerGender": { "type": "string", "nullable": true, "enum": [ "FEMALE", "MALE", "OTHER" ], "description": "The individual's gender. We return on of the following values:\n\n - `FEMALE`\n - `MALE`\n - `OTHER`\n \n", "example": "FEMALE" }, "OwnerDocumentIdOpenFinanceBrazil": { "type": "object", "required": [ "document_type", "document_number" ], "description": "Information regarding the identification document the owner provided to the bank.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "properties": { "document_type": { "type": "string", "description": "The type of document the owner provided to the institution to open the account. Common document types are:\n\n🇧🇷 Brazil\n- `CPF` (*Cadastro de Pessoas Físicas*)\n- `CNPJ`(*Cadastro Nacional de Pessoas Jurídicas*)\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "CPF" }, "document_number": { "type": "string", "description": "The document's identification number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "235578435-S" } } }, "EnumOwnerIndividualDocumentIdType": { "type": "string", "nullable": true, "enum": [ "DRIVERS_LICENSE", "PASSPORT", "ID_CARD", "FISCAL_ID", "FOREIGNER_REGISTRATION_CARD", "OTHER", null ], "description": "The type of ID document. We return one of the following values:\n\n - `DRIVERS_LICENSE`\n - `PASSPORT`\n - `ID_CARD`\n - `FISCAL_ID`\n - `FOREIGNER_REGISTRATION_CARD`\n - `OTHER`\n - `null`\n \n", "example": "DRIVERS_LICENSE" }, "OwnerIndividualDocumentIds": { "type": "object", "nullable": true, "required": [ "type", "type_additional_info", "number", "check_digit", "issue_date", "expiration_date", "country_of_issuance", "additional_info" ], "description": "Detailed information regarding additional documents provided to prove the individuals ID.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerIndividualDocumentIdType" }, "type_additional_info": { "type": "string", "nullable": true, "maxLength": 70, "pattern": "^[\\w\\W\\s]{0,70}$", "description": "Additional information regarding the document type.\n\n> Note: For Business ID documents, this field must return a value from Brazil's open finance network.\n", "example": "Learner's licence" }, "number": { "type": "string", "maxLength": 40, "pattern": "^[\\w\\W\\s]{0,40}$", "description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "DL-7896829-7" }, "check_digit": { "type": "string", "maxLength": 2, "pattern": "^[\\w\\W\\s]{0,2}$", "description": "The check digit of the ID document.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "7" }, "issue_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "expiration_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "country_of_issuance": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[\\w]{3}$", "description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n\nThis field must be returned when the `type` is `PASSPORT`.\n", "example": "CAN" }, "additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W\\s]{0,100}$", "description": "Additional information about the ID document.\n", "example": "The document has water damage" } } }, "OwnerIndividualNationalityDocumentId": { "type": "object", "nullable": true, "required": [ "type", "type_additional_info", "number", "issue_date", "expiration_date", "country_of_issuance", "additional_info" ], "description": "Detailed information regarding additional documents provided to prove the individuals ID.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerIndividualDocumentIdType" }, "number": { "type": "string", "maxLength": 40, "pattern": "^[\\w\\W\\s]{0,40}$", "description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "DL-7896829-7" }, "issue_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "expiration_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "country_of_issuance": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^[\\w]{3}$", "description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n\nThis field must be returned when the `type` is `PASSPORT`.\n", "example": "CAN" }, "additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W\\s]{0,100}$", "description": "Additional information about the ID document.\n", "example": "The document has water damage" } } }, "OwnerNationalities": { "type": "object", "required": [ "info", "documents" ], "description": "Detailed information regarding the individual's nationalities.", "properties": { "info": { "type": "string", "nullable": true, "pattern": "^\\S[\\s\\S]*$", "maxLength": 40, "description": "The nationality of the individual.\n", "example": "CAN" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerIndividualNationalityDocumentId" } } } }, "OwnerEmails": { "type": "object", "nullable": true, "required": [ "is_main", "email" ], "description": "Additional list of emails the owner provided.", "properties": { "is_main": { "type": "boolean", "description": "Boolean to indicate if this is the user's main email address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": true }, "email": { "type": "string", "maxLength": 320, "pattern": "^[\\w\\W\\s]{0,320}$", "description": "The user's email address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "homen_morcego@gmail.com" } } }, "OwnerAddresses": { "type": "object", "nullable": true, "required": [ "is_main", "address", "additional_info", "district_name", "town", "town_code", "state", "postcode", "country_name", "country_code", "latitude", "longitude" ], "description": "Detailed information regarding the owner's addresses.", "properties": { "is_main": { "type": "boolean", "description": "Boolean to indicate if this is the user's main address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": true }, "address": { "type": "string", "maxLength": 150, "pattern": "^[\\w\\W\\s]{0,150}$", "description": "The user's address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Av Naburo Ykesaki, 1270" }, "additional_info": { "type": "string", "nullable": true, "maxLength": 150, "pattern": "^[\\w\\W\\s]{0,150}$", "description": "Additional information regarding the user's address.\n", "example": "In between two palm trees" }, "district_name": { "type": "string", "nullable": true, "maxLength": 50, "pattern": "^[\\w\\W\\s]{0,50}$", "description": "The distrct of the address.\n", "example": "CENTRO" }, "town": { "type": "string", "maxLength": 50, "pattern": "^[\\w\\W\\s]{0,50}$", "description": "The user's town.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Brasilia" }, "town_code": { "type": "string", "nullable": true, "maxLength": 7, "pattern": "\\d{7}$", "description": "The seven-digit code for the town, if applicable.\n\nFor Brazil, this is the IBGE town code.\n", "example": "3550308" }, "state": { "type": "string", "nullable": true, "maxLength": 2, "pattern": "^[\\w\\W\\s]{0,2}$", "description": "The state that the address is located in.\n", "example": "SP" }, "postcode": { "type": "string", "maxLength": 8, "pattern": "^\\d{8}$", "description": "The postcode of the address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "17500001" }, "country_name": { "type": "string", "maxLength": 80, "pattern": "^[\\w\\W\\s]{0,80}$", "description": "The name of the country.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Brasil" }, "country_code": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^([A-Z]{3})$", "description": "The three-letter country code (ISO-3166 Alpha 3 compliant).\n", "example": "BRA" }, "latitude": { "type": "string", "nullable": true, "maxLength": 13, "pattern": "^-?\\d{1,2}\\.\\d{1,9}$", "description": "The geographic latitude coordinate.\n", "example": "-23.5475000" }, "longitude": { "type": "string", "nullable": true, "maxLength": 13, "pattern": "^-?\\d{1,3}\\.\\d{1,8}$", "description": "The geographic longitude coordinate.\n", "example": "-46.6361100" } } }, "EnumOwnerPhoneNumberType": { "type": "string", "nullable": true, "enum": [ "LANDLINE", "MOBILE", "OTHER", null ], "description": "The type of phone number. We return one of the following values:\n\n - `LANDLINE`\n - `MOBILE`\n - `OTHER`\n - `null`\n", "example": "MOBILE" }, "OwnerPhoneNumbers": { "type": "object", "nullable": true, "required": [ "is_main", "type", "additional_info", "number", "country_code", "area_code", "extension" ], "description": "Detailed information regarding the owners's `phone_number`s.", "properties": { "is_main": { "type": "boolean", "description": "Boolean to indicate if this is the user's main phone number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": true }, "type": { "$ref": "#/components/schemas/EnumOwnerPhoneNumberType" }, "additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W\\s]{0,100}$", "description": "Additional information about the phone number.\n", "example": "This is their work mobile number." }, "number": { "type": "string", "maxLength": 11, "pattern": "^([0-9]{8,11})$", "description": "The phone number (not including the country, area, or extension codes).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "29875132" }, "country_code": { "type": "string", "nullable": true, "maxLength": 4, "pattern": "^\\d{1,4}$", "description": "The country dialling code. For example: `351` (no `+`).\n", "example": "351" }, "area_code": { "type": "string", "nullable": true, "maxLength": 2, "pattern": "^\\d{1,2}$", "description": "The area dialling code.\n", "example": "21" }, "extension": { "type": "string", "nullable": true, "maxLength": 5, "pattern": "^\\d{1,5}$", "description": "The extension code.\n", "example": "932" } } }, "EnumOwnerFiliationType": { "type": "string", "nullable": true, "enum": [ "MOTHER", "FATHER", null ], "description": "The familial relationship. We return one of the following values:\n\n - `MOTHER`\n - `FATHER`\n - `null`\n \n", "example": "MOTHER" }, "OwnerFiliations": { "type": "object", "required": [ "type", "civil_name", "social_name" ], "description": "Information regarding any familial relationships of the individual.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerFiliationType" }, "civil_name": { "type": "string", "maxLength": 70, "pattern": "^[\\w\\W\\s]{0,70}$", "description": "The person's full name.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Bruce Wayne" }, "social_name": { "type": "string", "nullable": true, "maxLength": 70, "pattern": "^[\\w\\W\\s]{0,70}$", "description": "The person's social name.\n", "example": "The Dark Knight" } } }, "EnumOwnerIndividualFinancialProfileOccupationCode": { "type": "string", "nullable": true, "enum": [ "BRAZIL_PUBLIC_OFFICE", "BRAZIL_OCCUPATION_CODE", "OTHER", null ], "description": "The area of employment of the individual. We return one of the following values:\n\n - `BRAZIL_PUBLIC_OFFICE`\n - `BRAZIL_OCCUPATION_CODE`\n - `OTHER`\n - `null`\n", "example": "BRAZIL_OCCUPATION_CODE" }, "EnumOwnerInformedIncomeFrequency": { "type": "string", "nullable": true, "enum": [ "DAILY", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "BIMONTHLY", "QUARTERLY", "BIANNUALLY", "ANNUALLY", "OTHERS" ], "description": "Indicates how often the individual receives their salary. We return one of the following values:\n\n - `DAILY`\n - `WEEKLY`\n - `FORTNIGHTLY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `QUARTERLY`\n - `BIANNUALLY`\n - `ANNUALLY`\n - `OTHERS`\n", "example": "MONTHLY" }, "OwnerIndividualInformedIncome": { "type": "object", "required": [ "frequency", "amount", "currency", "date" ], "description": "Information regarding the individual's reported income.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "properties": { "frequency": { "$ref": "#/components/schemas/EnumOwnerInformedIncomeFrequency" }, "amount": { "type": "number", "format": "float", "minLength": 1, "maxLength": 20, "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The reported income that the individual receives.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": 45391.89 }, "currency": { "type": "string", "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "BRL" }, "date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "Date when the individual last received their salary.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "2020-03-19" } } }, "OwnerIndividualPatrimony": { "type": "object", "nullable": true, "required": [ "amount", "currency", "year" ], "description": "Information regarding the individual's reported assets (if available).", "properties": { "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The reported assets of the individual.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `patrimony` object is available.\n", "example": 45391.89 }, "currency": { "type": "string", "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `patrimony` object is available.\n", "example": "BRL" }, "year": { "type": "integer", "format": "int32", "maximum": 2090, "minimum": 1700, "description": "The year that the reported assets applied. \n\n> **Non-nullable:** A value must be returned by Brazil's open finance network when the `patrimony` object is available.\n", "example": 2020 } } }, "OwnerIndividualFinancialProfile": { "type": "object", "nullable": true, "required": [ "company_id", "occupation_code", "occupation_description", "informed_income", "patrimony" ], "description": "Information regarding the financial profile of the individual.", "properties": { "company_id": { "type": "string", "nullable": true, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The identifier of the company where the individual is employed.\n", "example": "50685362000135" }, "occupation_code": { "$ref": "#/components/schemas/EnumOwnerIndividualFinancialProfileOccupationCode" }, "occupation_description": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "[\\w\\W\\s]*", "description": "Information regarding the individual's occupation.\n", "example": "01" }, "informed_income": { "$ref": "#/components/schemas/OwnerIndividualInformedIncome" }, "patrimony": { "$ref": "#/components/schemas/OwnerIndividualPatrimony" } } }, "EnumOwnerProcuratorType": { "type": "string", "nullable": true, "enum": [ "LEGAL_REPRESENTATIVE", "ATTORNEY", null ], "description": "The type of representative that can access and make changes to the account. We return one of the following values:\n\n - `LEGAL_REPRESENTATIVE`\n - `ATTORNEY`\n - `null`\n \n", "example": "LEGAL_REPRESENTATIVE" }, "OwnerProcurators": { "type": "object", "nullable": true, "required": [ "type", "civil_name", "social_name", "document_number" ], "description": "Information regarding any individuals or companies that can act on behalf of the owner.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerProcuratorType" }, "civil_name": { "type": "string", "maxLength": 70, "pattern": "^[\\w\\W]*$", "description": "The representatives's full name.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `procurators` field is available.\n", "example": "Alfred Thaddeus Pennyworth" }, "social_name": { "type": "string", "nullable": true, "maxLength": 70, "pattern": "^[\\w\\W]*$", "description": "The person's social name.\n", "example": "Alfred Pennyworth" }, "document_number": { "type": "string", "maxLength": 11, "pattern": "^\\d{11}$", "description": "The document number of the representative.\n\n**Note**: For individuals, this is Brazil's CPF number. For businesses, this is Brazil's CNPJ number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `procurators` field is available.\n", "example": "73677831148" } } }, "EnumOwnerIndividualProductType": { "type": "string", "nullable": true, "enum": [ "SAVINGS_ACCOUNT", "CHECKING_ACCOUNT", null ], "description": "The additional products the individual has at the institution. We return one of the following values:\n\n - `SAVINGS_ACCOUNT`\n - `CHECKING_ACCOUNT`\n - `null`\n", "example": "SAVINGS_ACCOUNT" }, "OwnerIndividualProducts": { "type": "object", "nullable": true, "required": [ "type", "subtype", "agency", "clearing_code", "number", "check_digit" ], "description": "Details regarding any additional products that the individual has with the institution.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerIndividualProductType" }, "subtype": { "type": "string", "nullable": true, "description": "The subtype of the product that the individual has at the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "CONJUNTA_SIMPLES" }, "agency": { "type": "string", "nullable": true, "maxLength": 4, "pattern": "^\\d{1,4}$", "description": "The branch code where the product was opened.\n", "example": "6272" }, "clearing_code": { "type": "string", "maxLength": 3, "pattern": "^\\d{3}$", "description": "The banking clearing code for the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "001" }, "number": { "type": "string", "maxLength": 20, "pattern": "^\\d{8,20}$", "description": "The account number of the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `procurators` field is available.\n", "example": "24550245" }, "check_digit": { "type": "string", "maxLength": 2, "pattern": "[\\w\\W\\s]*", "description": "The check digit of the product's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "7" } } }, "OwnerIndividualSalaryPortabilityRequests": { "type": "object", "description": "Details regarding the salary portability request.", "properties": { "employer_name": { "type": "string", "maxLength": 80, "pattern": "^(?!\\s)[\\w\\W\\s]*[^\\s]$", "description": "The name of the employer.", "example": "ACME Inc." }, "employer_id_number": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^\\d{14}$|^\\d{11}$", "description": "The CPF or CNPJ of the employer.", "example": 12345678901 }, "employer_bank_id_number": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The CNPJ of the employer's bank.", "example": 12345678901234 }, "employer_bank_code": { "type": "string", "minLength": 8, "maxLength": 8, "pattern": "^[0-9]{8}$", "description": "The bank ISPB (*Identificador de Sistema de Pagamentos Brasileiro*s) code of the employer's bank.", "example": 12345678 }, "portability_approval_date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the portability request was approved, in `YYYY-MM-DD` format.", "example": "2024-04-01" } } }, "OwnerIndividualPayrollAccounts": { "type": "object", "description": "Details regarding the payroll bank account.", "properties": { "employer_name": { "type": "string", "maxLength": 80, "pattern": "^(?!\\s)[\\w\\W\\s]*[^\\s]$", "description": "The name of the employer.", "example": "ACME Inc." }, "employer_id_number": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^\\d{14}$|^\\d{11}$", "description": "The CPF or CNPJ of the employer.", "example": 12345678901 }, "employer_bank_id_number": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The CNPJ of the employer's bank.", "example": 12345678901234 }, "employer_bank_code": { "type": "string", "minLength": 8, "maxLength": 8, "pattern": "^[0-9]{8}$", "description": "The bank ISPB (*Identificador de Sistema de Pagamentos Brasileiro*s) code of the employer's bank.", "example": 12345678 }, "account_opening_date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the salary bank account was opened, in `YYYY-MM-DD` format.", "example": "2024-04-01" } } }, "OwnerIndividualFinancialRelation": { "type": "object", "nullable": true, "required": [ "start_date", "product_services", "product_services_additional_info", "procurators", "products" ], "description": "Details regarding any additional relationship the individual has with the institution (for example, other accounts or products they have with the institution).", "properties": { "start_date": { "type": "string", "format": "date-time", "maxLength": 20, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)Z$", "description": "The ISO-8601 timestamp when the financial relationship between the individual and the institution started.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "2021-05-21T08:30:00Z" }, "product_services": { "type": "array", "minItems": 1, "description": "A list of products that the individual has with the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "type": "string", "description": "The name of the product, according to the institution.\n", "example": "CONTA_DEPOSITO_A_VISTA" } }, "product_services_additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W]*$", "description": "Additional information regarding the products that the individual has.\n", "example": "Joint account with Robin" }, "procurators": { "type": "array", "description": "Information regarding any individuals or companies that can act on behalf of the owner.", "items": { "$ref": "#/components/schemas/OwnerProcurators" } }, "products": { "type": "array", "description": "Details regarding any additional products that the individual has with the institution.", "items": { "$ref": "#/components/schemas/OwnerIndividualProducts" } }, "salary_portability_requests": { "type": "array", "description": "Details regarding any salary portability requests that the individual has made with the institution.\n\nA salary portability is a request to transfer the individual's salary from their employer's 'payroll' bank account to another bank account.\n\n> 📘 \n>\n> Please note that the receiving bank account cannot terminate a salary portability (or be informed that it has been termnated). Only the employer's payroll bank is able to provide this information. As such, the portabilities listed here may not be up-to-date.\n", "items": { "$ref": "#/components/schemas/OwnerIndividualSalaryPortabilityRequests" } }, "payroll_accounts": { "type": "array", "description": "Details regarding any payroll bank accounts that are associated with the individual. That is, each time the indivudal has a new employer that they receive a salary from, it should be listed here.\n\n> 📘\n>\n> Past employers may not close the payroll account for the indiviual. As such, the payroll accounts listed here may not be up-to-date.\n", "items": { "$ref": "#/components/schemas/OwnerIndividualPayrollAccounts" } } } }, "OwnerIndividualOpenFinanceBrazil": { "type": "object", "title": "Owner Individual (OFDA Brazil)", "x-tags": [ "Owners" ], "required": [ "id", "link", "internal_identification", "collected_at", "created_at", "display_name", "social_name", "birth_date", "marital_status", "marital_status_additional_info", "gender", "companies_id", "is_local_resident", "document_id", "additional_documents", "nationalities", "email", "emails", "address", "addresses", "phone_number", "phone_numbers", "filiations", "financial_profile", "financial_relation" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "internal_identification": { "type": "string", "nullable": true, "description": "The institution's internal identifier for the owner.", "example": "7e5838e4" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "display_name": { "type": "string", "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The full name of the individual, as provided by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Jack Oswald White" }, "social_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The social name of the individual, as generally accepted by the country.\n", "example": "O Piadista" }, "birth_date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The individual's date of birth, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "1988-07-15" }, "marital_status": { "$ref": "#/components/schemas/EnumOwnerMaritalStatus" }, "marital_status_additional_info": { "type": "string", "nullable": true, "maxLength": 50, "pattern": "^[\\w\\W]{0,50}$", "description": "Additional information about the individual's marital status.\n", "example": "It's complicated" }, "gender": { "$ref": "#/components/schemas/EnumOwnerGender" }, "companies_id": { "type": "array", "minItems": 1, "description": "The institutions responsible for the creation and verification of the owner.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "type": "string", "maxLength": 14, "pattern": "^\\d{14}$", "description": "The institutions responsible for the creation and verification of the owner.\n", "example": "01773247000103" } }, "is_local_resident": { "type": "boolean", "description": "Boolean to indicate if the individual is a local resident of the country.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": true }, "document_id": { "$ref": "#/components/schemas/OwnerDocumentIdOpenFinanceBrazil" }, "additional_documents": { "type": "array", "description": "Detailed information regarding additional documents provided to prove the individuals ID.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "minItems": 1, "items": { "$ref": "#/components/schemas/OwnerIndividualDocumentIds" } }, "nationalities": { "type": "array", "nullable": true, "minItems": 1, "description": "Detailed information regarding the individual's nationalities.\n\nOnly required to be returned when `is_local_resident` is set to `false`.\n", "items": { "$ref": "#/components/schemas/OwnerNationalities" } }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 320, "description": "The account owner's registered email address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "johndoe@belvo.com" }, "emails": { "type": "array", "minItems": 0, "description": "Additional list of emails the owner provided.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/OwnerEmails" } }, "address": { "type": "string", "nullable": true, "description": "The account owner's registered address.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Carrer de la Llacuna, 162, 08018 Barcelona" }, "addresses": { "type": "array", "minItems": 1, "description": "Detailed information regarding the owner's addresses.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/OwnerAddresses" } }, "phone_number": { "type": "string", "nullable": true, "description": "The account owner's registered phone number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "+52-XXX-XXX-XXXX" }, "phone_numbers": { "type": "array", "minItems": 0, "description": "Detailed information regarding the owner's phone numbers.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/OwnerPhoneNumbers" } }, "filiations": { "type": "array", "minItems": 1, "description": "Information regarding any familial relationships of the individual.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/OwnerFiliations" } }, "financial_profile": { "$ref": "#/components/schemas/OwnerIndividualFinancialProfile" }, "financial_relation": { "$ref": "#/components/schemas/OwnerIndividualFinancialRelation" } } }, "OwnerBusinessDocumentIds": { "type": "object", "nullable": true, "required": [ "type", "type_additional_info", "number", "check_digit", "issue_date", "expiration_date", "country_of_issuance", "additional_info" ], "description": "Detailed information regarding additional documents provided to prove the business's ID.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerIndividualDocumentIdType" }, "type_additional_info": { "type": "string", "nullable": true, "maxLength": 70, "pattern": "^[\\w\\W\\s]{0,70}$", "description": "Additional information regarding the document type.\n\n> Note: For Business ID documents, this field must return a value from Brazil's open finance network.\n", "example": "EIN" }, "number": { "type": "string", "maxLength": 40, "pattern": "^[\\w\\W]{0,40}$", "description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "DL-7896829-7" }, "check_digit": { "type": "string", "maxLength": 2, "pattern": "^[\\w\\W\\s]{0,2}$", "description": "The check digit of the ID document.\n\n> **Note**: This field is not applicable for Business ID documents and will return `null`.\n", "example": null }, "issue_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n\n> **Note**: This field is not applicable for Business ID documents and will return `null`.\n", "example": null }, "expiration_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "country_of_issuance": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^(\\w{3}){1}$", "description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "CAN" }, "additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W\\s]{0,100}$", "description": "Additional information about the ID document.\n\n> **Note**: This field is not applicable for Business ID documents and will return `null`.\n", "example": null } } }, "EnumOwnerPartyPersonType": { "type": "string", "nullable": true, "enum": [ "INDIVIDUAL", "COMPANY" ], "description": "The type of person that is an ownership party of the account. We return one of the following values:\n\n - `INDIVIDUAL`\n - `COMPANY`\n \n", "example": "INDIVIDUAL" }, "EnumOwnerPartyType": { "type": "string", "nullable": true, "enum": [ "MEMBER", "ADMINISTRATOR" ], "description": "The access type that the `person_type` has to the account. We return one of the following values:\n\n- `MEMBER` indicates that the `person_type` has read access to the account.\n- `ADMINISTRATOR` indicates that the `person_type` can perform all actions for the account (including transfers).\n", "example": "MEMBER" }, "EnumOwnerPartyDocumentType": { "type": "string", "nullable": true, "enum": [ "CPF", "CNPJ", "OTHER_TRAVEL_DOCUMENT", "PASSPORT" ], "description": "The type of ID document the party provided when being added to the account. We return one of the following values:\n\n - `CPF`\n - `CNPJ`\n - `OTHER_TRAVEL_DOCUMENT`\n - `PASSPORT`\n", "example": "CPF" }, "OwnerParties": { "type": "object", "nullable": true, "required": [ "person_type", "type", "display_name", "social_name", "trade_name", "start_date", "percentage_type", "document_type", "document_number", "document_issue_date", "document_expiration_date", "document_country", "document_additional_info" ], "description": "Detailed information regarding the parties allowed to act on the owner's behalf.", "properties": { "person_type": { "$ref": "#/components/schemas/EnumOwnerPartyPersonType" }, "type": { "$ref": "#/components/schemas/EnumOwnerPartyType" }, "display_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The full name of the individual, as provided by the institution. Only applicable if the `person_type` is `INDIVIDUAL`.\n", "example": "Jack Oswald White" }, "social_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The social name of the individual, as generally accepted by the country. Only applicable if the `person_type` is `INDIVIDUAL`.\n", "example": "O Piadista" }, "company_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The full (official) name of the business. Only applicable if the `person_type` is `COMPANY`.\n", "example": "Wayne Enterprises" }, "trade_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The trade name of the business. Only applicable if the `person_type` is `COMPANY`.\n", "example": "WayneCorp" }, "start_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the party was added to the account, in `YYYY-MM-DD` format.\n", "example": "2021-07-15" }, "percentage_type": { "type": "number", "nullable": true, "format": "float", "minLength": 8, "maxLength": 8, "pattern": "^[01]\\.\\d{6}$", "description": "The party's equity interest.\n", "example": 0.51 }, "document_type": { "$ref": "#/components/schemas/EnumOwnerPartyDocumentType" }, "document_number": { "type": "string", "maxLength": 40, "pattern": "^[\\w\\W\\s]{0,40}$", "description": "The ID document's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "DL-7896829-7" }, "document_issue_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document was issued, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "document_expiration_date": { "type": "string", "nullable": true, "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date the the ID document expires, in `YYYY-MM-DD` format.\n", "example": "2019-01-01" }, "document_country": { "type": "string", "nullable": true, "maxLength": 3, "pattern": "^(\\w{3}){1}$", "description": "The three-letter country code that issued the document (in ISO-3166 Alpha 3 format).\n", "example": "CAN" }, "document_additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "^[\\w\\W\\s]{0,100}$", "description": "Additional information regarding the document.\n", "example": "Confirmed CPF with their driver's licence." } } }, "OwnerBusinessEconomicActivies": { "type": "object", "nullable": true, "required": [ "is_main", "code" ], "description": "Details regarding the reported economic activities of the business.", "properties": { "is_main": { "type": "boolean", "description": "Boolean to indicate whether this is the business's main economic activity.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `economic_activities` field is available.\n", "example": true }, "code": { "type": "string", "minLength": 2, "maxLength": 7, "pattern": "^\\d{2,7}$", "description": "The code of the economic activity, as given by the country.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `economic_activities` field is available.\n", "example": "8599604" } } }, "EnumOwnerBusinessInformedRevenueFrequency": { "type": "string", "nullable": true, "enum": [ "DAILY", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "BIMONTHLY", "QUARTERLY", "BIANNUALLY", "ANNUALLY", "OTHERS", null ], "description": "Indicates how often the business declares their revenue. We return one of the following values:\n \n - `DAILY`\n - `WEEKLY`\n - `FORTNIGHTLY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `QUARTERLY`\n - `BIANNUALLY`\n - `ANNUALLY`\n - `OTHERS`\n - `null`\n", "example": "MONTHLY" }, "OwnerBusinessInformedRevenue": { "type": "object", "nullable": true, "required": [ "frequency", "frequency_additional_info", "amount", "currency", "year" ], "description": "Information regarding the business's reported revenue.", "properties": { "frequency": { "$ref": "#/components/schemas/EnumOwnerBusinessInformedRevenueFrequency" }, "frequency_additional_info": { "type": "string", "nullable": true, "maxLength": 100, "pattern": "[\\w\\W\\s]*", "description": "Additional information regarding the frequency.\n", "example": "Recently switched from weekly to monthly." }, "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The reported revenue of the business.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `informed_revenue` field is available.\n", "example": 45391.89 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `informed_revenue` field is available.\n", "example": "BRL" }, "year": { "type": "integer", "format": "int32", "minimum": 1700, "maximum": 2090, "description": "The year when revenue was last declared.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `informed_revenue` field is available.\n", "example": 2022 } } }, "OwnerBusinessPatrimony": { "type": "object", "nullable": true, "required": [ "amount", "currency", "date" ], "description": "Information regarding the individual's reported assets.", "properties": { "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The reported assets of the business.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `patrimony` field is available.\n", "example": 45391.89 }, "currency": { "type": "string", "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `patrimony` field is available.\n", "example": "BRL" }, "date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the reported assets applied, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `patrimony` field is available.\n", "example": "2022-12-12" } } }, "OwnerBusinessFinancialProfile": { "type": "object", "nullable": true, "required": [ "economic_activities", "informed_revenue", "patrimony" ], "description": "Information regarding the financial profile of the individual.", "properties": { "economic_activities": { "type": "array", "description": "Details regarding the reported economic activities of the business.", "items": { "$ref": "#/components/schemas/OwnerBusinessEconomicActivies" } }, "informed_revenue": { "$ref": "#/components/schemas/OwnerBusinessInformedRevenue" }, "patrimony": { "$ref": "#/components/schemas/OwnerBusinessPatrimony" } } }, "EnumOwnerBusinessProductType": { "type": "string", "nullable": true, "enum": [ "SAVINGS_ACCOUNT", "CHECKING_ACCOUNT", null ], "description": "The additional products the business has at the institution. We return one of the following values:\n\n - `SAVINGS_ACCOUNT`\n - `CHECKING_ACCOUNT`\n - `null`\n \n", "example": "SAVINGS_ACCOUNT" }, "OwnerBusinessProducts": { "type": "object", "nullable": true, "required": [ "type", "subtype", "agency", "clearing_code", "number", "check_digit" ], "description": "Details regarding any additional products that the individual has with the institution.", "properties": { "type": { "$ref": "#/components/schemas/EnumOwnerBusinessProductType" }, "subtype": { "type": "string", "description": "The subtype of the product that the business has at the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "CONJUNTA_SIMPLES" }, "agency": { "type": "string", "nullable": true, "maxLength": 4, "pattern": "^\\d{1,4}$", "description": "The branch code where the product was opened.\n", "example": "6272" }, "clearing_code": { "type": "string", "maxLength": 3, "pattern": "^\\d{3}$", "description": "The banking clearing code for the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "001" }, "number": { "type": "string", "maxLength": 20, "pattern": "^\\d{8,20}$", "description": "The account number of the product.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "24550245" }, "check_digit": { "type": "string", "maxLength": 2, "pattern": "^[\\w\\W\\s]{0,2}$", "description": "The check digit of the product's number.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network if the `products` field is available.\n", "example": "7" } } }, "OwnerBusinessFinancialRelation": { "type": "object", "nullable": true, "required": [ "start_date", "product_services", "procurators", "products" ], "description": "Details regarding any additional relationship the business has with the institution (for example, other accounts or products they have with the institution).", "properties": { "start_date": { "type": "string", "format": "date-time", "maxLength": 20, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\\d|2[0123]):(?:[012345]\\d):(?:[012345]\\d)Z$", "description": "The ISO-8601 timestamp when the financial relationship between the business and the institution started.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "2021-05-21T08:30:00Z" }, "product_services": { "type": "array", "minItems": 1, "description": "A list of products that the business has with the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "type": "string", "description": "The name of the product, according to the institution.\n", "example": "CONTA_DEPOSITO_A_VISTA" } }, "procurators": { "type": "array", "description": "Information regarding any individuals or companies that can act on behalf of the owner.", "items": { "$ref": "#/components/schemas/OwnerProcurators" } }, "products": { "type": "array", "description": "Details regarding any additional products that the business has with the institution.", "items": { "$ref": "#/components/schemas/OwnerBusinessProducts" } } } }, "OwnerBusinessOpenFinanceBrazil": { "type": "object", "title": "Owner Business (OFDA Brazil)", "x-tags": [ "Owners" ], "required": [ "id", "link", "internal_identification", "collected_at", "created_at", "company_name", "trade_name", "incorporation_date", "companies_id", "document_id", "additional_documents", "email", "emails", "address", "addresses", "phone_number", "phone_numbers", "parties", "financial_profile", "financial_relation" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "internal_identification": { "type": "string", "nullable": true, "description": "The institution's internal identifier for the owner.", "example": "7e5838e4" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "company_name": { "type": "string", "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The full (official) name of the business, as provided by the institution.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "Wayne Enterprises" }, "trade_name": { "type": "string", "nullable": true, "maxLength": 128, "pattern": "^[\\w\\W]{0,128}$", "description": "The trade name of the business.\n", "example": "WayneCorp" }, "incorporation_date": { "type": "string", "format": "date", "maxLength": 10, "pattern": "^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$", "description": "The date that the business was incorporated, in `YYYY-MM-DD` format.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "example": "1988-07-15" }, "companies_id": { "type": "array", "minItems": 1, "description": "The institutions responsible for the creation and verification of the owner.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "type": "string", "maxLength": 14, "pattern": "^\\d{14}$", "description": "The institutions responsible for the creation and verification of the owner.\n", "example": "01773247000103" } }, "document_id": { "$ref": "#/components/schemas/OwnerDocumentIdOpenFinanceBrazil" }, "additional_documents": { "type": "array", "minItems": 1, "description": "Detailed information regarding additional documents provided to prove the business's ID.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/OwnerBusinessDocumentIds" } }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 256, "description": "The account owner's registered email address.", "example": "johndoe@belvo.com" }, "emails": { "type": "array", "minItems": 0, "description": "Additional list of emails the owner provided.", "items": { "$ref": "#/components/schemas/OwnerEmails" } }, "address": { "type": "string", "nullable": true, "description": "The accounts owners registered address.", "example": "Carrer de la Llacuna, 162, 08018 Barcelona" }, "addresses": { "type": "array", "minItems": 1, "description": "Detailed information regarding the owner's addresses.", "items": { "$ref": "#/components/schemas/OwnerAddresses" } }, "phone_number": { "type": "string", "nullable": true, "description": "The account owner's registered phone number.", "example": "+52-XXX-XXX-XXXX" }, "phone_numbers": { "type": "array", "minItems": 0, "description": "Detailed information regarding the owner's `phone_number`s.", "items": { "$ref": "#/components/schemas/OwnerPhoneNumbers" } }, "parties": { "type": "array", "minItems": 1, "description": "Detailed information regarding the parties allowed to act on the owner's behalf.\n\n> **Non-nullable:** A value must be returned by Brazil's open finance network.\n", "items": { "$ref": "#/components/schemas/OwnerParties" } }, "financial_profile": { "$ref": "#/components/schemas/OwnerBusinessFinancialProfile" }, "financial_relation": { "$ref": "#/components/schemas/OwnerBusinessFinancialRelation" } } }, "OwnerDocumentId": { "type": "object", "nullable": true, "required": [ "document_type", "document_number" ], "description": "Information regarding the identification document the owner provided to the bank.", "properties": { "document_type": { "type": "string", "nullable": true, "description": "The type of document the owner provided to the institution to open the account. Common document types are:\n\n🇧🇷 Brazil\n- `CPF` (*Cadastro de Pessoas Físicas*)\n- `CNPJ`(*Cadastro Nacional de Pessoas Jurídicas*)\n\n🇨🇴 Colombia\n- `CC`(*Cédula de Ciudadanía*)\n- `NIT` (*Número de Identificación Tributaria*)\n\n🇲🇽 Mexico\n- `CURP` (*Clave Única de Registro de Población*)\n- `NSS` (*Número de Seguridad Social*)\n- `RFC` (*Registro Federal de Contribuyentes*)\n", "example": "CPF" }, "document_number": { "type": "string", "nullable": true, "description": "The document's identification number.", "example": "235578435-S" } } }, "Owner": { "type": "object", "title": "Owner Standard (Multi-Region)", "x-tags": [ "Owners" ], "required": [ "id", "link", "internal_identification", "display_name", "email", "phone_number", "address", "collected_at" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "internal_identification": { "type": "string", "nullable": true, "description": "The institution's internal identifier for the owner.", "example": "7e5838e4" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "display_name": { "type": "string", "nullable": true, "maxLength": 128, "description": "The full name of the owner, as provided by the bank.", "example": "John Doe" }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 256, "description": "The account owner's registered email address.", "example": "johndoe@belvo.com" }, "phone_number": { "type": "string", "nullable": true, "description": "The account owner's registered phone number.", "example": "+52-XXX-XXX-XXXX" }, "address": { "type": "string", "nullable": true, "description": "The accounts owners registered address.", "example": "Carrer de la Llacuna, 162, 08018 Barcelona" }, "document_id": { "$ref": "#/components/schemas/OwnerDocumentId" }, "business_name": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\n\n*The name of the business.*\n", "example": null }, "first_name": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\n\n*The first name of the account owner.*\n", "example": null }, "last_name": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\n\n*The last name of the account owner.*\n", "example": null }, "second_last_name": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\n\n*The second last name of the account owner.*\n", "example": null } } }, "InvestmentBalance": { "type": "object", "title": "Investment Instrument Balance", "description": "The balance of the investment instrument, as of the `reference_date`.\n", "properties": { "reference_date": { "type": "string", "format": "date-time", "description": "The date and time that the balance was calculated for the investment instrument, in `YYYY-MM-DDTHH:MM:SSZ` format.\n", "example": "2022-07-21T17:32:00Z" }, "gross_value": { "type": "number", "format": "float", "description": "The gross value of the investment instrument.", "example": 1000 }, "blocked_amount": { "type": "number", "format": "float", "description": "The amount of the investment instrument that is blocked or unavailable for transactions.", "example": 100 }, "quantity": { "type": "number", "format": "float", "pattern": "‘^-?\\d{1,15}\\.\\d{2,8}$’", "description": "The number of units, quotas, or assets held on the reference date.", "example": 100 }, "gross_unit_price": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^-?\\d{1,15}\\.\\d{2,8}$’", "description": "The current gross unit value of the investment on the reference date", "example": 10 }, "net_value": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^-?\\d{1,15}\\.\\d{2,8}$’", "description": "The net value of the investment after deductions for taxes, fees, and other charges, as of the reference date.", "example": 900 }, "withheld_amount": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1,15}\\.\\d{2,4}$’", "description": "The amount of the investment instrument that has been withheld or deducted from the net value.", "example": 10 }, "transaction_fee": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1,15}\\.\\d{2,4}$’", "description": "The fees and taxes charged for the transaction.", "example": 5 }, "purchase_unit_price": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1,15}\\.\\d{2,4}$’", "description": "The unit price at the time of purchase for the security or asset.", "example": 10 }, "pre_fixed_rate": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1}\\.\\d{6}$’", "description": "The pre-fixed remuneration rate for the income product.", "example": 0.05 }, "post_fixed_rate": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1}\\.\\d{6}$’", "description": "The percentage of the post-fixed indexer for the income product.", "example": 0.05 }, "penalty_fee": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1,15}\\.\\d{2,4}$’", "description": "The penalty (fine) for delays in payments, as defined in the contract.", "example": 10 }, "late_payment_fee": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1,15}\\.\\d{2,4}$’", "description": "The interest charged for delayed payments.", "example": 10 }, "closing_price": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^-?\\d{1,15}\\.\\d{2,8}$’", "description": "The closing price of the investment on the reference date.", "example": 10 }, "unit_price_factor": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1,15}\\.\\d{2,4}$’", "description": "The factor used to calculate the unit price.", "example": 1 } } }, "Remuneration": { "type": "object", "description": "The remuneration details of the investment instrument.\n", "properties": { "pre_fixed_rate": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1}\\.\\d{6}$’", "description": "The fixed interest rate defined at issuance, expressed as a decimal (for example `0.150000` represents 15%).", "example": 0.05 }, "post_fixed_rate": { "type": "number", "format": "float", "nullable": true, "pattern": "‘^\\d{1}\\.\\d{6}$’", "description": "The post-fixed interest rate defined at issuance, expressed as a decimal (for example `0.150000` represents 15%).", "example": 0.05 }, "rate_type": { "type": "string", "nullable": true, "maxLength": 30, "pattern": "[\\w\\W-]*", "description": "The type of remuneration rate applied to the financial instrument. Can be either:\n - `LINEAR`\n - `EXPONENCIAL`\n", "example": "LINEAR" }, "rate_periodicity": { "type": "string", "nullable": true, "description": "The frequency that the remuneration rate is applied to the financial instrument. Can be either:\n - `DIARIO`\n - `MENSAL`\n - `ANUAL`\n - `SEMESTRAL`\n", "example": "MENSAL" }, "calculation_base": { "type": "string", "nullable": true, "maxLength": 30, "pattern": "[\\w\\W-]*", "description": "Indicates whether the remuneration or interest calculation is based on business days (*dias úteis*) or calendar days (*dias corridos*).\n- `DIAS_UTEIS`\n - `DIAS_CORRIDOS`\n", "example": "DIAS_CORRIDOS" }, "indexer": { "type": "string", "nullable": true, "maxLength": 30, "pattern": "[\\w\\W-]*", "description": "The index used as a reference to calculate the profitability or returns of the financial instrument. Can be one either:\n - `CDI` \n - `DI` \n - `TR` \n - `IPCA` \n - `IGP_M` \n - `IGP_DI` \n - `INPC` \n - `BCP` \n - `TLC` \n - `SELIC` \n - `PRE_FIXADO` \n - `OUTROS`\n", "example": "CDI" }, "indexer_additional_info": { "type": "string", "nullable": true, "maxLength": 50, "pattern": "[\\w\\W-]*", "description": "Additional information regarding the `indexer` rate. Required when `indexer` is set to `OUTROS`. \n", "example": "IPCA + 5%" } } }, "ClassificationDetails": { "type": "object", "nullable": true, "description": "The classification details of the investment instrument.\n\n> 🚧 Only applicable for `INVESTMENT_FUND` investments.\n>\n> This object is only applicable for `INVESTMENT_FUND` investments. For all other investment types, this object will be `null`.\n", "properties": { "category": { "type": "string", "nullable": true, "maxLength": 11, "description": "The investment fund's category, as defined by ANBIMA's classification standards. Can be one of:\n - `RENDA_FIXA`\n - `ACOES`\n - `MULTIMERCADO`\n - `CAMBIAL`\n", "example": "ACOES" }, "class": { "type": "string", "nullable": true, "maxLength": 70, "pattern": "[\\w\\W\\s]*", "description": "The class within the investment fund's category, as defined by ANBIMA's classification standards.\n", "example": "Ações Livre" }, "subclass": { "type": "string", "nullable": true, "maxLength": 70, "pattern": "[\\w\\W\\s]*", "description": "The subclass of the investment fund, as defined by ANBIMA's classification standards.\n", "example": "Ações Livre" } } }, "VoucherPaymentDetails": { "type": "object", "title": "Voucher Payment Details", "description": "The voucher payment (also known as coupon payments) details of the investment instrument.\n\n> 🚧 Only applicable for `FIXED_INCOME_CREDIT` and `TREASURY_BOND` investments.\n>\n> This object is only applicable for `FIXED_INCOME_CREDIT` and `TREASURY_BOND` investments. For all other investment types, this object will be `null`.\n", "properties": { "is_voucher_payment": { "type": "boolean", "description": "Indicates whether the financial instrument pays periodic interest (voucher payments).\n", "example": true }, "periodicity": { "type": "string", "nullable": true, "description": "The frequency that the voucher payments are made. Required when `is_voucher_payment` is set to `true`. Can be one of:\n - `MENSAL` \n - `TRIMESTRAL` \n - `SEMESTRAL` \n - `ANUAL` \n - `IRREGULAR` \n - `OUTROS`\n", "example": "MENSAL" }, "periodicity_additional_info": { "type": "string", "nullable": true, "maxLength": 50, "pattern": "[\\w\\W\\s]*", "description": "Additional information about the voucher payment periodicity. Required when `periodicity` is set to `OUTROS`.\n", "example": "30/360" } } }, "DebtorDetails": { "type": "object", "nullable": true, "title": "Debtor Details", "description": "The debtor details of the investment instrument.\n\n> 🚧 Only applicable for `FIXED_INCOME_CREDIT` investments.\n>\n> This object is only applicable for `FIXED_INCOME_CREDIT` investments. For all other investment types, this object will be `null`.\n", "properties": { "name": { "type": "string", "maxLength": 70, "pattern": "[\\w\\W\\s]*", "description": "The name of the debtor.\n", "example": "Roberto Marino" }, "id_document_number": { "type": "string", "maxLength": 14, "pattern": "‘^\\d{14}$’", "description": "The debtor's identification document number (CNPJ).\n", "example": 12345678901 } } }, "InvestmentBrazil": { "type": "object", "title": "Investments Object (Brazil)", "x-tags": [ "Investments Brazil" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier created by Belvo used to reference the current investment.", "example": "5359ddc5-31fc-4346-934b-cc24630a8d06" }, "type": { "type": "string", "description": "The type of investment: Can be either\n\n - `FIXED_INCOME_BANKING` (*Renda Fixa Bancária*)\n - `FIXED_INCOME_CREDIT` (*Renda Fixa Crédito*)\n - `VARIABLE_INCOME` (*Renda Variável*)\n - `TREASURY_BOND` (*Tesouro Direto*)\n - `INVESTMENT_FUND` (*Fundos de Investimento*)\n", "example": "FIXED_INCOME_BANKING" }, "issuer_id_number": { "type": "string", "nullable": true, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The CNPJ number of the issuing institution. For Investment Funds, this is the CNPJ of the fund.\n\n> 🚧 Not applicable for `TREASURY_BOND` investments.\n", "example": "10187609364567" }, "isin_number": { "type": "string", "nullable": true, "maxLength": 12, "pattern": "‘^[A-Z]{2}([A-Z0-9]){9}\\d{1}$’", "description": "The ISO-6166 International Securities Identification Number (ISIN) for the financial instrument.\n", "example": "BRCST4CTF001" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) of the investment. For example, `BRL` for Brazilian Real.\n", "example": "BRL" }, "product_name": { "type": "string", "maxLength": 250, "description": "The name of the investment product.\n\n- For `FIXED_INCOME_BANKING`, this can be: CDB, RDB, LCI, or LCA.\n- For `FIXED_INCOME_CREDIT`, this can be: DEBENTURES, CRI, or CRA.\n- For `INVESTMENT_FUND`, this will be the name of the fund. For example: CONSTELLATION MASTER FIA\n- For `TREASURY_BOND`, this will be the name of the bond. For example: Tesouro Selic 2025.\n- For `VARIABLE_INCOME_INCOME`, this will be the name of the stock. For example AAPL.\n", "example": "CONSTELLATION MASTER FIA" }, "is_tax_exempt": { "type": "boolean", "description": "Indicates if the investment is exempt from taxes.\n\n> 🚧 Only applicable for `FIXED_INCOME_CREDIT` investments.\n", "example": false }, "clearing_code": { "type": "string", "nullable": true, "maxLength": 30, "pattern": "[\\w\\W-]*", "description": "The clearing code of the investment.\n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING` and `FIXED_INCOME_CREDIT`.\n", "example": "CDB421GPXXX" }, "due_date": { "type": "string", "format": "date", "nullable": true, "description": "The maturity date of the financial instrument. \n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING`, `FIXED_INCOME_CREDIT`, and `TREASURY_BOND` investments.\n", "example": "2022-01-01" }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "The date the financial instrument was issued.\n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING` and `FIXED_INCOME_CREDIT`.\n", "example": "2021-01-01" }, "purchase_date": { "type": "string", "format": "date", "nullable": true, "description": "The date the financial instrument was purchased.\n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING`, `FIXED_INCOME_CREDIT`, and `TREASURY_BOND` investments.\n", "example": "2021-01-01" }, "grace_period_date": { "type": "string", "format": "date", "nullable": true, "description": "The grace period date of the financial instrument.\n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING` and `FIXED_INCOME_CREDIT`.\n", "example": "2021-01-01" }, "issue_unit_price": { "type": "number", "format": "float", "nullable": true, "description": "The unit price of the financial instrument at the time of issuance.\n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING` and `FIXED_INCOME_CREDIT`.\n", "example": 1000 }, "balance": { "$ref": "#/components/schemas/InvestmentBalance" }, "remuneration": { "$ref": "#/components/schemas/Remuneration" }, "classification_details": { "$ref": "#/components/schemas/ClassificationDetails" }, "voucher_payment_details": { "$ref": "#/components/schemas/VoucherPaymentDetails" }, "debtor_details": { "$ref": "#/components/schemas/DebtorDetails" } } }, "BrokerNote": { "type": "object", "title": "Broker Note", "nullable": true, "required": [ "broker_note_number", "gross_value", "brokerage_fee", "clearing_settlement_fee", "clearing_registration_fee", "stock_exchange_asset_trade_notice_fee", "stock_exchange_fee", "clearing_custody_fee", "taxes", "income_tax", "net_value" ], "description": "Details regarding the broker note that is associated with this transaction. This object is only returned for transactions that are associated with a `VARIABLE_INCOME` investment type.\n\n> 📘 Info\n>\n> A broker note (*nota de corretagem*) is an official document issued by a brokerage detailing the transactions made by an investor on a given day. It includes information on the gross value of all purchases and sales, brokerage fees, clearing and settlement fees, clearing and registration fees, stock exchange asset trade notice fees, stock exchange fees, clearing custody fees, taxes, and income tax withheld at source.\n", "properties": { "broker_note_number": { "type": "string", "pattern": "‘^\\d{1,16}$’", "minLength": 1, "maxLength": 16, "description": "The broker note number.", "example": "1854009930314350" }, "gross_value": { "type": "number", "format": "float", "description": "The gross value of all purchases and sales for the day.", "example": 1000 }, "brokerage_fee": { "type": "number", "format": "float", "description": "The total brokerage fee charged for the day.", "example": 10 }, "clearing_settlement_fee": { "type": "number", "format": "float", "description": "The fee charged for clearing and settlement in custody.", "example": 2.5 }, "clearing_registration_fee": { "type": "number", "format": "float", "description": "The fee charged for clearing and registration in custody.", "example": 1 }, "stock_exchange_asset_trade_notice_fee": { "type": "number", "format": "float", "description": "The fee charged by the stock exchange for asset trade notifications.", "example": 0.5 }, "stock_exchange_fee": { "type": "number", "format": "float", "description": "The fee charged by the stock exchange for registry services.", "example": 3 }, "clearing_custody_fee": { "type": "number", "format": "float", "description": "The fee charged by financial institutions for custody services.", "example": 1.5 }, "taxes": { "type": "number", "format": "float", "description": "The total amount taxes charged on the transaction for the day, excluding income tax withheld at source.", "example": 10 }, "income_tax": { "type": "number", "format": "float", "description": "The total amount of income tax withheld at the source for the day.", "example": 5 }, "net_value": { "type": "number", "format": "float", "description": "The net value of the broker note after deducting expenses for brokerage fees, clearing settlement fees, registration fees, ANA fees, emoluments, custody fees, taxes, and IRRF", "example": 980 } } }, "InvestmentTransactionBrazil": { "type": "object", "description": "Details regarding the investment transaction.", "title": "Investment Transaction Object (Brazil)", "x-tags": [ "Investment Transactions Brazil" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "investment": { "$ref": "#/components/schemas/InvestmentBrazil" }, "internal_identification": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$", "minLength": 1, "maxLength": 100, "description": "The institution's internal identification of the investment transaction.", "example": "ABCD2126019929279212650822221989319253344" }, "value_date": { "type": "string", "format": "date", "description": "The date on which the transaction was settled, in `YYYY-MM-DD` format.\n\n> 📘 `VARIABLE_INCOME`\n>\n> For `VARIABLE_INCOME` investments, you will only receive transactions up until the last trading date. For example, if today is 19.11.2024, you will only receive transactions up till 18.11.2024. \n\n> 📘 `INVESTMENT_FUND` \n>\n> For `INVESTMENT_FUND` investments, this is the date when the transaction (purchase or redemption) is officially processed into fund shares or quotas. For purchases, this is the date the investor’s money is applied to acquire fund shares. For redemptions, this is the date when the fund shares are officially converted back into cash.\n", "example": "2024-11-18" }, "gross_value": { "type": "number", "format": "float", "pattern": "‘^-?\\d{1,15}\\.\\d{2,4}$’", "description": "The gross value of the transaction.\n\n> 🚧 Not applicable for `VARIABLE_INCOME` investments.\n", "example": 60 }, "net_value": { "type": "number", "format": "float", "pattern": "‘^-?\\d{1,15}\\.\\d{2,4}$’", "description": "The net value of the transaction.\n\n> 🚧 Not applicable for `VARIABLE_INCOME` investments.\n", "example": 60 }, "value": { "type": "number", "format": "float", "description": "The value of the transaction.\n\nFor **`VARIABLE_INCOME` investments**, this is the value of the trade executed by the client. If the client buys or sells stocks, this field indicates the total value of the trade (for example, the price per share × quantity).\n\nFor **`INVESTMENT_FUND` investments**, this is the value requested by the client for a fund transaction.\n\n> 🚧 Only applicable for `VARIABLE_INCOME` and `INVESTMENT_FUND` investments.\n", "example": 60 }, "unit_price": { "type": "number", "format": "float", "description": "The price for an individual unit or quota.\n", "example": 3 }, "price_factor": { "type": "number", "format": "float", "description": "The number of units (shares) considered when calculating the price per share or unit for a transaction.\n\n> 🚧 Only applicable for `VARIABLE_INCOME` investments.\n", "example": 1 }, "transaction_tax": { "type": "number", "format": "float", "description": "The Financial Transaction Tax (*Imposto sobre Operações Financeiras (IOF)*) applied or withheld during the transaction.\n\n> 🚧 Not applicable for `VARIABLE_INCOME` investments.\n", "example": 0 }, "income_tax": { "type": "number", "format": "float", "description": "The Income Tax (*Imposto de Renda (IR)*) applied or withheld during the transaction.\n\n> 🚧 Not applicable for `VARIABLE_INCOME` investments.\n", "example": 0 }, "quantity": { "type": "number", "format": "float", "description": "The number of units, quotas, or assets involved in a transaction.\n", "example": 20 }, "type": { "type": "string", "enum": [ "INFLOW", "OUTFLOW", "null" ], "description": "The transaction type (`INFLOW` or `OUTFLOW`) from the investment perspective. \n", "example": "INFLOW" }, "subtype": { "type": "string", "description": "The transaction subtype.\n\n- For `FIXED_INCOME_BANKING`: APLICACAO, RESGATE, CANCELAMENTO, VENCIMENTO, PAGAMENTO_JUROS, AMORTIZACAO, TRANSFERENCIA_TITULARIDADE, TRANSFERENCIA_CUSTODIA, OUTROS.\n- For `FIXED_INCOME_CREDIT`: COMPRA, VENDA, CANCELAMENTO, VENCIMENTO, PAGAMENTO_JUROS, AMORTIZACAO, PRÊMIO, TRANSFERENCIA_TITULARIDADE, TRANSFERENCIA_CUSTODIA, MULTA, MORA, OUTROS.\n- For `VARIABLE_INCOME`: COMPRA, VENDA, DIVIDENDOS, JCP, ALUGUEIS, TRANSFERENCIA_TITULARIDADE, OUTROS.\n- For `INVESTMENT_FUND`: AMORTIZACAO, TRANSFERENCIA_DE_COTAS, APLICACAO, RESGATE, COME_COTAS, OUTROS.\n- For `TREASURY_BOND`: COMPRA, VENDA, CANCELAMENTO, VENCIMENTO, PAGAMENTO_JUROS, AMORTIZACAO, TRANSFERENCIA_TITULARIDADE, TRANSFERENCIA_CUSTODIA, OUTROS.\n", "example": null }, "subtype_additional_info": { "type": "string", "pattern": "‘[\\w\\W\\s]*’", "maxLength": 100, "description": "Additional information about the transaction subtype. This field is mandatory when the subtype is `OUTROS`.\n", "example": null }, "indexer_percentage": { "type": "number", "format": "float", "description": "The maximum percentage of the indexer for the contract (Bancaria) or transaction (Credito).\n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING` and `FIXED_INCOME_CREDIT` investments.\n", "example": 0 }, "rate": { "type": "number", "format": "float", "description": "The remuneration rate applied to the transaction. \n\n> 🚧 Only applicable for `FIXED_INCOME_BANKING`, `FIXED_INCOME_CREDIT`, and `TREASURY_BOND` investments.\n", "example": 0 }, "exit_fee": { "type": "number", "format": "float", "description": "The exit fee applied to the Investment Fund (Fundos de Investimento) transaction. This fee is charged when a client redeems or exits the fund.\n\n> 🚧 Only applicable for `INVESTMENT_FUND` investments.\n", "example": 0 }, "broker_note_details": { "$ref": "#/components/schemas/BrokerNote" } } }, "EnumEmploymentRecordStatus": { "type": "string", "enum": [ "EMPLOYED", "RETIRED", "UNEMPLOYED", "null" ], "description": "Indicates the employment status of the individual. We return one of the following responses:\n \n - `EMPLOYED`\n - `RETIRED`\n - `UNEMPLOYED`\n - `null`\n", "example": "EMPLOYED" }, "EmploymentRecordEntitlement": { "type": "object", "description": "Details regarding the benefits the individual is entitled to.", "properties": { "entitled_to_health_insurance": { "type": "boolean", "description": "Indicates whether or not the individual is entitled to health insurance.\n", "example": true }, "entitled_to_company_benefits": { "type": "boolean", "description": "Indicates whether or not the individual is entitled to company benefits.\n", "example": true }, "valid_until": { "type": "string", "nullable": true, "format": "date", "description": "Date until when the individual is covered by health insurance and/or company benefits. If `null` the employee is currently working and no end date is required.\n", "example": null }, "status": { "$ref": "#/components/schemas/EnumEmploymentRecordStatus" } } }, "EnumEmploymentRecordDocumentType": { "type": "string", "nullable": true, "enum": [ "NSS", "CURP", "RFC" ], "description": "The type of document related to the individual. We return one of the following values:\n\n - `NSS`\n - `CURP`\n - `RFC`\n \n", "example": "NSS" }, "EmploymentRecordDocumentId": { "type": "object", "description": "Details regarding the individual's ID documents.", "properties": { "document_type": { "$ref": "#/components/schemas/EnumEmploymentRecordDocumentType" }, "document_number": { "type": "string", "nullable": true, "description": "The ID document's number (as a string).\n", "example": "10277663582" } } }, "EmploymentRecordPersonalData": { "type": "object", "description": "Details regarding the personal information of the individual.", "properties": { "official_name": { "type": "string", "nullable": true, "description": "The legal name of the individual.\n", "example": "Bruce Banner del Torro" }, "first_name": { "type": "string", "nullable": true, "description": "The first name of the individual.\n", "example": "Bruce" }, "last_name": { "type": "string", "nullable": true, "description": "The last name of the individual.\n", "example": "Banner del Torro" }, "birth_date": { "type": "string", "nullable": true, "format": "date", "description": "The date of birth of the individual, in `YYYY-MM-DD` format.\n", "example": "2022-02-09" }, "entitlements": { "$ref": "#/components/schemas/EmploymentRecordEntitlement" }, "document_ids": { "type": "array", "description": "Details regarding the individual's ID documents.", "items": { "$ref": "#/components/schemas/EmploymentRecordDocumentId" } }, "email": { "type": "string", "nullable": true, "deprecated": true, "description": "The email address of the individual.\n", "example": "bruce.banner@avengers.com" } } }, "EmploymentRecordSocialSecuritySummary": { "type": "object", "nullable": true, "description": "Details regarding the individual's social security contributions, according to the IMSS.\n\n>**Note**: For ISSSTE Mexico, this value will return `null`.\n", "properties": { "weeks_redeemed": { "type": "integer", "nullable": true, "format": "int32", "description": "Number of weeks the individual needed to take out of their pension.\n", "example": 0 }, "weeks_reinstated": { "type": "integer", "nullable": true, "format": "int32", "description": "Number of weeks the individual has paid back into their pension (*AFORE*), after having redeemed them previously.\n", "example": 0 }, "weeks_contributed": { "type": "integer", "nullable": true, "format": "int32", "description": "Number of weeks the individual has contributed to their social security, based on the number of weeks the individual has worked according to IMSS.\n", "example": 188 } } }, "EnumEmploymentRecordStatusUpdateEvents": { "type": "string", "nullable": true, "enum": [ "DISMISSED_RESIGNED", "SALARY_MODIFICATION", "HIRED", "VOLUNTARY_CONTRIBUTION", "ABSENCE", "SICK_LEAVE", "NORMAL", "BDUTA_CERTIFICATE", "DYE_CERTIFICATE" ], "description": "For IMSS Mexico, this is the event that caused the change in employment status or salary. We return one of the following values:\n \n - `DISMISSED_RESIGNED`: The employee was either dismissed or resigned.\n - `SALARY_MODIFICATION`: The employee received a salary modification (increase or decrease).\n - `HIRED`: The employee was hired.\n - `VOLUNTARY_CONTRIBUTION`: The employee made a voluntary contribution to IMSS.\n - `ABSENCE`: The employee was on absent (such as on vacation).\n - `SICK_LEAVE`: The employee was on sick leave.\n\nFor ISSSTE Mexico, this is the information source regarding the change in employment status or salary. We return one of the following values:\n\n - `NORMAL`: Indicates that the information was received from the **Instituto de Seguridad y Servicios Sociales de los Trabajadores del Estado (ISSSTE)**.\n - `BDUTA_CERTIFICATE`: Indicates that the information was received from the central database, **Base de Datos Única de Trabajadores Activos (BDUTA)**.\n - `DYE_CERTIFICATE`: Indicates that the information was received from an affiliate institution, **Dependencia y Entidad (DYE)**.\n \n", "example": "HIRED" }, "EmploymentRecordEmploymentStatusUpdates": { "type": "object", "description": "Details regarding any employment changes of the individual.", "nullable": true, "properties": { "event": { "$ref": "#/components/schemas/EnumEmploymentRecordStatusUpdateEvents" }, "base_salary": { "type": "number", "format": "float", "description": "The base salary of the individual, current as of the `update_date`.\n\n - For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year.\n - For ISSSTE Mexico, this value is calculated excluding the individual's perks.\n", "example": 1033.09 }, "update_date": { "type": "string", "format": "date", "description": "The date that the employment event occurred, in `YYYY-MM-DD` format.\n", "example": "2021-09-01" } } }, "EmploymentRecordDetail": { "type": "object", "description": "Details regarding the individual's employment history.", "properties": { "collected_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp when the data point was collected.", "example": "2020-04-23T21:32:55.336854+00:00" }, "employer": { "type": "string", "description": "The official name of the employer.\n\n>**Note**: For ISSSTE Mexico, this is the official name of the entity along with the entity that is responsible for managing the employee's information, separated by a semicolon (`;`). For example: SECRETARIA DE EDUCACION PUBLICA (SEP);SECRETARIA DE EDUCACION PUBLICA (SEP).\n", "example": "Batman Enterprises CDMX" }, "employer_id": { "type": "string", "nullable": true, "description": "The official ID of the employer, according to the country.\n\n>**Note**: For ISSSTE Mexico, this value will return `null`.\n", "example": "780-BAT-88769-CDMX" }, "start_date": { "type": "string", "format": "date", "description": "Date when employment started, in `YYYY-MM-DD` format.\n", "example": "2019-10-10" }, "end_date": { "type": "string", "nullable": true, "format": "date", "description": "Date when employment finished, in `YYYY-MM-DD` format.\n\n>**Note**: This field will return `null` for the user's current employment.\n", "example": "2019-12-31" }, "weeks_employed": { "type": "integer", "format": "int32", "description": "Number of weeks that the individual was employed.\n", "example": 12 }, "state": { "type": "string", "nullable": true, "description": "In what geographical state the individual was employed, according to the country.\n\n>**Note**: For ISSSTE Mexico, this value will return `null`.\n", "example": "DISTRITO FEDERAL" }, "most_recent_base_salary": { "type": "number", "format": "float", "description": "The most recent base salary the individual earned.\n\n- For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year.\n- For ISSSTE Mexico, this value is calculated dividing `monthly_salary` by 30 (days), and excludes the individual's perks.\n", "example": 762.54 }, "monthly_salary": { "type": "number", "format": "float", "description": "The monthly salary of the individual, including any additional perks.\n\n- For IMSS Mexico, this value is calculated including the perks that the individual is entitled to throughout the year.\n- For ISSSTE Mexico, this value is calculated excluding perks.\n", "example": 23193.925 }, "currency": { "type": "string", "description": "The three-letter currency code in which the salary is paid.\n", "example": "MXN" }, "employment_status_updates": { "type": "array", "nullable": true, "description": "Details regarding any employment changes of the individual.", "items": { "$ref": "#/components/schemas/EmploymentRecordEmploymentStatusUpdates" } } } }, "EmploymentRecordScore": { "type": "object", "description": "The employment score provides an insight into employability and income generation potential in a given period.", "properties": { "score": { "type": "integer", "nullable": true, "minimum": 300, "maximum": 900, "description": "A score between 300 and 900 that provides an insight into employability and income generation potential.\n\n- A low score (closer to 300) could indicate lower predicted employability and income generation potential, suggesting potential challenges in securing employment or achieving higher income levels in the future.\n- A high score (closer to 900) could suggest a greater likelihood of securing employment and generating higher income levels.\n\nThe score can return `null` if the individual has no employment history.\n", "example": 612 }, "period": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The number of months (in the future) that the score is calculated for.\n\nFor example, a period of `6` indicates that the score is calculated for the next `6` months.\n\n> **Note**: At present Belvo calculates the score for 3, 6, and 12 months.\n", "example": 6 }, "version": { "type": "string", "description": "The version of our employment score model used to perform the calculation.", "example": "1.0.0" } } }, "EmploymentRecordSalaryEstimation": { "type": "object", "title": "Employment Record Salary Estimation Object (Mexico)", "required": [ "currency", "base_salary_estimate", "employment_status_estimate" ], "nullable": true, "description": "Provides a modeled estimation of the user's current base salary and employment status. \n\n> **Note**: This field is only available for links created with Mexico's IMSS. For other institutions (such as ISSSTE), this field will return `null`.\n", "properties": { "employment_status_estimate": { "type": "string", "nullable": true, "description": "Current employment status estimated using an employment record with a past report date. Returns `\"EMPLOYED\"` (if the `base_salary_estimate` is greater than 0) or `\"UNEMPLOYED\"`.", "example": "EMPLOYED" }, "base_salary_estimate": { "type": "number", "format": "float", "nullable": true, "description": "Current base salary (daily amount) estimated using an employment record with a past report date.", "example": 1000 }, "currency": { "type": "string", "description": "The three-letter currency code (ISO-4217). For example, `\"MXN\"`.", "example": "MXN" } } }, "EmploymentRecordFile": { "type": "object", "description": "Additional PDF binary files relating to the individual's employment.", "properties": { "type": { "type": "string", "description": "The title of the document.\n", "example": "ReporteSemanasCotizadas_190123" }, "value": { "type": "string", "nullable": true, "description": "The PDF binary of the file (as a string).\n\n> **Note**: In our sandbox environment, this field will return `null`.\n", "example": "=PDF_BINARY=" } } }, "EmploymentRecord": { "type": "object", "description": "Employment record response payload", "title": "Employment Record Object (Mexico)", "x-tags": [ "Employment Records Mexico" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "report_date": { "type": "string", "format": "date", "description": "The date when the employment record report was generated, in `YYYY-MM-DD` format.", "example": "2023-01-19" }, "days_since_extraction": { "type": "integer", "description": "The number of days that have passed since the employment data was originally extracted from the institution.", "example": 42 }, "internal_identification": { "type": "string", "description": "Unique ID for user according to the institution. For IMSS and ISSSTE Mexico, this is the CURP.", "example": "BLPM951331IONVGR54" }, "personal_data": { "$ref": "#/components/schemas/EmploymentRecordPersonalData" }, "social_security_summary": { "$ref": "#/components/schemas/EmploymentRecordSocialSecuritySummary" }, "employment_records": { "type": "array", "description": "Details regarding the individual's employment history.", "items": { "$ref": "#/components/schemas/EmploymentRecordDetail" } }, "employment_scores": { "type": "array", "nullable": true, "description": "An array of `employment_record` scores. Each score provides an insight into employability and income generation potential in a given period.\n\n> **Note 1**: This field is only available for links created with Mexico's IMSS. For other institutions, this field will return `null`.\n\n> **Note 2**: This field will return `null` for employment records retrieved before 16-04-2024. For employment records generated before 16-04-2024, you'll need to make a new POST request to retrieve employment records to calculate the scores.\n", "items": { "$ref": "#/components/schemas/EmploymentRecordScore" }, "example": [ { "score": 722, "period": 3, "version": "1.0.0" }, { "score": 612, "period": 6, "version": "1.0.0" }, { "score": 570, "period": 12, "version": "1.0.0" } ] }, "salary_estimation": { "$ref": "#/components/schemas/EmploymentRecordSalaryEstimation" }, "files": { "type": "array", "nullable": true, "description": "Additional PDF binary files relating to the individual's employment.", "items": { "$ref": "#/components/schemas/EmploymentRecordFile" } } } }, "attach_pdf": { "type": "boolean", "default": false, "description": "When set to `true`, you will receive the PDF in binary format in the response.", "example": true }, "CurrentEmploymentDocumentId": { "type": "object", "description": "Details regarding the individual's ID documents.", "required": [ "document_type", "document_number" ], "properties": { "document_type": { "$ref": "#/components/schemas/EnumEmploymentRecordDocumentType" }, "document_number": { "type": "string", "nullable": true, "description": "The ID document's number (as a string).\n", "example": "10277663582" } } }, "CurrentEmploymentPersonalData": { "type": "object", "description": "Details regarding the personal information of the individual.", "required": [ "official_name", "first_name", "last_name", "birth_date", "document_ids" ], "properties": { "official_name": { "type": "string", "nullable": true, "description": "The legal name of the individual.\n", "example": "Bruce Banner del Torro" }, "first_name": { "type": "string", "nullable": true, "description": "The first name of the individual.\n", "example": "Bruce" }, "last_name": { "type": "string", "nullable": true, "description": "The last name of the individual.\n", "example": "Banner del Torro" }, "birth_date": { "type": "string", "nullable": true, "format": "date", "description": "The date of birth of the individual, in `YYYY-MM-DD` format.\n", "example": "1990-02-09" }, "document_ids": { "type": "array", "description": "Details regarding the individual's ID documents.", "items": { "$ref": "#/components/schemas/CurrentEmploymentDocumentId" } } } }, "CurrentEmploymentRecord": { "type": "object", "description": "Current employment record details", "required": [ "employer", "employer_id", "employer_rfc", "state", "days_employed", "base_salary", "monthly_salary" ], "properties": { "employer": { "type": "string", "description": "The official name of the employer.", "example": "Batman Enterprises CDMX" }, "employer_id": { "type": "string", "description": "The official ID of the employer, according to the country.", "example": "123456789010" }, "employer_rfc": { "type": "string", "description": "The employer's RFC (tax identification number).", "example": "RFC123456" }, "state": { "type": "string", "description": "The geographical state where the employment is located.", "example": "CDMX" }, "days_employed": { "type": "integer", "description": "The number of days the individual has been employed with this employer.", "example": 365 }, "base_salary": { "type": "number", "format": "float", "nullable": true, "description": "The base salary of the individual.", "example": 10000 }, "monthly_salary": { "type": "number", "format": "float", "nullable": true, "description": "The monthly salary of the individual, including any additional perks.", "example": 304166.67 } } }, "CurrentEmployment": { "type": "object", "description": "Current employment status response payload", "title": "Current Employment Object (Mexico)", "x-tags": [ "Current Employments Mexico" ], "required": [ "id", "link", "created_at", "collected_at", "month", "internal_identification", "personal_data", "status", "current_employment_records" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "month": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}$", "description": "The month for which the current employment status is reported, in `YYYY-MM` format. If `status` is `UNEMPLOYED`, this field is `null`.", "example": "2023-01" }, "internal_identification": { "type": "string", "nullable": true, "description": "Unique ID for user according to the institution. For IMSS and ISSSTE Mexico, this is the CURP. If `status` is `UNEMPLOYED`, this field is `null`.", "example": "BLPM230130IONVGR54" }, "personal_data": { "$ref": "#/components/schemas/CurrentEmploymentPersonalData" }, "status": { "type": "string", "enum": [ "EMPLOYED", "UNEMPLOYED" ], "description": "The current employment status of the individual.", "example": "EMPLOYED" }, "current_employment_records": { "type": "array", "minItems": 1, "nullable": true, "description": "Details regarding the individual's current employment. If `status` is `UNEMPLOYED`, this field is `null`.", "items": { "$ref": "#/components/schemas/CurrentEmploymentRecord" } } } }, "EmployerDataBrazil": { "type": "object", "description": "Details regarding the employer.", "additionalProperties": false, "required": [ "name", "code", "economic_activity" ], "properties": { "name": { "type": "string", "minLength": 5, "description": "The name of the employer.", "example": "Wayne Industries" }, "code": { "type": "string", "minLength": 8, "maxLength": 14, "description": "The institution's unique code for the employer.", "example": "49430669" }, "economic_activity": { "type": "string", "minLength": 4, "description": "The main economic activity the employer is involved in. For Brazil, this is the *Classificação Nacional de Atividades Econômicas* (CNAE) code.", "example": "6421-2 - BANCOS COMERCIAIS" } } }, "OccupationBrazil": { "type": "object", "description": "Details regarding the occupation the employee had at the employer.", "additionalProperties": false, "required": [ "start_date", "end_date", "description", "name", "locale" ], "properties": { "start_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The date that the employee started the position, in `YYYY-MM-DD` format.", "example": "2022-01-01" }, "end_date": { "type": "string", "format": "date", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The date that the employee stopped working in this position, in `YYYY-MM-DD` format. If `null`, this means that the employee is still holds this position.", "example": "2023-01-01" }, "description": { "type": "string", "minLength": 5, "description": "The position the employee held. For Brazil, this description must be according to the Ministry of Labour and listed in the *Classificação Brasileira de Ocupações* (CBO).", "example": "ANALISTA DE PRODUTOS BANCARIOS" }, "name": { "type": "string", "minLength": 5, "description": "The employees occupation, as provided by the employer.", "example": "ANALISTA DE PRODUTOS BANCARIOS - 2525-40" }, "locale": { "type": "string", "description": "Where the employee fufilled their duties. For Brazil, this can be either:\n - `Urbana` (Urban)\n - `Rural` (Rural)\n - `Não Identificado`\n - `null`\n", "example": "Urbana" } } }, "EnumEmploymentSalaryType": { "type": "string", "nullable": true, "enum": [ "REGULAR", "THIRTEENTH", "VOLUNTARY", "RETIREMENT", null ], "description": "The type of salary.\n\nWe return one of the following values:\n - `REGULAR`\n - `THIRTEENTH`\n - `VOLUNTARY`\n - `RETIREMENT`\n - `null`\n", "example": "VOLUNTARY" }, "SalaryBrazil": { "type": "object", "description": "Details regarding the salary the employee received from the employer.", "additionalProperties": false, "required": [ "base_amount", "retained_amount", "month", "currency" ], "properties": { "base_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The base amount of the salary, before any deductions or bonuses.", "example": 1033.09 }, "retained_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount retained by Brazil's *Instituto Nacional do Seguro Social* (INSS).", "example": 0.01 }, "type": { "$ref": "#/components/schemas/EnumEmploymentSalaryType" }, "month": { "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^\\d{4}-\\d{2}$", "description": "The month that the employee received their salary, in `YYYY-MM` format.", "example": "2022-01" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217).", "example": "BRL" } } }, "EmploymentBrazil": { "type": "object", "description": "Details regarding the employment the employee had at a given employer.", "title": "Employments Object (Brazil)", "x-tags": [ "Employments Brazil" ], "additionalProperties": false, "required": [ "id", "link", "created_at", "collected_at", "start_date", "end_date", "employer_data", "occupations", "salaries" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "start_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The employee's start date at the employer, in `YYYY-MM-DD` format.", "example": "2022-01-01" }, "end_date": { "type": "string", "format": "date", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "minLength": 10, "maxLength": 10, "description": "The employee's end date at the employer, in `YYYY-MM-DD` format. If `null`, the employee is still working at the employer.", "example": "2023-01-01" }, "employer_data": { "$ref": "#/components/schemas/EmployerDataBrazil" }, "occupations": { "type": "array", "description": "The employee's occupations at the employer.", "items": { "$ref": "#/components/schemas/OccupationBrazil" } }, "salaries": { "type": "array", "description": "The salaries the employee received from the employer.", "items": { "$ref": "#/components/schemas/SalaryBrazil" } } } }, "EnumIncomeStreamType": { "type": "string", "enum": [ "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" ], "description": "The type of income used in the calculations.\n\nWe return one of the following enum values:\n\n - `SALARY`\n - `GOVERNMENT`\n - `INTEREST`\n - `RENT`\n - `RETIREMENT`\n - `FREELANCE`\n - `ALTERNATIVE_INCOME`\n - `TRANSFER`\n - `DEPOSIT`\n - `UNKNOWN`\n", "example": "SALARY" }, "EnumIncomeStreamFrequency": { "type": "string", "enum": [ "MONTHLY", "FORTNIGHTLY", "WEEKLY", "IRREGULAR", "SINGLE" ], "description": "How often the income is received.\n\nWe return one of the following enum values:\n\n - `MONTHLY` - For transactions that occur once per month.\n - `FORTNIGHTLY` - For transactions that occur once every two weeks.\n - `WEEKLY` - For transactions that occur once per week.\n - `IRREGULAR` - For transactions that do not occur on a defined frequency pattern.\n - `SINGLE` - For transactions that occur only once and do not repeat.\n", "example": "MONTHLY" }, "EnumIncomeStreamConfidence": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "description": "Belvo's level of confidence for future incomes.\n\nWe return one of the following enum values:\n\n - `HIGH`\n - `MEDIUM`\n - `LOW`\n", "example": "HIGH" }, "IncomeStreamsBody": { "type": "object", "required": [ "account_id", "income_type", "frequency", "monthly_average", "average_income_amount", "last_income_amount", "currency", "last_income_description", "last_income_date", "stability", "regularity", "trend", "lookback_periods", "full_periods", "periods_with_income", "number_of_incomes", "confidence" ], "description": "A list of income streams for the account.\n\nFor each income stream, we provide additional insights such as:\n- Frequency, stability, and confidence level of the income transactions.\n- Key metrics about the transaction amounts.\nℹ️ If no income sources are found, we return an empty array.\n", "properties": { "account_id": { "type": "string", "description": "Unique ID for the bank account to be verified for income streams.", "example": "EBACA-89077589" }, "income_type": { "$ref": "#/components/schemas/EnumIncomeStreamType" }, "frequency": { "$ref": "#/components/schemas/EnumIncomeStreamFrequency" }, "monthly_average": { "type": "number", "format": "float", "description": "The average amount of income received from the source over `periods_with_income`.\n", "example": 2500 }, "monthly_median": { "type": "number", "format": "float", "description": "The median amount of income received from the source over within a natural month.\n", "example": 2200 }, "average_income_amount": { "type": "number", "format": "float", "description": "The average income transaction amount from the source.\n", "example": 2500 }, "last_income_amount": { "type": "number", "format": "float", "description": "The amount of the most recent income received from the source.\n", "example": 2500 }, "currency": { "type": "string", "description": "The three-letter currency code of the income. For example:\n\n • 🇧🇷 BRL (Brazilian Real)\n • 🇨🇴 COP (Colombian Peso)\n • 🇲🇽 MXN (Mexican Peso)\n \n", "example": "BRL" }, "last_income_description": { "type": "string", "description": "The description of the most recent income from the stream. \n", "example": "Salário" }, "last_income_date": { "type": "string", "format": "date", "description": "The date when the most recent income from the stream was received, in `YYYY-MM-DD` format.\n", "example": "2023-02-09" }, "stability": { "type": "number", "nullable": true, "format": "float", "description": "The stability of the income based on its amount, with a range from 0 to 1, where 1 represents perfect stability.\n\n**Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.\n", "example": 1 }, "regularity": { "type": "number", "nullable": true, "format": "float", "description": "The regularity of the income based in its frequency, with a range from 0 to 1, where 1 represents perfect regularity.\n\n**Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.\n", "example": 1 }, "trend": { "type": "number", "nullable": true, "format": "float", "description": "The income trend during a period of time calculated between last income and first income received, where:\n - a negative float means that the income trend is decreasing during the time period.\n - a positive float means that the income trend is increasing during the time period.\n\n**Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.\n", "example": 0 }, "lookback_periods": { "type": "integer", "format": "int32", "description": "Number of period units (based on *rolling months*) used to generate insights and calculations.\n\n**Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.\n", "example": 9 }, "full_periods": { "type": "integer", "format": "int32", "description": "Number of period units (based on *rolling months*) with data to perform calculations.\n\n**Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.\n", "example": 9 }, "periods_with_income": { "type": "integer", "format": "int32", "description": "Number of period units (based on *rolling months*) with at least one income available.\n\n**Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.\n", "example": 9 }, "number_of_incomes": { "type": "integer", "format": "int32", "description": "Number of income transactions over the `lookback_periods`.\n", "example": 9 }, "confidence": { "$ref": "#/components/schemas/EnumIncomeStreamConfidence" } } }, "EnumIncomeSourceType": { "type": "string", "enum": [ "BANK" ], "description": "The type of source we generate income insights from.\nWe return one of the following enum values:\n\n - `BANK`\n", "example": "BANK" }, "Income": { "type": "object", "description": "Income insights", "title": "Income Object", "x-tags": [ "Incomes" ], "required": [ "id", "link", "created_at", "income_streams", "income_source_type", "first_transaction_date", "last_transaction_date", "best_working_day_to_charge", "good_working_days_to_charge", "number_of_income_streams", "monthly_average", "monthly_average_regular", "monthly_average_irregular", "monthly_average_low_confidence", "monthly_average_medium_confidence", "monthly_average_high_confidence", "total_income_amount", "total_regular_income_amount", "total_low_confidence", "total_medium_confidence", "total_high_confidence" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "income_streams": { "type": "array", "description": "An array of enriched income stream objects.", "items": { "$ref": "#/components/schemas/IncomeStreamsBody" } }, "income_source_type": { "$ref": "#/components/schemas/EnumIncomeSourceType" }, "first_transaction_date": { "type": "string", "nullable": true, "format": "date", "description": "The date when the first transaction occurred, in `YYYY-MM-DD` format.\n", "example": "2022-06-09" }, "last_transaction_date": { "type": "string", "format": "date", "description": "The date when when the last transaction occurred, in `YYYY-MM-DD` format.\n", "example": "2023-02-09" }, "best_working_day_to_charge": { "type": "integer", "format": "int32", "description": "The best working day of the month to charge the user.\n", "example": 22 }, "good_working_days_to_charge": { "type": "array", "minItems": 0, "maxItems": 3, "items": { "type": "integer", "format": "int32" }, "description": "Additional working days that have been identified as good days to charge the user.\n", "example": [ 17, 7, 2 ] }, "number_of_income_streams": { "type": "integer", "format": "int32", "description": "Number of total income streams analized.\n", "example": 1 }, "monthly_average": { "type": "number", "format": "float", "description": "Average amount of income received per month across all the accounts for the specific user.\n", "example": 2500 }, "monthly_average_regular": { "type": "number", "format": "float", "description": "Average amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, or `WEEKLY`) received per month for the specific user.\n", "example": 2500 }, "monthly_average_irregular": { "type": "number", "format": "float", "description": "Average amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) received per month for the specific user.\n", "example": 0 }, "monthly_average_low_confidence": { "type": "number", "format": "float", "description": "Average amount of income received per month for the specific user with `LOW` confidence.\n", "example": 0 }, "monthly_average_medium_confidence": { "type": "number", "format": "float", "description": "Average amount of income received per month for the specific user with `MEDIUM` confidence.\n", "example": 0 }, "monthly_average_high_confidence": { "type": "number", "format": "float", "description": "Average amount of income received per month for the specific user with `HIGH` confidence.\n", "example": 2500 }, "total_income_amount": { "type": "number", "format": "float", "description": "Total amount of all income received for the specific user.\n", "example": 22500 }, "total_regular_income_amount": { "type": "number", "format": "float", "description": "Total amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, `WEEKLY`) for the specific user.\n", "example": 22500 }, "total_irregular_income_amount": { "type": "number", "format": "float", "description": "Total amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) for the specific user.\n", "example": 0 }, "total_low_confidence": { "type": "number", "format": "float", "description": "Total amount of income for the specific user with `LOW` confidence.\n", "example": 0 }, "total_medium_confidence": { "type": "number", "format": "float", "description": "Total amount of income for the specific user with `MEDIUM` confidence.\n", "example": 0 }, "total_high_confidence": { "type": "number", "format": "float", "description": "Total amount of income for the specific user with `HIGH` confidence.\n", "example": 22500 } } }, "EnumInvoiceAllowedIncomeTypesRequest": { "type": "string", "enum": [ "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" ], "description": "The categories of the incomes you want to get information for. \n\nYou can send through one or more of the following values:\n - `SALARY`\n - `GOVERNMENT`\n - `INTEREST`\n - `RENT`\n - `RETIREMENT`\n - `FREELANCE`\n - `ALTERNATIVE_INCOME`\n - `TRANSFER`\n - `DEPOSIT`\n - `UNKNOWN`\n", "example": "SALARY" }, "EnumIncomeMinimumConfidenceLevelRequest": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "description": "The minimum confidence level of the incomes you want to get information for.\n\nYou can send through one of the following values:\n\n - `HIGH`\n - `MEDIUM`\n - `LOW`\n", "example": "HIGH" }, "RecurringExpenseSourceTransaction": { "type": "object", "nullable": true, "required": [ "amount", "description", "value_date" ], "description": "An array of minified transaction objects used to evaluate the recurring expense. If no transactions were found, we return an empty array.", "properties": { "amount": { "type": "number", "format": "float", "description": "The transaction amount.", "example": 2145.45 }, "description": { "type": "string", "nullable": true, "description": "The description of the transaction provided by the institution. Usually, this is the text that the end user would see in the bank statement. The description can be an empty string.\n\n**Note:** For EYOD Risk Insights, the description is the one that you provided in the initial request.\n", "example": "Netflix.com/march" }, "value_date": { "type": "string", "format": "date", "description": "The date when the transaction occurred, in `YYYY-MM-DD` format.", "example": "2019-10-23" } } }, "EnumRecurringExpenseFrequency": { "type": "string", "enum": [ "MONTHLY" ], "default": "MONTHLY", "description": "The frequency at which this recurring expense occurs.\n\n\nℹ️ **Note:** Belvo only identifies `MONTHLY` frequencies.\n", "example": "MONTHLY" }, "EnumRecurringExpenseCategory": { "type": "string", "enum": [ "Bills & Utilities", "Credits & Loans", "Insurance", "Online Platforms & Leisure", "Transport & Travel", "Taxes" ], "description": "The transaction category for the recurring expense. For more information on the available categories, please see our Transaction categorization documentation.\n\n- `Online Platforms & Leisure` (Netflix, Spotify, Gym Memberships)\n- `Bills & Utilities` (electricity, telephone, internet)\n- `Credits & Loans` (credit card cash advances, student loan, watercraft lease)\n- `Insurance` (home, car, and health & life insurance)\n- `Transport & Travel` (Uber trip, airbnb, parking)\n- `Taxes` (service fee, donation, court taxes)\n", "example": "Online Platforms & Leisure" }, "EnumRecurringExpensePaymentType": { "type": "string", "nullable": true, "enum": [ "SUBSCRIPTION", "REGULAR" ], "description": "The type of recurring expense. We return one of the following values:\n\n - `SUBSCRIPTION`\n - `REGULAR`\n", "example": "SUBSCRIPTION" }, "RecurringExpenses": { "type": "object", "title": "Recurring Expenses Object", "x-tags": [ "Recurring Expenses" ], "required": [ "account", "name", "transactions", "frequency", "average_transaction_amount", "median_transaction_amount", "days_since_last_transaction", "category", "payment_type" ], "description": "Recurring expense insights.\n\n\nℹ️ If no recurring expense insights are found, we return an empty array.\n", "properties": { "id": { "$ref": "#/components/schemas/id" }, "account": { "$ref": "#/components/schemas/AccountOpenFinanceBrazil" }, "name": { "type": "string", "nullable": true, "default": null, "description": "The name for the recurring expense.\n\nℹ️ **Note**: This information is taken from the description section of a transaction and then normalized to provide you with an easy-to-read name. As such, sometimes the name will reflect the merchant the payment is made to (for example, Netflix.com), while for other recurring expenses, this could be something like \"Monthly payment to John\".\n", "example": "Netflix" }, "transactions": { "type": "array", "description": "An array of minified transaction objects used to evaluate the recurring expense. If no transactions were found, we return an empty array.", "items": { "$ref": "#/components/schemas/RecurringExpenseSourceTransaction" } }, "frequency": { "$ref": "#/components/schemas/EnumRecurringExpenseFrequency" }, "average_transaction_amount": { "type": "number", "format": "float", "description": "The average transaction amount of the recurring expense.", "example": 32.9 }, "median_transaction_amount": { "type": "number", "format": "float", "description": "The median transaction amount of the recurring expense.", "example": 32.9 }, "days_since_last_transaction": { "type": "integer", "format": "int32", "description": "Number of days since the last recurring expense occurred.\n\nBased on the frequency, you can infer how many days until the next charge will occur.\n", "example": 5 }, "category": { "$ref": "#/components/schemas/EnumRecurringExpenseCategory" }, "payment_type": { "$ref": "#/components/schemas/EnumRecurringExpensePaymentType" } } }, "RiskInsightsAssetMetrics": { "type": "object", "nullable": true, "description": "Aggregate details regarding the assets used in the risk insight analysis. For asset metrics, we only consider checking and savings accounts.\n\n\n> Asset metrics can provide a snapshot of your user's wealth and liquid assets, indicating how they manage their wealth and their current financial status.\n", "required": [ "institutions", "num_accounts", "num_checking_accounts", "num_savings_accounts", "checking_accounts_balance", "savings_accounts_balance" ], "properties": { "institutions": { "type": "array", "nullable": true, "description": "An array of institutions from which account information was retrieved for the user. \n\n> **Note**: For most use cases, this array will only return one item.\n", "items": { "type": "string", "description": "The name of the institution", "example": "erebor_mx_retail" }, "example": [ "erebor_mx_retail" ] }, "num_assets_accounts": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of accounts found for the user.\n", "example": 1 }, "num_checking_accounts": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of checking accounts found for the user.\n", "example": 1 }, "num_savings_accounts": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of savings accounts found for the user.\n", "example": 1 }, "checking_accounts_balance": { "type": "number", "nullable": true, "format": "float", "description": "The total closing balance of all checking accounts.\n", "example": 35901.46 }, "savings_accounts_balance": { "type": "number", "nullable": true, "format": "float", "description": "The total closing balance of all savings accounts.\n", "example": 300.02 } } }, "RiskInsightsCreditCardMetrics": { "type": "object", "nullable": true, "required": [ "num_accounts", "sum_credit_limit", "sum_credit_used", "credit_card_limit_utilization" ], "description": "Aggregated metrics calculated based on the user's credit card accounts.\n\n> Credit card metrics illustrate a customer's credit card habits, revealing how many credit card accounts a customer has, their total credit limit, how much of that limit they're using, and the rate of their credit card limit utilization.\n", "properties": { "num_accounts": { "type": "integer", "format": "int32", "minimum": 0, "description": "Number of credit cards accounts associated to the user.\n", "example": 2 }, "sum_credit_limit": { "type": "number", "nullable": true, "format": "float", "description": "Sum total of all credit cards' limits.\n", "example": 106560 }, "sum_credit_used": { "type": "number", "nullable": true, "format": "float", "description": "Sum total of all credit used.\n", "example": 101020.14 }, "credit_card_limit_utilization": { "type": "number", "nullable": true, "format": "float", "description": "The percentage of the credit card limit used.\n", "example": 0.95 } } }, "RiskInsightsLoansMetrics": { "type": "object", "nullable": true, "description": "Aggregated metrics calculated based on the user's loan accounts and checking accounts that have an overdraft.\n\n> Loan metrics help in understanding a customer's borrowing and repayment behavior, which can help in assessing their ability to take on additional credit and potential default risks.\n", "required": [ "num_accounts", "sum_loans_principal", "sum_loans_outstanding_principal", "sum_loans_monthly_payment", "loan_limit_utilization", "overdraft_limit", "overdraft_limit_utilization" ], "properties": { "num_accounts": { "type": "integer", "format": "int32", "description": "The number of loan accounts associated with the user.\n", "example": 1 }, "sum_loans_principal": { "type": "number", "nullable": true, "format": "float", "description": "Sum total of the principal for all of the user's loan accounts.\n", "example": 5000 }, "sum_loans_outstanding_principal": { "type": "number", "nullable": true, "format": "float", "description": "Sum total of the outstanding principal for all the user's loan accounts.\n", "example": 2000 }, "sum_loans_monthly_payment": { "type": "number", "nullable": true, "format": "float", "description": "Sum total of the monthly payments for all the user's loan accounts.\n", "example": 400 }, "loan_limit_utilization": { "type": "number", "nullable": true, "format": "float", "description": "The percentage of the loan limit used.\n", "example": 0.3 }, "overdraft_limit": { "type": "number", "nullable": true, "format": "float", "description": "The total overdraft limit of all checking and savings accounts.\n", "example": 900 }, "overdraft_limit_utilization": { "type": "number", "nullable": true, "format": "float", "description": "The percentage of the overdraft limit used.\n", "example": 0.4 } } }, "RiskInsightsBalanceMetrics": { "type": "object", "nullable": true, "description": "Balance metrics calculated based on the user's balances from checking and savings accounts.", "required": [ "closing_balance", "min_balance_3d", "min_balance_1w", "min_balance_1m", "min_balance_3m", "min_balance_6m", "min_balance_12m", "mean_balance_3d", "mean_balance_1w", "mean_balance_1m", "mean_balance_3m", "mean_balance_6m", "mean_balance_12m", "max_balance_3d", "max_balance_1w", "max_balance_1m", "max_balance_3m", "max_balance_6m", "max_balance_12m", "std_balance_3d", "std_balance_1w", "std_balance_1m", "std_balance_3m", "std_balance_6m", "std_balance_12m", "balance_trend_3d", "balance_trend_1w", "balance_trend_1m", "balance_trend_3m", "balance_trend_6m", "balance_trend_12m", "days_balance_below_0_3d", "days_balance_below_0_1w", "days_balance_below_0_1m", "days_balance_below_0_3m", "days_balance_below_0_6m", "days_balance_below_0_12m", "days_balance_below_mean_3d", "days_balance_below_mean_1w", "days_balance_below_mean_1m", "days_balance_below_mean_3m", "days_balance_below_mean_6m", "days_balance_below_mean_12m", "days_balance_below_x_3d", "days_balance_below_x_1w", "days_balance_below_x_1m", "days_balance_below_x_3m", "days_balance_below_x_6m", "days_balance_below_x_12m", "balance_threshold_x" ], "properties": { "closing_balance": { "type": "number", "nullable": true, "format": "float", "description": "The balance of all the accounts at the `collected_at` time.\n", "example": 35901.46 }, "min_balance_3d": { "type": "number", "nullable": true, "format": "float", "description": "The minimum balance in the last three days.\n", "example": 35417.68 }, "min_balance_1w": { "type": "number", "nullable": true, "format": "float", "description": "The minimum balance in the last week).\n", "example": 34150.5 }, "min_balance_1m": { "type": "number", "nullable": true, "format": "float", "description": "The minimum balance in the last month.\n", "example": 33990.59 }, "min_balance_3m": { "type": "number", "nullable": true, "format": "float", "description": "The minimum balance in the last three months.\n", "example": 33990.59 }, "min_balance_6m": { "type": "number", "nullable": true, "format": "float", "description": "The minimum balance in the six last months.\n", "example": 33990.59 }, "min_balance_12m": { "type": "number", "nullable": true, "format": "float", "description": "The minimum balance in the last twelve months.\n", "example": 33990.59 }, "mean_balance_3d": { "type": "number", "nullable": true, "format": "float", "description": "The mean balance in the last three days.\n", "example": 35659.57 }, "mean_balance_1w": { "type": "number", "nullable": true, "format": "float", "description": "The mean balance in the last week.\n", "example": 35077.1 }, "mean_balance_1m": { "type": "number", "nullable": true, "format": "float", "description": "The mean balance in the last month.\n", "example": 34816.08 }, "mean_balance_3m": { "type": "number", "nullable": true, "format": "float", "description": "The mean balance in the last three months.\n", "example": 34816.08 }, "mean_balance_6m": { "type": "number", "nullable": true, "format": "float", "description": "The mean balance in the last six months.\n", "example": 34816.08 }, "mean_balance_12m": { "type": "number", "nullable": true, "format": "float", "description": "The mean balance in the last twelve months.\n", "example": 34816.08 }, "max_balance_3d": { "type": "number", "nullable": true, "format": "float", "description": "The maximum balance in the last three days.\n", "example": 35901.46 }, "max_balance_1w": { "type": "number", "nullable": true, "format": "float", "description": "The maximum balance in the last week.\n", "example": 35901.46 }, "max_balance_1m": { "type": "number", "nullable": true, "format": "float", "description": "The maximum balance in the last month.\n", "example": 35901.46 }, "max_balance_3m": { "type": "number", "nullable": true, "format": "float", "description": "The maximum balance in the last three months.\n", "example": 35901.46 }, "max_balance_6m": { "type": "number", "nullable": true, "format": "float", "description": "The maximum balance in the last six months.\n", "example": 35901.46 }, "max_balance_12m": { "type": "number", "nullable": true, "format": "float", "description": "The maximum balance in the last twelve months.\n", "example": 35901.46 }, "std_balance_3d": { "type": "number", "nullable": true, "format": "float", "description": "The balance standard deviation in the last three days.\n", "example": 279.31 }, "std_balance_1w": { "type": "number", "nullable": true, "format": "float", "description": "The balance standard deviation in the last week.\n", "example": 764.03 }, "std_balance_1m": { "type": "number", "nullable": true, "format": "float", "description": "The balance standard deviation in the last month.\n", "example": 586.55 }, "std_balance_3m": { "type": "number", "nullable": true, "format": "float", "description": "The balance standard deviation in the last three months.\n", "example": 586.55 }, "std_balance_6m": { "type": "number", "nullable": true, "format": "float", "description": "The balance standard deviation in the last six months.\n", "example": 586.55 }, "std_balance_12m": { "type": "number", "nullable": true, "format": "float", "description": "The balance standard deviation in the last twelve months.\n", "example": 586.55 }, "balance_trend_3d": { "type": "number", "nullable": true, "format": "float", "description": "The balance trend of the user in the last three days.\n", "example": 193.51 }, "balance_trend_1w": { "type": "number", "nullable": true, "format": "float", "description": "The balance trend of the user in the last week.\n", "example": 290.18 }, "balance_trend_1m": { "type": "number", "nullable": true, "format": "float", "description": "The balance trend of the user in the last month.\n", "example": 22.6 }, "balance_trend_3m": { "type": "number", "nullable": true, "format": "float", "description": "The balance trend of the user in the last three months.\n", "example": 22.6 }, "balance_trend_6m": { "type": "number", "nullable": true, "format": "float", "description": "The balance trend of the user in the last six months.\n", "example": 22.6 }, "balance_trend_12m": { "type": "number", "nullable": true, "format": "float", "description": "The balance trend of the user in the last twelve months.\n", "example": 22.6 }, "days_balance_below_0_3d": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to 0 in the last three days.\n", "example": 0 }, "days_balance_below_0_1w": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to 0 in the last week.\n", "example": 0 }, "days_balance_below_0_1m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to 0 in the last month.\n", "example": 0 }, "days_balance_below_0_3m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to 0 in the last three months.\n", "example": 0 }, "days_balance_below_0_6m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to 0 in the last six months.\n", "example": 0 }, "days_balance_below_0_12m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to 0 in the last twelve months.\n", "example": 0 }, "days_balance_below_mean_3d": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_3d`.\n", "example": 2 }, "days_balance_below_mean_1w": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_1w`.\n", "example": 3 }, "days_balance_below_mean_1m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_1m`.\n", "example": 17 }, "days_balance_below_mean_3m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_3m`.\n", "example": 17 }, "days_balance_below_mean_6m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_6m`.\n", "example": 17 }, "days_balance_below_mean_12m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the mean balance of the account is less than or equal to the amount specified in `mean_daily_balance_12m`.\n", "example": 17 }, "days_balance_below_x_3d": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last three days.\n", "example": 0 }, "days_balance_below_x_1w": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last week.\n", "example": 0 }, "days_balance_below_x_1m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last month.\n", "example": 0 }, "days_balance_below_x_3m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last three months.\n", "example": 0 }, "days_balance_below_x_6m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last six months.\n", "example": 0 }, "days_balance_below_x_12m": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days that the total balance of the account is less than or equal to the amount specified in `balance_threshold_x` in the last twelve months.\n", "example": 0 }, "balance_threshold_x": { "type": "number", "format": "float", "description": "The threshold used to compute `days_balance_below_x_period`. Please note, this is value is country specific (both in terms of the amount and the currency).\n", "example": 1000 } } }, "RiskInsightsTransactionMetrics": { "type": "object", "nullable": true, "description": "Aggregated metrics calculated based on the user's transactions from checking, savings, credit card, and loan accounts.\n\n\n> ℹ️ **Note**\n>\n> If there is not enough transactional data for a given period, we return `null` for calculated fields and `0` for 'count-based' fields. For example, if the account has only been open for five days (or you have provided data just for five days), we return values for `_3d`, `_1w`, and `_1m`, however:\n> \n> - `mean_num_transactions_3m` will return `null` as there is no data for months two and three (calculated field).\n> - `num_transactions_3m` will return `0` as there is no data for months two and three ('count-based' field)\n", "required": [ "num_transactions_3d", "num_transactions_1w", "num_transactions_1m", "num_transactions_3m", "num_transactions_6m", "num_transactions_12m", "max_num_transactions_3d", "max_num_transactions_1w", "max_num_transactions_1m", "max_num_transactions_3m", "max_num_transactions_6m", "max_num_transactions_12m", "mean_num_transactions_3d", "mean_num_transactions_1w", "mean_num_transactions_1m", "mean_num_transactions_3m", "mean_num_transactions_6m", "mean_num_transactions_12m", "num_incoming_transactions_3d", "num_incoming_transactions_1w", "num_incoming_transactions_1m", "num_incoming_transactions_3m", "num_incoming_transactions_6m", "num_incoming_transactions_12m", "max_num_incoming_transactions_3d", "max_num_incoming_transactions_1w", "max_num_incoming_transactions_1m", "max_num_incoming_transactions_3m", "max_num_incoming_transactions_6m", "max_num_incoming_transactions_12m", "mean_num_incoming_transactions_3d", "mean_num_incoming_transactions_1w", "mean_num_incoming_transactions_1m", "mean_num_incoming_transactions_3m", "mean_num_incoming_transactions_6m", "mean_num_incoming_transactions_12m", "sum_incoming_amount_3d", "sum_incoming_amount_1w", "sum_incoming_amount_1m", "sum_incoming_amount_3m", "sum_incoming_amount_6m", "sum_incoming_amount_12m", "max_incoming_amount_3d", "max_incoming_amount_1w", "max_incoming_amount_1m", "max_incoming_amount_3m", "max_incoming_amount_6m", "max_incoming_amount_12m", "mean_incoming_amount_3d", "mean_incoming_amount_1w", "mean_incoming_amount_1m", "mean_incoming_amount_3m", "mean_incoming_amount_6m", "mean_incoming_amount_12m", "num_outgoing_transactions_3d", "num_outgoing_transactions_1w", "num_outgoing_transactions_1m", "num_outgoing_transactions_3m", "num_outgoing_transactions_6m", "num_outgoing_transactions_12m", "max_num_outgoing_transactions_3d", "max_num_outgoing_transactions_1w", "max_num_outgoing_transactions_1m", "max_num_outgoing_transactions_3m", "max_num_outgoing_transactions_6m", "max_num_outgoing_transactions_12m", "mean_num_outgoing_transactions_3d", "mean_num_outgoing_transactions_1w", "mean_num_outgoing_transactions_1m", "mean_num_outgoing_transactions_3m", "mean_num_outgoing_transactions_6m", "mean_num_outgoing_transactions_12m", "sum_outgoing_amount_3d", "sum_outgoing_amount_1w", "sum_outgoing_amount_1m", "sum_outgoing_amount_3m", "sum_outgoing_amount_6m", "sum_outgoing_amount_12m", "max_outgoing_amount_3d", "max_outgoing_amount_1w", "max_outgoing_amount_1m", "max_outgoing_amount_3m", "max_outgoing_amount_6m", "max_outgoing_amount_12m", "mean_outgoing_amount_3d", "mean_outgoing_amount_1w", "mean_outgoing_amount_1m", "mean_outgoing_amount_3m", "mean_outgoing_amount_6m", "mean_outgoing_amount_12m", "days_without_transactions_3d", "days_without_transactions_1w", "days_without_transactions_1m", "days_without_transactions_3m", "days_without_transactions_6m", "days_without_transactions_12m", "days_since_last_transaction", "days_since_last_incoming_transaction", "days_since_last_outgoing_transaction", "days_history" ], "properties": { "num_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of transactions analyzed to determine the risk insights for the last three days (incoming and outgoing).\n", "example": 26 }, "num_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of transactions analyzed to determine the risk insights for the last week (incoming and outgoing).\n", "example": 46 }, "num_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of transactions analyzed to determine the risk insights for the last month (incoming and outgoing).\n", "example": 168 }, "num_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of transactions analyzed to determine the risk insights for the last three months (incoming and outgoing).\n", "example": 460 }, "num_transactions_6m": { "type": "integer", "format": "int32", "default": 670, "description": "The total number of transactions analyzed to determine the risk insights for the last six months (incoming and outgoing).\n", "example": 472 }, "num_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of transactions analyzed to determine the risk insights for the last twelve months (incoming and outgoing).\n", "example": 496 }, "max_num_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of transactions for the last three days.\n", "example": 10 }, "max_num_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of transactions for the last week.\n", "example": 10 }, "max_num_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of transactions for the last month.\n", "example": 18 }, "max_num_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of transactions for the last three months.\n", "example": 18 }, "max_num_transactions_6m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of transactions for the last six months.\n", "example": 18 }, "max_num_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of transactions for the last twelve months.\n", "example": 18 }, "mean_num_transactions_3d": { "type": "number", "format": "float", "default": 0, "description": "The mean number of transactions for the last three days.\n", "example": 6.5 }, "mean_num_transactions_1w": { "type": "number", "format": "float", "default": 0, "description": "The mean number of transactions for the last week.\n", "example": 5.75 }, "mean_num_transactions_1m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of transactions for the last month.\n", "example": 5.42 }, "mean_num_transactions_3m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of transactions for the last three months.\n", "example": 5.05 }, "mean_num_transactions_6m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of transactions for the last six months.\n", "example": 2.61 }, "mean_num_transactions_12m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of transactions for the last twelve months.\n", "example": 1.37 }, "num_incoming_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of inflow transactions for the last three days.\n", "example": 12 }, "num_incoming_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of inflow transactions for the last week.\n", "example": 21 }, "num_incoming_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of inflow transactions for the last month.\n", "example": 80 }, "num_incoming_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of inflow transactions for the last three months.\n", "example": 229 }, "num_incoming_transactions_6m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of inflow transactions for the last six months.\n", "example": 238 }, "num_incoming_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "The total number of inflow transactions for the last twelve months.\n", "example": 256 }, "max_num_incoming_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of inflow transactions for the last three days.\n", "example": 6 }, "max_num_incoming_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of inflow transactions for the last week.\n", "example": 6 }, "max_num_incoming_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of inflow transactions for the last month.\n", "example": 10 }, "max_num_incoming_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of inflow transactions for the last three months.\n", "example": 10 }, "max_num_incoming_transactions_6m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of inflow transactions for the last six months.\n", "example": 10 }, "max_num_incoming_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of inflow transactions for the last twelve months.\n", "example": 10 }, "mean_num_incoming_transactions_3d": { "type": "number", "format": "float", "default": 0, "description": "The mean number of inflow transactions for the last three days.\n", "example": 3 }, "mean_num_incoming_transactions_1w": { "type": "number", "format": "float", "default": 0, "description": "The mean number of inflow transactions for the last week.\n", "example": 2.62 }, "mean_num_incoming_transactions_1m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of inflow transactions for the last month.\n", "example": 2.58 }, "mean_num_incoming_transactions_3m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of inflow transactions for the last three months.\n", "example": 2.52 }, "mean_num_incoming_transactions_6m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of inflow transactions for the last six months.\n", "example": 1.31 }, "mean_num_incoming_transactions_12m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of inflow transactions for the last twelve months.\n", "example": 0.71 }, "sum_incoming_amount_3d": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all inflow transactions for the last three days.\n", "example": 17142.16 }, "sum_incoming_amount_1w": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all inflow transactions for the last week.\n", "example": 24825.92 }, "sum_incoming_amount_1m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all inflow transactions for the last month.\n", "example": 75993.36 }, "sum_incoming_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all inflow transactions for the last three months.\n", "example": 198197.28 }, "sum_incoming_amount_6m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all inflow transactions for the last six months.\n", "example": 223697.28 }, "sum_incoming_amount_12m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all inflow transactions for the last twelve months.\n", "example": 274697.28 }, "max_incoming_amount_3d": { "type": "number", "nullable": true, "format": "float", "description": "The highest value inflow transaction in the last three days.\n", "example": 3000 }, "max_incoming_amount_1w": { "type": "number", "nullable": true, "format": "float", "description": "The highest value inflow transaction in the last week.\n", "example": 3000 }, "max_incoming_amount_1m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value inflow transaction in the last month.\n", "example": 3000 }, "max_incoming_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value inflow transaction in the last three months.\n", "example": 3000 }, "max_incoming_amount_6m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value inflow transaction in the last six months.\n", "example": 3000 }, "max_incoming_amount_12m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value inflow transaction in the last twelve months.\n", "example": 3000 }, "mean_incoming_amount_3d": { "type": "number", "nullable": true, "format": "float", "description": "The mean incoming value of all transactions in the last three days.\n", "example": 1428.51 }, "mean_incoming_amount_1w": { "type": "number", "nullable": true, "format": "float", "description": "The mean incoming value of all transactions in the last week.\n", "example": 1182.19 }, "mean_incoming_amount_1m": { "type": "number", "nullable": true, "format": "float", "description": "The mean incoming value of all transactions in the last month.\n", "example": 949.92 }, "mean_incoming_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The mean incoming value of all transactions in the last three months.\n", "example": 865.49 }, "mean_incoming_amount_6m": { "type": "number", "nullable": true, "format": "float", "description": "The mean incoming value of all transactions in the last six months.\n", "example": 939.9 }, "mean_incoming_amount_12m": { "type": "number", "nullable": true, "format": "float", "description": "The mean incoming value of all transactions in the last twelve months.\n", "example": 1073.04 }, "num_outgoing_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "To total number of outflow transactions in the last three days.\n", "example": 14 }, "num_outgoing_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "To total number of outflow transactions in the last week.\n", "example": 25 }, "num_outgoing_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "To total number of outflow transactions in the last month.\n", "example": 88 }, "num_outgoing_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "To total number of outflow transactions in the last three months.\n", "example": 231 }, "num_outgoing_transactions_6m": { "type": "integer", "format": "int32", "default": 0, "description": "To total number of outflow transactions in the last six months.\n", "example": 234 }, "num_outgoing_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "To total number of outflow transactions in the last twelve months.\n", "example": 240 }, "max_num_outgoing_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of outflow transactions for the last three days.\n", "example": 6 }, "max_num_outgoing_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of outflow transactions for the last week.\n", "example": 6 }, "max_num_outgoing_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of outflow transactions for the last month.\n", "example": 8 }, "max_num_outgoing_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of outflow transactions for the last three months.\n", "example": 9 }, "max_num_outgoing_transactions_6m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of outflow transactions for the last six months.\n", "example": 9 }, "max_num_outgoing_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "The maximum number of outflow transactions for the last twelve months.\n", "example": 9 }, "mean_num_outgoing_transactions_3d": { "type": "number", "format": "float", "default": 0, "description": "The mean number of outflow transactions for the last three days.\n", "example": 3.5 }, "mean_num_outgoing_transactions_1w": { "type": "number", "format": "float", "default": 0, "description": "The mean number of outflow transactions for the last week.\n", "example": 3.12 }, "mean_num_outgoing_transactions_1m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of outflow transactions for the last month.\n", "example": 2.84 }, "mean_num_outgoing_transactions_3m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of outflow transactions for the last three months.\n", "example": 2.54 }, "mean_num_outgoing_transactions_6m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of outflow transactions for the last six months.\n", "example": 1.29 }, "mean_num_outgoing_transactions_12m": { "type": "number", "format": "float", "default": 0, "description": "The mean number of outflow transactions for the last twelve months.\n", "example": 0.66 }, "sum_outgoing_amount_3d": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all outflow transactions for the last three days.\n", "example": 18246.95 }, "sum_outgoing_amount_1w": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all outflow transactions for the last week.\n", "example": 26362.25 }, "sum_outgoing_amount_1m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all outflow transactions for the last month.\n", "example": 78243.82 }, "sum_outgoing_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all outflow transactions for the last three months.\n", "example": 192608.77 }, "sum_outgoing_amount_6m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all outflow transactions for the last six months.\n", "example": 201608.77 }, "sum_outgoing_amount_12m": { "type": "number", "nullable": true, "format": "float", "description": "The total sum of all outflow transactions for the last twelve months.\n", "example": 219608.77 }, "max_outgoing_amount_3d": { "type": "number", "nullable": true, "format": "float", "description": "The highest value outflow transaction in the last three days.\n", "example": 3000 }, "max_outgoing_amount_1w": { "type": "number", "nullable": true, "format": "float", "description": "The highest value outflow transaction in the last week.\n", "example": 3000 }, "max_outgoing_amount_1m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value outflow transaction in the last month.\n", "example": 3000 }, "max_outgoing_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value outflow transaction in the last three months.\n", "example": 3000 }, "max_outgoing_amount_6m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value outflow transaction in the last six months.\n", "example": 3000 }, "max_outgoing_amount_12m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value outflow transaction in the last twelve months.\n", "example": 3000 }, "mean_outgoing_amount_3d": { "type": "number", "nullable": true, "format": "float", "description": "The mean outgoing value of all transaction in the last three days.\n", "example": 1303.35 }, "mean_outgoing_amount_1w": { "type": "number", "nullable": true, "format": "float", "description": "The mean outgoing value of all transaction in the last week.\n", "example": 1054.49 }, "mean_outgoing_amount_1m": { "type": "number", "nullable": true, "format": "float", "description": "The mean outgoing value of all transaction in the last month.\n", "example": 889.13 }, "mean_outgoing_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The mean outgoing value of all transaction in the last three months.\n", "example": 833.8 }, "mean_outgoing_amount_6m": { "type": "number", "nullable": true, "format": "float", "description": "The mean outgoing value of all transaction in the last six months.\n", "example": 861.58 }, "mean_outgoing_amount_12m": { "type": "number", "nullable": true, "format": "float", "description": "The mean outgoing value of all transaction in the last twelve months.\n", "example": 915.04 }, "days_without_transactions_3d": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days that no transactions occurred within the last three days.\n", "example": 0 }, "days_without_transactions_1w": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days that no transactions occurred within the last week.\n", "example": 0 }, "days_without_transactions_1m": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days that no transactions occurred within the last month.\n", "example": 0 }, "days_without_transactions_3m": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days that no transactions occurred within the last three months.\n", "example": 0 }, "days_without_transactions_6m": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days that no transactions occurred within the last six months.\n", "example": 87 }, "days_without_transactions_12m": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days that no transactions occurred within the last twelve months.\n", "example": 261 }, "days_since_last_transaction": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days since the last transaction occurred.\n", "example": 0 }, "days_since_last_incoming_transaction": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days since the last inflow transaction occurred.\n", "example": 0 }, "days_since_last_outgoing_transaction": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days since the last outflow transaction occurred.\n", "example": 0 }, "days_history": { "type": "integer", "format": "int32", "default": 0, "description": "The number of days between when the risk insight request was made and the first transaction.\n", "example": 365 } } }, "RiskInsightsCashflowMetrics": { "type": "object", "nullable": true, "description": "Aggregate metrics calculated based on the user's transactions from checking, savings, credit, and loan accounts. However, internal transfers (transfers between accounts belonging to the same link) are not used in the calculation.\n\n{% admonition type=\"info\" %}\n If there is not enough transactional data for a given period, we return `null`. For example, if the account has only been open for 15 days (or you have only provided data for just 15 days), we return values for `_3d`, `_1w`, and `_1m`, however for `_3m` we will return `null` as there is no data for months two and three.\n{% /admonition %}\n", "required": [ "max_positive_3d", "max_positive_1w", "max_positive_1m", "max_positive_3m", "max_positive_6m", "max_positive_12m", "max_negative_3d", "max_negative_1w", "max_negative_1m", "max_negative_3m", "max_negative_6m", "max_negative_12m", "mean_positive_3d", "mean_positive_1w", "mean_positive_1m", "mean_positive_3m", "mean_positive_6m", "mean_positive_12m", "mean_negative_3d", "mean_negative_1w", "mean_negative_1m", "mean_negative_3m", "mean_negative_6m", "mean_negative_12m", "sum_positive_3d", "sum_positive_1w", "sum_positive_1m", "sum_positive_3m", "sum_positive_6m", "sum_positive_12m", "sum_positive_trend_3d", "sum_positive_trend_1w", "sum_positive_trend_1m", "sum_positive_trend_3m", "sum_positive_trend_6m", "sum_positive_trend_12m", "sum_negative_3d", "sum_negative_1w", "sum_negative_1m", "sum_negative_3m", "sum_negative_6m", "sum_negative_12m", "sum_negative_trend_3d", "sum_negative_trend_1w", "sum_negative_trend_1m", "sum_negative_trend_3m", "sum_negative_trend_6m", "sum_negative_trend_12m", "positive_to_negative_ratio_3d", "positive_to_negative_ratio_1w", "positive_to_negative_ratio_1m", "positive_to_negative_ratio_3m", "positive_to_negative_ratio_6m", "positive_to_negative_ratio_12m", "net_cashflow_3d", "net_cashflow_1w", "net_cashflow_1m", "net_cashflow_3m", "net_cashflow_6m", "net_cashflow_12m", "net_cashflow_trend_3d", "net_cashflow_trend_1w", "net_cashflow_trend_1m", "net_cashflow_trend_3m", "net_cashflow_trend_6m", "net_cashflow_trend_12m" ], "properties": { "max_positive_3d": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of positive cash flow transactions in the last three days.\n", "example": 1850.12 }, "max_positive_1w": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of positive cash flow transactions the last week.\n", "example": 3808.99 }, "max_positive_1m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of positive cash flow transactions the last month.\n", "example": 4012.61 }, "max_positive_3m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of positive cash flow transactions the last three months.\n", "example": 5001.08 }, "max_positive_6m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of positive cash flow transactions the last six months.\n", "example": 8500 }, "max_positive_12m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of positive cash flow transactions the last twelve months.\n", "example": 8500 }, "max_negative_3d": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of negative cash flow transactions in the last three days.\n", "example": 3375.43 }, "max_negative_1w": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of negative cash flow transactions in the last week.\n", "example": 3375.43 }, "max_negative_1m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of negative cash flow transactions in the last month.\n", "example": 5305.92 }, "max_negative_3m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of negative cash flow transactions in the last three months.\n", "example": 7535.85 }, "max_negative_6m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of negative cash flow transactions in the last six months.\n", "example": 7535.85 }, "max_negative_12m": { "type": "number", "nullable": true, "format": "float", "description": "The highest value of negative cash flow transactions in the last twelve months.\n", "example": 7535.85 }, "mean_positive_3d": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the positive cash flow transactions in the last three days.\n", "example": 1410.54 }, "mean_positive_1w": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the positive cash flow transactions in the last week.\n", "example": 1665.74 }, "mean_positive_1m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the positive cash flow transactions in the last month.\n", "example": 1827.36 }, "mean_positive_3m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the positive cash flow transactions in the last three months.\n", "example": 1881.58 }, "mean_positive_6m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the positive cash flow transactions in the last six months.\n", "example": 2102.19 }, "mean_positive_12m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the positive cash flow transactions in the last twelve months.\n", "example": 2502.06 }, "mean_negative_3d": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the negative cash flow transactions in the last three days.\n", "example": 3373.48 }, "mean_negative_1w": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the negative cash flow transactions in the last week.\n", "example": 2477.04 }, "mean_negative_1m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the negative cash flow transactions in the last month.\n", "example": 1904.96 }, "mean_negative_3m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the negative cash flow transactions in the last three months.\n", "example": 1838.47 }, "mean_negative_6m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the negative cash flow transactions in the last six months.\n", "example": 1877.63 }, "mean_negative_12m": { "type": "number", "nullable": true, "format": "float", "description": "The mean value of the negative cash flow transactions in the last twelve months.\n", "example": 1948.51 }, "sum_positive_3d": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a positive cash flow in the last three days.\n", "example": 5642.16 }, "sum_positive_1w": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a positive cash flow in the last week.\n", "example": 13325.92 }, "sum_positive_1m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a positive cash flow in the last month.\n", "example": 52993.36 }, "sum_positive_3m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a positive cash flow in the last three months.\n", "example": 163697.28 }, "sum_positive_6m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a positive cash flow in the last six months.\n", "example": 189197.28 }, "sum_positive_12m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a positive cash flow in the last twelve months.\n", "example": 240197.28 }, "sum_positive_trend_3d": { "type": "number", "nullable": true, "format": "float", "description": "The positive cash flow trend based on the sum of all positive transactions in the last three days.\n", "example": 98.902 }, "sum_positive_trend_1w": { "type": "number", "nullable": true, "format": "float", "description": "The positive cash flow trend based on the sum of all positive transactions in the last week.\n", "example": -84.0393 }, "sum_positive_trend_1m": { "type": "number", "nullable": true, "format": "float", "description": "The positive cash flow trend based on the sum of all positive transactions in the last month.\n", "example": 22.7315 }, "sum_positive_trend_3m": { "type": "number", "nullable": true, "format": "float", "description": "The positive cash flow trend based on the sum of all positive transactions in the last three months.\n", "example": 1.8398 }, "sum_positive_trend_6m": { "type": "number", "nullable": true, "format": "float", "description": "The positive cash flow trend based on the sum of all positive transactions in the last six months.\n", "example": -17.1869 }, "sum_positive_trend_12m": { "type": "number", "nullable": true, "format": "float", "description": "The positive cash flow trend based on the sum of all positive transactions in the last twelve months.\n", "example": -25.9856 }, "sum_negative_3d": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a negative cash flow in the last three days.\n", "example": 6746.95 }, "sum_negative_1w": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a negative cash flow in the last week.\n", "example": 14862.25 }, "sum_negative_1m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a negative cash flow in the last month.\n", "example": 55243.82 }, "sum_negative_3m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a negative cash flow in the last three months.\n", "example": 158108.77 }, "sum_negative_6m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a negative cash flow in the last six months.\n", "example": 167108.77 }, "sum_negative_12m": { "type": "number", "nullable": true, "format": "float", "description": "The sum total of all transactions leading to a negative cash flow in the last twelve months.\n", "example": 185108.77 }, "sum_negative_trend_3d": { "type": "number", "nullable": true, "format": "float", "description": "The negative cash flow trend based on the sum of all negative transactions in the last three days.\n", "example": -3.91 }, "sum_negative_trend_1w": { "type": "number", "nullable": true, "format": "float", "description": "The negative cash flow trend based on the sum of all negative transactions in the last week.\n", "example": 254.2517 }, "sum_negative_trend_1m": { "type": "number", "nullable": true, "format": "float", "description": "The negative cash flow trend based on the sum of all negative transactions in the last month.\n", "example": 58.376 }, "sum_negative_trend_3m": { "type": "number", "nullable": true, "format": "float", "description": "The negative cash flow trend based on the sum of all negative transactions in the last three months.\n", "example": 2.5895 }, "sum_negative_trend_6m": { "type": "number", "nullable": true, "format": "float", "description": "The negative cash flow trend based on the sum of all negative transactions in the last six months.\n", "example": -1.4824 }, "sum_negative_trend_12m": { "type": "number", "nullable": true, "format": "float", "description": "The negative cash flow trend based on the sum of all negative transactions in the last twelve months.\n", "example": -4.2394 }, "positive_to_negative_ratio_3d": { "type": "number", "nullable": true, "format": "float", "description": "The ratio between sum_positive / sum_negative in the last three days.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n", "example": 0.84 }, "positive_to_negative_ratio_1w": { "type": "number", "nullable": true, "format": "float", "description": "The ratio between sum_positive / sum_negative in the last week.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n", "example": 0.9 }, "positive_to_negative_ratio_1m": { "type": "number", "nullable": true, "format": "float", "description": "The ratio between sum_positive / sum_negative in the last month.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n", "example": 0.96 }, "positive_to_negative_ratio_3m": { "type": "number", "nullable": true, "format": "float", "description": "The ratio between sum_positive / sum_negative in the last three months.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n", "example": 1.04 }, "positive_to_negative_ratio_6m": { "type": "number", "nullable": true, "format": "float", "description": "The ratio between sum_positive / sum_negative in the last six months.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n", "example": 1.13 }, "positive_to_negative_ratio_12m": { "type": "number", "nullable": true, "format": "float", "description": "The ratio between sum_positive / sum_negative in the last twelve months.\n\nℹ️ If the ratio is greater than `1`, it means that the user has more income than outgoing, indicating that they spend less than they earn.\n\n**Note**: In the case that there have been no outgoing transactions, the value will be `null`.\n", "example": 1.3 }, "net_cashflow_3d": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow in the last three days.\n", "example": -1104.79 }, "net_cashflow_1w": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow in the last week.\n", "example": -1536.33 }, "net_cashflow_1m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow in the last month.\n", "example": -2250.46 }, "net_cashflow_3m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow in the last three months.\n", "example": 5588.51 }, "net_cashflow_6m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow in the last six months.\n", "example": 22088.51 }, "net_cashflow_12m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow in the last twelve months.\n", "example": 55088.51 }, "net_cashflow_trend_3d": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow trend in the last three days months.\n", "example": 1448.683 }, "net_cashflow_trend_1w": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow trend in the last week.\n", "example": 163.8856 }, "net_cashflow_trend_1m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow trend in the last month.\n", "example": 1.3034 }, "net_cashflow_trend_3m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow trend in the last three months.\n", "example": -0.472 }, "net_cashflow_trend_6m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow trend in the last six months.\n", "example": -15.1286 }, "net_cashflow_trend_12m": { "type": "number", "nullable": true, "format": "float", "description": "The net cash flow trend in the last twelve months.\n", "example": -21.5511 } } }, "RiskInsightsCategoryMetrics": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/EnumTransactionCategory" }, "subcategory": { "$ref": "#/components/schemas/EnumTransactionSubcategory" }, "net_amount_3m": { "type": "number", "nullable": true, "format": "float", "description": "The net amount of the transactions for this category in the last three months (calculated as the total incoming - total outgoing transactions for this category).", "example": 642.76 }, "category_inflow_ratio_3m": { "type": "number", "nullable": true, "format": "float", "description": "The ratio of `net_amount_3m` divided by the sum of all incoming categorized transactions (including the current category) for the same period.\n\nNote: If there are no inflow transactions for the period, this value will return `null`.\n", "example": 1 }, "trend_3m": { "type": "number", "nullable": true, "format": "float", "description": "The net category transaction trend (incoming - outgoing transactions for the category) for the period.", "example": 0 } } }, "RiskInsights": { "type": "object", "title": "Risk Insights Object", "x-tags": [ "Risk Insights" ], "required": [ "id", "link", "created_at", "accounts", "assets_metrics", "transactions_metrics", "balances_metrics", "cashflow_metrics", "credit_cards_metrics", "loans_metrics", "category_metrics" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "accounts": { "type": "array", "nullable": true, "description": "An array of Belvo-generated account numbers (UUIDs) that were used during the risk insights analysis. If no accounts were found, we return an empty array.", "items": { "type": "string", "format": "uuid", "description": "The Belvo-generated ID for the account.", "example": "0d3ffb69-f83b-456e-ad8e-208d0998d71d" }, "example": [ "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "00293c8e-1152-440b-9892-3c071fb88672", "cf638fba-ef45-4c10-bc6f-adecc4b2bf4e", "3861a5da-ae9b-4f20-a632-a9294489d5ac", "1f60315b-236d-498e-be7a-92bc613d329b", "a2c8da63-ed51-41e6-891a-4ae7e784463a" ] }, "assets_metrics": { "$ref": "#/components/schemas/RiskInsightsAssetMetrics" }, "credit_cards_metrics": { "$ref": "#/components/schemas/RiskInsightsCreditCardMetrics" }, "loans_metrics": { "$ref": "#/components/schemas/RiskInsightsLoansMetrics" }, "balances_metrics": { "$ref": "#/components/schemas/RiskInsightsBalanceMetrics" }, "transactions_metrics": { "$ref": "#/components/schemas/RiskInsightsTransactionMetrics" }, "cashflow_metrics": { "$ref": "#/components/schemas/RiskInsightsCashflowMetrics" }, "category_metrics": { "type": "array", "description": "An array of aggregate metrics regarding the transaction categories and subcategories that Belvo has identified within the user's transaction history.\n\nIn the array, Belvo only returns categories that have been identified.\n", "items": { "$ref": "#/components/schemas/RiskInsightsCategoryMetrics" } } } }, "EmploymentMetric": { "type": "object", "description": "Employment Metrics details", "title": "Employment Metrics Object", "x-tags": [ "Employment Metrics" ], "required": [ "id", "link", "collected_at", "created_at", "updated_at", "reference_date", "age", "current_status", "current_employer_count", "base_salary_last", "weeks_employed_last_job", "weeks_since_last_job", "weeks_employed_total", "weeks_with_multiple_employers", "employer_count", "unique_employer_count", "employers_per_year", "weeks_between_jobs", "max_weeks_between_jobs", "increases_last_job", "decreases_last_job", "increases_after_change", "decreases_after_change", "increases_overall", "decreases_overall", "increases_1y", "decreases_1y", "increases_3y", "decreases_3y", "increases_5y", "decreases_5y", "yearly_change_1y", "yearly_change_3y", "yearly_change_5y", "min_monthly_salary_1y", "min_monthly_salary_3y", "min_monthly_salary_5y", "average_monthly_salary_1y", "average_monthly_salary_3y", "average_monthly_salary_5y", "max_monthly_salary_1y", "max_monthly_salary_3y", "max_monthly_salary_5y" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the employment metrics calculation was last updated.\n", "example": "2023-08-30T15:31:35.728607Z" }, "reference_date": { "type": "string", "nullable": true, "format": "date", "description": "The reference_date your provided in your request. If you didn't provide one, this field will return `null`, indicating that the calculations are performed up until the date of the request.\n\n**Note:** All calculations are relative to this date.\n", "example": "2023-06-01" }, "age": { "type": "integer", "format": "int32", "description": "The age of the individual.", "example": 32 }, "current_status": { "$ref": "#/components/schemas/EnumEmploymentRecordStatus" }, "current_employer_count": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of employers the individual has right now.\n", "example": 1 }, "base_salary_last": { "type": "number", "nullable": true, "format": "float", "description": "The user's latest base salary. If `current_status` is `EMPLOYED`, this is the user's current base salary.\n", "example": 42.17 }, "weeks_employed_last_job": { "type": "number", "nullable": true, "format": "float", "description": "The number of weeks the user was employed in their last job. If `current_status` is `EMPLOYED`, then this field indicates the number of weeks the user has been employed with his current job.\n", "example": 327.1429 }, "weeks_since_last_job": { "type": "number", "nullable": true, "format": "float", "description": "The number of weeks since their last job. If the value of this field is `0`, this indicates that the user is currently employed.\n", "example": 0 }, "weeks_employed_total": { "type": "number", "nullable": true, "format": "float", "description": "The total number of weeks the user has been employed, according to the institution.\n\n> **Note:**\n>\n> In the case that the user is employed at two or more places at the same time, we still calculate those weeks as one week. For example, if a user has three concurrent jobs for a month, this is calculated as 4 weeks.\n", "example": 148.2 }, "weeks_with_multiple_employers": { "type": "number", "nullable": true, "format": "float", "description": "The number of the weeks that the individual has had more than one employer at the same time.\n", "example": 0 }, "employer_count": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of employers the user has had. Useful to indicate employment stability over the course of their lifetime.\n", "example": 14 }, "unique_employer_count": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of unique employers that the individual has had.\n\n> **Note:**\n>\n> If the user left one company and returned, for example, six months later to the same company, this is counted as one employer.\n", "example": 3 }, "employers_per_year": { "type": "number", "nullable": true, "format": "float", "description": "Number of employers per year. Useful to indicate employment stability over the course of a year.\n\n> **Note:**\n>\n> If the user left one company and returned, for example, six months later to the same company, this is counted as one employer.\n", "example": 0.6326 }, "weeks_between_jobs": { "type": "number", "nullable": true, "format": "float", "description": "The total number of weeks the individual was unemployed.\n", "example": 687.2865 }, "max_weeks_between_jobs": { "type": "number", "nullable": true, "format": "float", "description": "The maximum number of weeks that the individual was unemployed.\n", "example": 249.8571 }, "increases_last_job": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases the user had in their last job. If `current_status` is `EMPLOYED`, this refers to the user's current job.\n\n> **Note:**\n>\n> For all salary increases or decreases, we only take into account those where the change in salary is greater than 2%.\n", "example": 0 }, "decreases_last_job": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases the user had in their last job. If `current_status` is `EMPLOYED`, this refers to the user's current job.\n", "example": 0 }, "increases_after_change": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases between the individual's penultimate job and the last (or current) job.\n", "example": 0 }, "decreases_after_change": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary decreases between the individual's penultimate job and the last (or current) job.\n", "example": 0 }, "increases_overall": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases throughout the individual's working career.\n", "example": 0 }, "decreases_overall": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary decreases throughout the individual's working career.\n", "example": 0 }, "increases_1y": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases throughout the individual's last year (YTD).\n", "example": 0 }, "decreases_1y": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary decreases throughout the individual's last year (YTD).\n", "example": 0 }, "increases_3y": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases throughout the individual's last three years.\n\n> **Note:**\n>\n> If the individual's working career is less than three years, we return `null`.\n", "example": null }, "decreases_3y": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary decreases throughout the individual's last three years.\n\n> **Note:**\n>\n> If the individual's working career is less than three years, we return `null`.\n", "example": null }, "increases_5y": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary increases throughout the individual's last five years.\n\n> **Note:**\n>\n> If the individual's working career is less than five years, we return `null`.\n", "example": null }, "decreases_5y": { "type": "integer", "nullable": true, "format": "int32", "description": "The total number of salary decreases throughout the individual's last five years.\n\n> **Note:**\n>\n> If the individual's working career is less than five years, we return `null`.\n", "example": null }, "yearly_change_1y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's salary percentage change for the last year (YTD).\n", "example": 0 }, "yearly_change_3y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's salary percentage change for the last three years.\n\n> **Note:**\n>\n> If the individual's working career is less than three years, we return `null`.\n", "example": null }, "yearly_change_5y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's salary percentage change for the last five years.\n\n> **Note:**\n>\n> If the individual's working career is less than five years, we return `null`.\n", "example": null }, "min_monthly_salary_1y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's minimum monthly salary for the last year.\n", "example": 3402.88 }, "min_monthly_salary_3y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's minimum monthly salary for the last three years.\n", "example": 3402.88 }, "min_monthly_salary_5y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's minimum monthly salary for the last five years.\n", "example": 3402.88 }, "average_monthly_salary_1y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's average monthly salary for the last year.\n", "example": 3402.88 }, "average_monthly_salary_3y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's average monthly salary for the last three years.\n", "example": 3402.88 }, "average_monthly_salary_5y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's average monthly salary for the last five years.\n", "example": 3402.88 }, "max_monthly_salary_1y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's maximum monthly salary for the last year.\n", "example": 3402.88 }, "max_monthly_salary_3y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's maximum monthly salary for the last three years.\n", "example": 3402.88 }, "max_monthly_salary_5y": { "type": "number", "nullable": true, "format": "float", "description": "The individual's maximum monthly salary for the last five years.\n", "example": 3402.88 } } }, "FinancialStatementBalanceSheetCurrentAssets": { "type": "object", "description": "The current assets of the company for the given year.", "required": [ "cash_and_equivalents", "short_term_investments", "accounts_receivable", "notes_receivable", "other_debtors", "bad_debt_provision", "tax_recoverable", "inventory", "prepaid_expenses", "assets_available_for_sale", "total" ], "properties": { "cash_and_equivalents": { "type": "number", "format": "float", "nullable": true, "description": "The total amount of cash and cash equivalents, including currency, bank accounts, and other liquid investments that can be quickly converted to cash.", "example": 48572.01 }, "short_term_investments": { "type": "number", "format": "float", "nullable": true, "description": "The value of investments that are expected to be liquidated into cash within one year, such as marketable securities.", "example": 21345.01 }, "accounts_receivable": { "type": "number", "format": "float", "nullable": true, "description": "The amount owed by customers for sales made on credit, expected to be received within a short period.", "example": 154321.01 }, "notes_receivable": { "type": "number", "format": "float", "nullable": true, "description": "The value of written promissory notes received from customers or others, promising to pay a specified amount by a certain date.", "example": 31789.01 }, "other_debtors": { "type": "number", "format": "float", "nullable": true, "description": "The total amounts due from various other debtors, excluding accounts and notes receivable.", "example": 12345.01 }, "bad_debt_provision": { "type": "number", "format": "float", "nullable": true, "description": "The estimated amount of receivables that are expected to be uncollectible, often referred to as allowance for doubtful accounts.", "example": 0.01 }, "tax_recoverable": { "type": "number", "format": "float", "nullable": true, "description": "The amount of tax payments that can be recovered from tax authorities.", "example": 8976.01 }, "inventory": { "type": "number", "format": "float", "nullable": true, "description": "The total value of goods available for sale, raw materials, work-in-progress, and finished products.", "example": 65432.01 }, "prepaid_expenses": { "type": "number", "format": "float", "nullable": true, "description": "The amount paid in advance for goods or services to be received in the future, such as insurance premiums or rent.", "example": 14321.01 }, "assets_available_for_sale": { "type": "number", "format": "float", "nullable": true, "description": "The value of non-current assets that are available for sale but not yet sold, such as surplus equipment or property.", "example": 54321.01 }, "total": { "type": "number", "format": "float", "nullable": true, "description": "The sum of all current assets, representing the total value of assets expected to be converted into cash or used within one year.", "example": 372480.01 } } }, "FinancialStatementBalanceSheetNonCurrentAssets": { "type": "object", "description": "The non-current assets of the company, which are long-term investments or property not easily converted into cash, for the given year.", "required": [ "property_plant_and_equipment", "accumulated_depreciation_and_amortization", "long_term_accounts_receivable", "prepayment_to_suppliers", "goodwill", "intangible_assets", "investments_in_associates", "long_term_financial_instruments", "total" ], "properties": { "property_plant_and_equipment": { "type": "number", "format": "float", "nullable": true, "description": "The total value of property, plant, and equipment owned by the company, including land, buildings, machinery, and vehicles, used for long-term operations.", "example": 1123456.01 }, "accumulated_depreciation_and_amortization": { "type": "number", "format": "float", "nullable": true, "description": "Total accumulated depreciation and amortization, representing the cumulative allocation of the cost of non-current assets over the period they are expected to provide economic benefits.", "example": 123456.01 }, "long_term_accounts_receivable": { "type": "number", "format": "float", "nullable": true, "description": "The amount owed by customers for sales made on credit, expected to be received after one year.", "example": 10987.01 }, "prepayment_to_suppliers": { "type": "number", "format": "float", "nullable": true, "description": "The amount paid in advance to suppliers for goods or services to be received in the future, expected to be utilized over the long term.", "example": 5432.01 }, "goodwill": { "type": "number", "format": "float", "nullable": true, "description": "The value of intangible assets that arise from the acquisition of other companies, representing the premium paid over the fair value of net assets acquired.", "example": 47654.01 }, "intangible_assets": { "type": "number", "format": "float", "nullable": true, "description": "The total value of intangible assets owned by the company, such as patents, trademarks, and copyrights, with useful lives extending beyond one year.", "example": 43210.01 }, "investments_in_associates": { "type": "number", "format": "float", "nullable": true, "description": "The value of investments in other companies in which the company has significant influence but not control, typically represented by ownership of 20-50% of the associate's voting shares.", "example": 65432.01 }, "long_term_financial_instruments": { "type": "number", "format": "float", "nullable": true, "description": "The value of financial instruments that are expected to be held for more than one year, such as bonds, debentures, and long-term loans.", "example": 32876.01 }, "total": { "type": "number", "format": "float", "nullable": true, "description": "The sum of all non-current assets, representing the total value of assets expected to be used or held for more than one year.", "example": 1346647.01 } } }, "FinancialStatementBalanceSheetCurrentLiabilities": { "type": "object", "description": "The current liabilities of the company, expected to be settled within the given year.", "required": [ "bank_loans", "accounts_payable", "notes_payable", "financial_instruments", "other_creditors", "income_tax_payable", "customer_advances", "provisions", "taxes_payable", "total" ], "properties": { "bank_loans": { "type": "number", "format": "float", "nullable": true, "description": "The total amount of loans borrowed from banks or financial institutions, expected to be repaid within one year.", "example": 49876.01 }, "accounts_payable": { "type": "number", "format": "float", "nullable": true, "description": "The amount owed to suppliers for goods or services purchased on credit, expected to be paid within a short period.", "example": 103298.01 }, "notes_payable": { "type": "number", "format": "float", "nullable": true, "description": "The value of written promissory notes issued to suppliers or others, promising to pay a specified amount by a certain date.", "example": 25643.01 }, "financial_instruments": { "type": "number", "format": "float", "nullable": true, "description": "The value of financial instruments that are expected to be liquidated into cash within one year, such as bonds, debentures, and short-term loans.", "example": 14321.01 }, "other_creditors": { "type": "number", "format": "float", "nullable": true, "description": "The total amounts due to various other creditors, excluding accounts and notes payable.", "example": 21987.01 }, "income_tax_payable": { "type": "number", "format": "float", "nullable": true, "description": "The amount of income tax that is owed to tax authorities, expected to be paid within a short period.", "example": 12765.01 }, "customer_advances": { "type": "number", "format": "float", "nullable": true, "description": "The total amount received in advance from customers for goods or services to be delivered in the future, expected to be utilized within one year.", "example": 18765.01 }, "provisions": { "type": "number", "format": "float", "nullable": true, "description": "The estimated amount set aside for future liabilities or losses, such as warranties, legal claims, or restructuring costs.", "example": 10987.01 }, "taxes_payable": { "type": "number", "format": "float", "nullable": true, "description": "The total amount of taxes owed to tax authorities, expected to be paid within a short period.", "example": 5321.01 }, "total": { "type": "number", "format": "float", "nullable": true, "description": "The sum of all current liabilities, representing the total value of obligations expected to be settled within one year.", "example": 260963.01 } } }, "FinancialStatementBalanceSheetNonCurrentLiabilities": { "type": "object", "description": "The non-current liabilities of the company, which are long-term obligations not due within the given year.", "required": [ "long_term_accounts_payable", "long_term_financial_instruments", "deferred_revenue", "contributions_for_future_capital_increases", "deferred_income_tax", "employee_benefits", "long_term_provisions", "total" ], "properties": { "long_term_accounts_payable": { "type": "number", "format": "float", "nullable": true, "description": "The amount owed to suppliers for goods or services purchased on credit, expected to be paid after one year.", "example": 30876.01 }, "long_term_financial_instruments": { "type": "number", "format": "float", "nullable": true, "description": "The value of financial instruments that are expected to be held for more than one year, such as bonds, debentures, and long-term loans.", "example": 42310.01 }, "deferred_revenue": { "type": "number", "format": "float", "nullable": true, "description": "The amount received in advance from customers for goods or services to be delivered in the future, expected to be recognized as revenue over the long term (such as rent).", "example": 21987.01 }, "contributions_for_future_capital_increases": { "type": "number", "format": "float", "nullable": true, "description": "The total contributions received from shareholders or other investors for future capital increases, expected to be utilized over the long term.", "example": 10987.01 }, "deferred_income_tax": { "type": "number", "format": "float", "nullable": true, "description": "The amount of income tax that is deferred to future periods, expected to be paid after one year.", "example": 26543.01 }, "employee_benefits": { "type": "number", "format": "float", "nullable": true, "description": "The total amount of benefits owed to employees, such as pensions, gratuities, and other post-employment benefits, expected to be settled over the long term.", "example": 30218.01 }, "long_term_provisions": { "type": "number", "format": "float", "nullable": true, "description": "The estimated amount set aside for future liabilities or losses, such as warranties, legal claims, or restructuring costs, expected to be settled after one year.", "example": 15432.01 }, "total": { "type": "number", "format": "float", "nullable": true, "description": "The sum of all non-current liabilities, representing the total value of obligations expected to be settled after one year.", "example": 178353.01 } } }, "FinancialStatementBalanceSheetEquity": { "type": "object", "description": "The equity of the company, representing the residual interest in the assets after deducting liabilities.", "required": [ "stockholders_equity", "future_capital_contributions", "legal_reserve", "capital_update_excess", "capital_update_insufficiency", "capital_reserve", "share_premium_on_stock_sales", "retained_earnings", "other_comprehensive_income", "controlling_interest", "non_controlling_interest", "total" ], "properties": { "stockholders_equity": { "type": "number", "format": "float", "nullable": true, "description": "The total value of shares issued by the company, representing the ownership interest of shareholders in the business.", "example": 501234.01 }, "future_capital_contributions": { "type": "number", "format": "float", "nullable": true, "description": "The funds received from shareholders that are specifically designated for future capital increases or investments.", "example": 75000.01 }, "legal_reserve": { "type": "number", "format": "float", "nullable": true, "description": "The statutory reserve mandated by law, typically set aside from profits, to provide financial protection against future losses or obligations.", "example": 25000.01 }, "capital_update_excess": { "type": "number", "format": "float", "nullable": true, "description": "The surplus resulting from adjustments made to equity capital, often due to inflation or the revaluation of assets.", "example": 15000.01 }, "capital_update_insufficiency": { "type": "number", "format": "float", "nullable": true, "description": "The deficit resulting from adjustments made to equity capital, often due to inflation or the revaluation of assets.", "example": -5000.01 }, "capital_reserve": { "type": "number", "format": "float", "nullable": true, "description": "The equity reserve derived from non-operating activities, such as gains from asset revaluations or certain capital transactions.", "example": 10000.01 }, "share_premium_on_stock_sales": { "type": "number", "format": "float", "nullable": true, "description": "The excess amount received by a company when shares are issued at a price above their nominal (par) value.", "example": 50000.01 }, "retained_earnings": { "type": "number", "format": "float", "nullable": true, "description": "The accumulated profits or losses of the company that have not been distributed to shareholders as dividends.", "example": 202345.01 }, "other_comprehensive_income": { "type": "number", "format": "float", "nullable": true, "description": "The gains or losses that are not included in net income but are reported directly in equity, such as unrealized gains on investments or foreign currency translation adjustments.", "example": 10987.01 }, "controlling_interest": { "type": "number", "format": "float", "nullable": true, "description": "The ownership interest in the company held by the parent entity or majority shareholders, representing the controlling stake in the business.", "example": 70876.01 }, "non_controlling_interest": { "type": "number", "format": "float", "nullable": true, "description": "The ownership interest in the company held by minority shareholders, representing the non-controlling stake in the business.", "example": 50321.01 }, "total": { "type": "number", "format": "float", "nullable": true, "description": "The sum of share capital, retained earnings, other comprehensive income, controlling interest, and non-controlling interest, representing the total equity of the company.", "example": 836763.01 } } }, "FinancialStatementBalanceSheet": { "type": "object", "description": "The balance sheet detailing the company's assets, liabilities, and equity for the given year.", "properties": { "current_assets": { "$ref": "#/components/schemas/FinancialStatementBalanceSheetCurrentAssets" }, "non_current_assets": { "$ref": "#/components/schemas/FinancialStatementBalanceSheetNonCurrentAssets" }, "current_liabilities": { "$ref": "#/components/schemas/FinancialStatementBalanceSheetCurrentLiabilities" }, "non_current_liabilities": { "$ref": "#/components/schemas/FinancialStatementBalanceSheetNonCurrentLiabilities" }, "equity": { "$ref": "#/components/schemas/FinancialStatementBalanceSheetEquity" } } }, "FinancialStatementIncomeStatement": { "type": "object", "description": "The income statement detailing the company's revenues, expenses, and profits for the given year.", "required": [ "net_revenue", "domestic_sales", "foreign_sales", "materials_used", "cost_of_goods_sold", "cost_of_services_sold", "gross_profit", "gross_loss", "operating_expenses", "operating_income", "operating_loss", "financial_result", "income_statement_financial_gains", "income_statement_financial_costs", "equity_in_earnings_of_affiliates", "income_before_taxes", "loss_before_taxes", "income_taxes", "income_from_continuing_operations", "loss_from_continuing_operations", "discontinued_operations", "net_income", "net_loss" ], "properties": { "net_revenue": { "type": "number", "format": "float", "nullable": true, "description": "The total revenue generated by the company from its core business operations, excluding any deductions for discounts, returns, or allowances.\n\n> **Note**: `domestic_sales` + `foreign_sales` will not sum to the `net_revenue` due to the exclusion of discounts, returns, and allowances.\n", "example": 1212345.01 }, "domestic_sales": { "type": "number", "format": "float", "nullable": true, "description": "The revenue generated by the company from sales of goods or services within its home country.", "example": 1123456.01 }, "foreign_sales": { "type": "number", "format": "float", "nullable": true, "description": "The revenue generated by the company from sales of goods or services in foreign countries.", "example": 88987.01 }, "materials_used": { "type": "number", "format": "float", "nullable": true, "description": "The total cost of materials used or traded by the company during the reporting period.", "example": 609876.01 }, "cost_of_goods_sold": { "type": "number", "format": "float", "nullable": true, "description": "The total cost incurred by the company to produce or purchase the goods sold during the reporting period.", "example": 412345.01 }, "cost_of_services_sold": { "type": "number", "format": "float", "nullable": true, "description": "The total cost incurred by the company to provide the services sold during the reporting period.", "example": 101234.01 }, "gross_profit": { "type": "number", "format": "float", "nullable": true, "description": "The difference between net revenue and the total cost of goods and services sold, representing the profit earned from core business operations before deducting operating expenses.", "example": 190890.01 }, "gross_loss": { "type": "number", "format": "float", "nullable": true, "description": "The negative difference between net revenue and the total cost of goods and services sold, representing the loss incurred from core business operations before deducting operating expenses.", "example": null }, "operating_expenses": { "type": "number", "format": "float", "nullable": true, "description": "The total expenses incurred by the company in its normal operating activities, including selling, general, and administrative expenses.", "example": 122345.01 }, "operating_income": { "type": "number", "format": "float", "nullable": true, "description": "The profit earned from core business operations after deducting operating expenses, but before considering interest, taxes, and other non-operating items.", "example": 68545.01 }, "operating_loss": { "type": "number", "format": "float", "nullable": true, "description": "The loss incurred from core business operations after deducting operating expenses, but before considering interest, taxes, and other non-operating items.", "example": null }, "financial_result": { "type": "number", "format": "float", "nullable": true, "description": "The net result of financial activities, including interest income, interest expense, and other financial gains or losses.", "example": 15098.01 }, "income_statement_financial_gains": { "type": "number", "format": "float", "nullable": true, "description": "The total positive financial income, including interest income, foreign exchange gains, and other gains from financing activities. This value must always be positive.", "minimum": 0, "example": 85000.01 }, "income_statement_financial_costs": { "type": "number", "format": "float", "nullable": true, "description": "The total financial expenses, including interest expenses, foreign exchange losses, and other costs incurred from financing activities. This value must always be negative.", "maximum": 0, "example": -32000.01 }, "equity_in_earnings_of_affiliates": { "type": "number", "format": "float", "nullable": true, "description": "The company's share of the profit or loss in its associates, entities over which it has significant influence but not control.", "example": 5678.01 }, "income_before_taxes": { "type": "number", "format": "float", "nullable": true, "description": "The profit earned before accounting for income tax expenses.", "example": 89321.01 }, "loss_before_taxes": { "type": "number", "format": "float", "nullable": true, "description": "The loss incurred before accounting for income tax expenses.", "example": null }, "income_taxes": { "type": "number", "format": "float", "nullable": true, "description": "The total amount of income tax expenses incurred during the reporting period.", "example": 20123.01 }, "income_from_continuing_operations": { "type": "number", "format": "float", "nullable": true, "description": "The profit earned from the company's ongoing business operations after deducting operating expenses and taxes.", "example": 69198.01 }, "loss_from_continuing_operations": { "type": "number", "format": "float", "nullable": true, "description": "The loss incurred from the company's ongoing business operations after deducting operating expenses and taxes.", "example": null }, "discontinued_operations": { "type": "number", "format": "float", "nullable": true, "description": "The net result of operations that have been discontinued or sold off during the reporting period.", "example": 0.01 }, "net_income": { "type": "number", "format": "float", "nullable": true, "description": "The total profit earned by the company after deducting all expenses, including operating, non-operating, interest, and taxes.", "example": 69198.01 }, "net_loss": { "type": "number", "format": "float", "nullable": true, "description": "The total loss incurred by the company after deducting all expenses, including operating, non-operating, interest, and taxes.", "example": null } } }, "FinancialStatement": { "type": "object", "description": "The financial statement detailing the company's financial performance for the given year.", "title": "Financial Statement Object (Mexico)", "x-tags": [ "Financial Statements" ], "required": [ "id", "link", "collected_at", "created_at", "error", "year", "currency", "balance_sheet", "income_statement" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "error": { "type": "string", "nullable": true, "description": "In cases where issues arise during the extraction of financial statements from the fiscal institution, the following error messages may be provided to explain the encountered issues:\n \n - `Unable to validate if the user has an available financial statement for the specified year.`\n - `No available financial statement found for the user for the specified year, preventing data extraction.`\n - `Unable to verify if the user has *conceptos vigentes* for the specified year.`\n - `The fiscal institution provided the financial statement in an unrecognized format.`\n", "example": null }, "year": { "type": "string", "pattern": "^\\d{4}$", "description": "The year of the financial statement.", "example": 2020 }, "currency": { "type": "string", "description": "The currency of the financial statement.", "example": "MXN" }, "balance_sheet": { "$ref": "#/components/schemas/FinancialStatementBalanceSheet" }, "income_statement": { "$ref": "#/components/schemas/FinancialStatementIncomeStatement" } } }, "EnumInvoiceSatInvoiceType": { "type": "string", "nullable": true, "enum": [ "Egreso", "Ingreso", "Nómina", "Pago", "Traslado" ], "description": "The fiscal institution's classification of the invoice.\n\nFor Mexico's SAT, we return one of the following values:\n\n - `Egreso`\n - `Ingreso`\n - `Nómina`\n - `Pago`\n - `Traslado`\n", "example": "Ingreso" }, "EnumInvoiceType": { "type": "string", "nullable": true, "enum": [ "OUTFLOW", "INFLOW", null ], "description": "The direction of the invoice (from the perspective of the Link owner).\n- `OUTFLOW` indicates a sent invoice.\n- `INFLOW` indicates a received invoice.\n", "example": "INFLOW" }, "TaxDetailsInvoicesSat": { "type": "object", "description": "General information about the taxes of the invoice.", "properties": { "total_tax_retained": { "type": "number", "format": "float", "description": "Total amount of retained taxes.", "example": 194.27 }, "total_tax_transferred": { "type": "number", "format": "float", "description": "Total amount of transferred taxes.", "example": 150.4 }, "retained_taxes": { "type": "array", "description": "List of retained taxes.", "items": { "type": "object", "properties": { "tax_type": { "type": "string", "nullable": true, "description": "The tax type code for this retained tax, as defined by the legal entity in the country.\n", "example": "Tasa" }, "tax": { "type": "string", "description": "The type of retained tax (for example, ISR, IVA or IEPS).", "example": "ISR" }, "tax_percentage": { "type": "number", "format": "float", "nullable": true, "description": "The percentage of tax retained.", "example": null }, "pre_tax_amount": { "type": "number", "format": "float", "nullable": true, "description": "The amount before tax.", "example": null }, "tax_amount": { "type": "number", "format": "float", "description": "The amount of retained tax.", "example": 94 } } } }, "transferred_taxes": { "type": "array", "description": "List of transferred taxes.", "items": { "type": "object", "properties": { "tax_type": { "type": "string", "nullable": true, "description": "The tax type code (TipoFactor) for this transferred tax, as defined by the legal entity in the country.\n", "example": "Tasa" }, "tax": { "type": "string", "description": "The type of transferred tax (for example, ISR, IVA or IEPS).", "example": "IVA" }, "tax_percentage": { "type": "number", "format": "float", "description": "The percentage of tax transferred.", "example": 16 }, "pre_tax_amount": { "type": "number", "format": "float", "description": "The amount before tax.", "example": 940 }, "tax_amount": { "type": "number", "format": "float", "description": "The amount of transferred tax.", "example": 150.4 } } } } } }, "EnumInvoiceSatPaymentMethod": { "type": "string", "nullable": true, "enum": [ "PUE", "PPD", null ], "description": "The payment method code used for this invoice, as defined by the legal entity of the country.\n\n- 🇲🇽 Mexico SAT catalog reference article. For Mexico, we return `PUE`, `PPD`, or `null`.\n", "example": "PUE" }, "InvoiceDetailRetainedTaxSat": { "type": "object", "required": [ "tax", "tax_percentage", "retained_tax_amount" ], "properties": { "collected_at": { "$ref": "#/components/schemas/collected_at" }, "tax_type": { "type": "string", "nullable": true, "description": "The tax type code for this retained tax, as defined by the legal entity in the country.\n", "example": "Tasa" }, "tax": { "type": "string", "nullable": true, "description": "The type of retained tax (for example, ISR, IVA or IEPS).", "example": "ISR" }, "tax_percentage": { "type": "number", "nullable": true, "format": "float", "description": "The percentage of tax retained.", "example": 10 }, "retained_tax_amount": { "type": "number", "nullable": true, "format": "float", "description": "The amount of retained tax.", "example": 209.79 } } }, "InvoiceDetailTransferredTaxSat": { "type": "object", "required": [ "tax", "tax_percentage", "transferred_tax_amount" ], "properties": { "collected_at": { "$ref": "#/components/schemas/collected_at" }, "tax_type": { "type": "string", "nullable": true, "description": "The tax type code for this transferred tax, as defined by the legal entity in the country.\n", "example": "Tasa" }, "tax": { "type": "string", "nullable": true, "description": "The type of transferred tax (for example, ISR, IVA or IEPS).", "example": "IVA" }, "tax_percentage": { "type": "number", "nullable": true, "format": "float", "description": "The percentage of tax transferred.", "example": 10 }, "transferred_tax_amount": { "type": "number", "nullable": true, "format": "float", "description": "The amount of transferred tax.", "example": 209.79 } } }, "InvoiceDetailSat": { "type": "object", "required": [ "description", "product_identification", "quantity", "unit_amount", "unit_description", "unit_code", "pre_tax_amount", "tax_percentage", "tax_amount", "total_amount" ], "properties": { "collected_at": { "$ref": "#/components/schemas/collected_at" }, "description": { "type": "string", "nullable": true, "description": "The description of the invoice item (an invoice can have one or more items).\n", "example": "December 2019 accounting fees" }, "product_identification": { "type": "string", "nullable": true, "description": "The identification code of the product or the service, as defined by the legal entity in the country.\\n- \\U0001F1F2\\U0001F1FD Mexico.", "example": "84101600" }, "quantity": { "type": "number", "nullable": true, "format": "float", "description": "The quantity of this invoice item.", "example": 10 }, "unit_code": { "type": "string", "nullable": true, "description": "The unit of measure, as defined by the legal entity in the country. \\n- \\U0001F1F2\\U0001F1FD Mexico SAT catalog reference.", "example": "E48" }, "unit_description": { "type": "string", "nullable": true, "description": "The description of the item, as defined by the legal entity in the country.\\n- \\U0001F1F2\\U0001F1FD Mexico SAT catalog reference.", "example": "Unidad de servicio" }, "unit_amount": { "type": "number", "nullable": true, "format": "float", "description": "The price of one a singular item.", "example": 200 }, "discount": { "type": "number", "nullable": true, "format": "float", "description": "The discount amount applied to this invoice item.\n", "example": 10 }, "tax_subject_code": { "type": "string", "nullable": true, "description": "Indicates what tax this item is subject to, as defined by the legal entity in the country.\n", "example": "02" }, "identifier_number": { "type": "string", "nullable": true, "description": "The identification number of the item, as defined by the seller. This can be used to identify the product or service in the seller's system.\n", "example": "PROD-12345" }, "pre_tax_amount": { "type": "number", "nullable": true, "format": "float", "description": "The total price for this item before tax is applied (`quantity` x `unit_amount`).\n", "example": 400 }, "tax_percentage": { "type": "number", "nullable": true, "format": "float", "description": "The tax percentage to apply.", "example": 16 }, "tax_amount": { "type": "number", "nullable": true, "format": "float", "description": "The amount of tax for this invoice item (`pre_tax_amount` x `tax_percentage`).\n", "example": 64 }, "total_amount": { "type": "number", "nullable": true, "format": "float", "description": "The total price for this invoice item (`pre_tax_amount` + `tax_amount`).", "example": 464 }, "retained_taxes": { "type": "array", "description": "The retained tax on the invoice item.", "items": { "$ref": "#/components/schemas/InvoiceDetailRetainedTaxSat" } }, "transferred_taxes": { "type": "array", "description": "The transferred taxes related to the invoice.", "items": { "$ref": "#/components/schemas/InvoiceDetailTransferredTaxSat" } } } }, "RelatedInvoiceSat": { "type": "object", "description": "Related invoice item.", "properties": { "relationship_type": { "type": "string", "nullable": true, "description": "The type of relationship between this invoice and the related invoice, as defined by the legal entity in the country. For more information, see our SAT catalog reference article.", "example": "01" }, "related_invoice_identification": { "type": "string", "nullable": true, "description": "The SAT ID of the related invoice.", "example": "INV-123456" } } }, "InvoicesPaymentsRelatedDocumentsSat": { "type": "object", "required": [ "invoice_identification", "currency", "payment_method", "previous_balance", "amount_paid", "outstanding_balance" ], "description": "List of all the related deferred invoices affected by the payment.", "properties": { "invoice_identification": { "type": "string", "nullable": true, "description": "The fiscal institution's unique ID for the related deferred invoice.\n", "example": "7EE015F3-6311-11EA-B02A-00155D014007" }, "currency": { "type": "string", "nullable": true, "description": "The currency of the related invoice. For example:\n \n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n \n Please note that other currencies other than in the list above may be returned.\n", "example": "MXN" }, "payment_method": { "type": "string", "nullable": true, "description": "The payment method of the related invoice.\n", "example": "PPD" }, "partiality_number": { "type": "integer", "format": "int32", "description": "The payment installment number.\n", "example": 1 }, "previous_balance": { "type": "number", "nullable": true, "format": "float", "description": "The invoice amount before the payment.\n", "example": 18877.84 }, "amount_paid": { "type": "number", "nullable": true, "format": "float", "description": "The amount paid in this installment.\n", "example": 8000 }, "outstanding_balance": { "type": "number", "nullable": true, "format": "float", "description": "The amount remaining to be paid.\n", "example": 10877.84 } } }, "InvoicesPaymentsSat": { "type": "object", "required": [ "date", "payment_type", "currency", "exchange_rate", "amount", "operation_number", "beneficiary_account_number", "payer_rfc", "payer_account_number", "payer_bank_name", "related_documents" ], "properties": { "date": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO-8601 timestamp when the payment was made.\n", "example": "2020-03-17T12:00:00.000Z" }, "payment_type": { "type": "string", "nullable": true, "description": "Payment type code used for this invoice, as defined by the country's legal entity.\n\n- 🇲🇽 Mexico SAT catalog reference article\n", "example": "03" }, "currency": { "type": "string", "nullable": true, "description": "The currency of the payment. For example:\n\n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n\nPlease note that other currencies other than in the list above may be returned.\n", "example": "BRL" }, "exchange_rate": { "type": "string", "nullable": true, "description": "The `currency` to MXN currency exchange rate when the payment was made.\n", "example": "3.75" }, "amount": { "type": "number", "nullable": true, "format": "float", "description": "The invoice amount, in the currency of the original invoice.\n", "example": 8000.5 }, "operation_number": { "type": "string", "nullable": true, "description": "The fiscal institution's internal identifier for the operation.\n", "example": "831840" }, "beneficiary_rfc": { "type": "string", "nullable": true, "description": "The fiscal ID of the payment beneficiary.\n", "example": "BNM840515VB1" }, "beneficiary_account_number": { "type": "string", "nullable": true, "description": "The bank account number of the payment beneficiary.\n", "example": "12343453245633" }, "payer_rfc": { "type": "string", "nullable": true, "description": "The fiscal ID of the payment issuer.\n", "example": "BKJM840515VB1" }, "payer_account_number": { "type": "string", "nullable": true, "description": "The bank account number of the payment issuer.\n", "example": "13343663245699" }, "payer_bank_name": { "type": "string", "nullable": true, "description": "The banking institution that was used by the payment issuer.\n", "example": "CITI BANAMEX" }, "related_documents": { "type": "array", "description": "A list of all the related deferred invoices affected by the payment.\n", "items": { "$ref": "#/components/schemas/InvoicesPaymentsRelatedDocumentsSat" } } } }, "EnumInvoicePayrollPeriodicity": { "type": "string", "nullable": true, "enum": [ "DAILY", "WEEKLY", "TENTH_DAY", "FOURTEENTH_DAY", "FIFTEENTH_DAY", "MONTHLY", "BIMONTHLY", "PER_TASK", "COMMISSION", "ONE_OFF", "OTHER_PERIODICITY", "null" ], "description": "How often the payroll payment is made.\n\nFor Mexico's SAT, we return one of the following values:\n\n - `DAILY`\n - `WEEKLY`\n - `TENTH_DAY`\n - `FOURTEENTH_DAY`\n - `FIFTEENTH_DAY`\n - `MONTHLY`\n - `BIMONTHLY`\n - `PER_TASK`\n - `COMMISSION`\n - `ONE_OFF`\n - `OTHER_PERIODICITY`\n", "example": "MONTHLY" }, "InvoicePayrollEarningsBreakdown": { "type": "object", "nullable": true, "description": "A breakdown of the earnings for the payroll payment.", "properties": { "type": { "type": "string", "nullable": true, "description": "The type of income. For a full list of possible values, please see the payroll earnings breakdown type table.\n", "example": "CHRISTMAS_BONUS" }, "taxable_amount": { "type": "number", "format": "float", "description": "The amount of the income that is taxable.\n", "example": 1505 }, "vat_free_amount": { "type": "number", "format": "float", "description": "The amount of the income that is not subject to VAT.\n", "example": 0 } } }, "InvoicePayrollTaxDeductions": { "type": "object", "nullable": true, "description": "A breakdown of the tax deductions on the payroll payment.", "properties": { "type": { "type": "string", "nullable": true, "description": "The type of tax deduction. For a full list of possible values, please see the payroll tax deductions type table.\n", "example": "UNION_FEES" }, "amount": { "type": "number", "format": "float", "description": "The amount of the tax deduction.\n", "example": 1505 } } }, "InvoicePayrollOtherPayments": { "type": "object", "nullable": true, "description": "A breakdown of other payments for the payroll.", "properties": { "type": { "type": "string", "nullable": true, "description": "The type of other payment. For a full list of possible values, please see the payroll other payments type table.\n", "example": "EMPLOYMENT_SUBSIDY" }, "amount": { "type": "number", "format": "float", "description": "The amount of the other payment.\n", "example": 1505 } } }, "InvoicesPayrollSat": { "type": "object", "nullable": true, "required": [ "version", "type", "payment_date", "date_from", "date_to", "days", "amount" ], "description": "Details regarding the payroll payment. Only applicable for payroll invoices.\n", "properties": { "days": { "type": "integer", "nullable": true, "format": "int32", "description": "The number of days covered by the payment.\n", "example": 30 }, "type": { "type": "string", "nullable": true, "description": "The payroll type, as defined by the legal entity of the country.\n\n- 🇲🇽 Mexico SAT catalog reference article\n", "example": "O" }, "amount": { "type": "number", "format": "float", "description": "The total amount of the payroll payment.\n", "example": 20400.1 }, "version": { "type": "string", "description": "The version of the payroll object.\n", "example": "1.2" }, "date_from": { "type": "string", "nullable": true, "format": "date", "description": "The start date of the payment period, in `YYYY-MM-DD` format.\n", "example": "2018-07-01" }, "date_to": { "type": "string", "nullable": true, "format": "date", "description": "The end date of the payment period, in `YYYY-MM-DD` format.\n", "example": "2018-07-31" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "payment_date": { "type": "string", "format": "date", "description": "The payment date, in `YYYY-MM-DD` format.\n", "example": "2018-07-16" }, "periodicity": { "$ref": "#/components/schemas/EnumInvoicePayrollPeriodicity" }, "earnings_breakdown": { "type": "array", "nullable": true, "description": "A breakdown of the earnings for the payroll payment.\n", "items": { "$ref": "#/components/schemas/InvoicePayrollEarningsBreakdown" } }, "tax_deductions": { "type": "array", "nullable": true, "description": "A breakdown of the tax deductions on the payroll payment.\n", "items": { "$ref": "#/components/schemas/InvoicePayrollTaxDeductions" } }, "other_payments": { "type": "array", "nullable": true, "description": "A breakdown of other payments for the payroll.\n", "items": { "$ref": "#/components/schemas/InvoicePayrollOtherPayments" } } } }, "InvoiceWarningsSat": { "type": "object", "nullable": true, "required": [ "code", "message" ], "description": "Object containing information about any warnings related to this invoice.\n", "properties": { "code": { "type": "string", "nullable": true, "description": "The warning code. Can be one of:\n\n - `sat_xml_limit_reached`\n - `sat_service_unavailable`\n - `null`\n", "example": "sat_xml_limit_reached" }, "message": { "type": "string", "nullable": true, "description": "The description of the warning.\n\nThe message will depend on the warning code:\n\n`sat_xml_limit_reached`
\nThe daily limit for XML downloads set by SAT was reached so this invoice might be missing data. Please check https://tinyurl.com/yydzhy5d for more information on this error.\n\n`sat_service_unavailable`
\nDownloading invoices details is not available. The SAT portal raised a 503 error.\n", "example": "The daily limit for XML downloads set by SAT was reached so this invoice\nmight be missing data. Please check https://tinyurl.com/yydzhy5d for more\ninformation on this error.\n" } } }, "InvoiceWithIdSat": { "type": "object", "title": "Invoices Object (Mexico)", "x-tags": [ "Invoices" ], "required": [ "type", "invoice_identification", "invoice_date", "invoice_type", "subtotal_amount", "tax_amount", "discount_amount", "total_amount", "currency", "exchange_rate", "status", "sender_name", "sender_id", "receiver_name", "receiver_id", "certification_authority", "certification_date", "cancelation_status", "cancelation_update_date", "payment_type", "payment_type_description", "invoice_details", "payroll", "payments", "collected_at" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "invoice_identification": { "type": "string", "nullable": true, "description": "The fiscal institution's unique ID for the invoice.", "example": "A1A1A1A1-2B2B-3C33-D44D-555555E55EE" }, "invoice_date": { "type": "string", "nullable": true, "description": "The date of the invoice, in `YYYY-MM-DD` format.", "example": "2019-12-01" }, "status": { "type": "string", "nullable": true, "description": "The status of the invoice. Can be either *Vigente* (valid) or *Cancelado*\n(cancelled).\n", "example": "Vigente" }, "invoice_type": { "$ref": "#/components/schemas/EnumInvoiceSatInvoiceType" }, "type": { "$ref": "#/components/schemas/EnumInvoiceType" }, "tax_details": { "$ref": "#/components/schemas/TaxDetailsInvoicesSat" }, "sender_id": { "type": "string", "nullable": true, "description": "The fiscal ID of the invoice sender", "example": "AAA111111AA11" }, "sender_fiscal_regime": { "type": "string", "nullable": true, "description": "The tax regime of the sender, as defined by the legal entity in the country.", "example": "601" }, "sender_name": { "type": "string", "nullable": true, "description": "The name of the invoice sender.", "example": "ACME CORP" }, "sender_tax_fraud_status": { "type": "string", "nullable": true, "description": "Indicates whether or not the sender is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.

\n\nSAT updates the tax fraud list every three months.

\n\nFor more information regarding the reason's a taxpayer can be put on the tax fraud list, please see Article 69 and Article 69-B of Mexico's Código Fiscal de la Federación.\n

\n\nPossible statuses are:\n\n- `INVESTIGATING`
\nThe fiscal institution has identified irregularities and open an investigation regarding the taxpayer.\n
\n- `DISMISSED`
\nThe fiscal institution has investigated the taxpayer and declared them innocent.\n
\n- `CONFIRMED`
\nThe fiscal institution has confirmed that the taxpayer is guilty.\n
\n- `OVERTURNED`
\nThe fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.\n
\n- `NO_TAX_FRAUD_STATUS`
\nThe receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).\n", "example": "NO_TAX_FRAUD_STATUS" }, "receiver_id": { "type": "string", "nullable": true, "description": "The fiscal ID of the invoice receiver.", "example": "BBB222222BB22" }, "receiver_postal_code": { "type": "string", "description": "The postal code of the receiver.", "example": "11560" }, "receiver_fiscal_regime": { "type": "string", "nullable": true, "description": "The tax regime of the receiver, as defined by the legal entity in the country.", "example": "601" }, "receiver_name": { "type": "string", "nullable": true, "description": "The name of the invoice receiver.", "example": "BELVO CORP" }, "receiver_tax_fraud_status": { "type": "string", "nullable": true, "description": "Indicates whether or not the receiver is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.

\n\nSAT updates the tax fraud list every three months.

\n\nFor more information regarding the reason's a taxpayer can be put on the tax fraud list, please see Article 69 and Article 69-B of Mexico's Código Fiscal de la Federación.\n

\n\nPossible statuses are:\n\n- `INVESTIGATING`
\nThe fiscal institution has identified irregularities and open an investigation regarding the taxpayer.\n
\n- `DISMISSED`
\nThe fiscal institution has investigated the taxpayer and declared them innocent.\n
\n- `CONFIRMED`
\nThe fiscal institution has confirmed that the taxpayer is guilty.\n
\n- `OVERTURNED`
\nThe fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.\n
\n- `NO_TAX_FRAUD_STATUS`
\nThe receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).\n", "example": "NO_TAX_FRAUD_STATUS" }, "cancelation_status": { "type": "string", "nullable": true, "description": "If the invoice is cancelled, this field indicates the status of the cancellation.\n" }, "cancelation_update_date": { "type": "string", "nullable": true, "format": "date", "description": "The date of the invoice cancelation, in `YYYY-MM-DD` format.\n", "example": "2019-12-02" }, "certification_date": { "type": "string", "nullable": true, "format": "date", "description": "The date of the fiscal certification, in `YYYY-MM-DD` format.\n", "example": "2019-12-01" }, "certification_authority": { "type": "string", "nullable": true, "description": "The fiscal ID of the certification provider.\n", "example": "CCC333333CC33" }, "payment_type": { "type": "string", "nullable": true, "description": "The payment type code used for this invoice, as defined by the country legal entity.\n\n- 🇲🇽 Mexico SAT catalog reference article\n", "example": "99" }, "payment_type_description": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\n", "example": null }, "payment_method": { "$ref": "#/components/schemas/EnumInvoiceSatPaymentMethod" }, "payment_method_description": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\n\n*The description of the payment method used for this invoice.*\n", "example": null }, "usage": { "type": "string", "nullable": true, "description": "The invoice's usage code, as defined by the legal entity of the country. \n\n- 🇲🇽 Mexico SAT catalog reference article\n", "example": "P01" }, "version": { "type": "string", "nullable": true, "description": "The CFDI version of the invoice.\n", "example": "3.3" }, "place_of_issue": { "type": "string", "nullable": true, "description": "The postcode of where the invoice was issued.\n", "example": "01165" }, "invoice_details": { "type": "array", "description": "A list of descriptions for each item (purchased product or service provided) in the invoice.\n", "items": { "$ref": "#/components/schemas/InvoiceDetailSat" } }, "currency": { "type": "string", "nullable": true, "description": "The currency of the invoice. For example:\n \n - 🇧🇷 BRL (Brazilian Real)\n - 🇨🇴 COP (Colombian Peso)\n - 🇲🇽 MXN (Mexican Peso)\n - 🇺🇸 USD (United States Dollar)\n", "example": "MXN" }, "subtotal_amount": { "type": "number", "nullable": true, "format": "float", "description": "The pretax amount of this invoice (sum of each item's `pre_tax_amount`).\n", "example": 400 }, "exchange_rate": { "type": "number", "nullable": true, "format": "float", "description": "The exchange rate used in this invoice for the currency.\n", "example": 0.052 }, "tax_amount": { "type": "number", "nullable": true, "format": "float", "description": "The amount of tax for this invoice (sum of each item's `tax_amount`).\n", "example": 64 }, "discount_amount": { "type": "number", "nullable": true, "format": "float", "description": "The total amount discounted in this invoice.\n", "example": 10 }, "total_amount": { "type": "number", "nullable": true, "format": "float", "description": "The total amount of the invoice (`subtotal_amount` + `tax_amount` - `discount_amount`)\n", "example": 454 }, "related_invoices": { "type": "array", "description": "A list of related invoices.", "items": { "$ref": "#/components/schemas/RelatedInvoiceSat" } }, "payments": { "type": "array", "description": "A list detailing all the invoice payments.\n", "items": { "$ref": "#/components/schemas/InvoicesPaymentsSat" } }, "payroll": { "$ref": "#/components/schemas/InvoicesPayrollSat" }, "folio": { "type": "string", "nullable": true, "description": "The internal control number that the taxpayer assigns to the invoice.\n", "example": "26" }, "series": { "type": "string", "nullable": true, "description": "The series of the invoice, as defined by the taxpayer. This is an optional field used to group invoices.\n", "example": "A" }, "export_type": { "type": "string", "nullable": true, "description": "The export type of the invoice, as defined by the legal entity in the country. For more information, see our SAT catalog reference article.", "example": "01" }, "xml": { "type": "string", "nullable": true, "description": "XML of the invoice document.\n" }, "warnings": { "$ref": "#/components/schemas/InvoiceWarningsSat" }, "sender_blacklist_status": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\nPlease use `sender_tax_fraud_status` instead.\n", "example": null }, "receiver_blacklist_status": { "type": "string", "nullable": true, "deprecated": true, "description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.*\nPlease use `receiver_tax_fraud_status` instead.\n", "example": null } } }, "attach_xml": { "type": "boolean", "default": false, "description": "When set to `true`, you will receive the XML invoice in the response.", "example": false }, "EnumTaxComplianceStatusOutcome": { "type": "string", "nullable": true, "enum": [ "POSITIVE", "NEGATIVE", "NO_OBLIGATIONS" ], "description": "Indicates whether the taxpayer is complying to all their tax obligations\n(`POSITIVE`), if they are not (`NEGATIVE`), or have none to comply to\n(`NO_OBLIGATIONS`).\n", "example": "NEGATIVE" }, "TaxComplianceStatus": { "type": "object", "title": "Tax Compliance Status Object (Mexico)", "x-tags": [ "Tax compliance status" ], "required": [ "pdf", "collected_at" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "internal_identification": { "type": "string", "nullable": true, "description": "The institution’s internal identification number for the document.", "example": "20NE1234567" }, "pdf": { "type": "string", "nullable": true, "format": "binary", "description": "Tax compliance status PDF as a binary.", "example": "=PDF-STRING=" }, "rfc": { "type": "string", "nullable": true, "description": "The account holder's RFC (Registro Federal de Contribuyentes) number.", "example": "KDFC211118IS0" }, "outcome": { "$ref": "#/components/schemas/EnumTaxComplianceStatusOutcome" } } }, "TaxReturnPersonal": { "type": "object", "additionalProperties": true, "title": "Tax Return Personal (Yearly)", "x-tags": [ "Tax returns" ], "required": [ "informacion_general", "sueldos_salarios", "servicios_profesionales", "dividendos", "deducciones_personales", "retenciones", "determinacion_impuesto", "pdf", "receipt_pdf", "collected_at" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "informacion_general": { "type": "object", "nullable": true, "description": "General information on the tax return (year, RFC, return type,\nperson/company name, and so on).\n" }, "sueldos_salarios": { "type": "object", "nullable": true, "description": "Details regarding the income information together combined with withheld\ntaxes.\n" }, "servicios_profesionales": { "type": "object", "nullable": true, "description": "Details regarding the income and tax information from professional\nservices provided.\n" }, "deducciones_personales": { "type": "object", "nullable": true, "description": "List of all personal tax deductions." }, "determinacion_impuesto": { "type": "object", "nullable": true, "description": "Details regarding the final tax return." }, "retenciones": { "type": "object", "nullable": true, "description": "Details on the already withheld taxes." }, "dividendos": { "type": "object", "nullable": true, "description": "Details regarding dividends." }, "datos_informativos": { "type": "object", "nullable": true, "description": "Extra informative data on the tax return." }, "pdf": { "type": "string", "nullable": true, "format": "binary", "description": "Tax return PDF as a binary.", "example": "=PDF-STRING=" }, "receipt_pdf": { "type": "string", "nullable": true, "format": "binary", "description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n", "example": "=PDF-STRING=" } } }, "TaxReturnPersonalMonthly": { "type": "object", "additionalProperties": true, "title": "Tax Return Personal (Monthly)", "x-tags": [ "Tax returns" ], "required": [ "informacion_general", "pdf", "type", "isr", "iva", "collected_at" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "informacion_general": { "type": "object", "nullable": true, "description": "General information regarding the tax return (year, RFC, return type,\nperson/company name, and so on).\n" }, "isr": { "type": "object", "nullable": true, "description": "Information used to calculate the monthly provisional payments of the\nincome tax.\n" }, "iva": { "type": "object", "nullable": true, "description": "Information used to calculate the monthly provisional payments of the VAT\ntax.\n" }, "pdf": { "type": "string", "nullable": true, "format": "binary", "description": "Tax return PDF as a binary.", "example": "=PDF-STRING=" }, "receipt_pdf": { "type": "string", "nullable": true, "format": "binary", "description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n", "example": "=PDF-STRING=" }, "type": { "type": "string", "description": "The type of tax return. Can be either monthly or annual.", "example": "monthly" } } }, "TaxReturnBusiness": { "type": "object", "additionalProperties": true, "title": "Tax Return Business (Yearly)", "x-tags": [ "Tax returns" ], "required": [ "id", "collected_at", "created_at", "informacion_general", "datos_adicionales", "estado_resultados", "estado_posicion_financiera_balance", "conciliacion_entre_resultado_contable_fiscal", "deducciones_autorizadas", "cifras_cierre_ejercicio", "determinacion_del_impuesto_sobre_la_renta", "dividendos_o_utilidades_distribuidos", "detalle_pago_r1_isr_personas_morales", "pdf", "receipt_pdf" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "informacion_general": { "type": "object", "nullable": true, "description": "General information regarding the tax return (year, RFC, return type,\nperson/company name, and so on).\n" }, "datos_adicionales": { "type": "object", "nullable": true, "description": "Additional data regarding the tax return." }, "estado_resultados": { "type": "object", "nullable": true, "description": "Detailed information about the legal entity's yearly profit and loss.\n\n> **Note**: For tax returns submitted for the 2022 tax year and later, this field will return null as it is no longer a required field when submitting your tax return.\n" }, "estado_posicion_financiera_balance": { "type": "object", "nullable": true, "description": "Details regarding balance sheet of the legal entity.\n\n> **Note**: For tax returns submitted for the 2022 tax year and later, this field will return null as it is no longer a required field when submitting your tax return.\n" }, "conciliacion_entre_resultado_contable_fiscal": { "type": "object", "nullable": true, "description": "Details regarding the accounting reconciliation.\n\n> **Note**: For tax returns submitted for the 2022 tax year and later, this field will return null as it is no longer a required field when submitting your tax return.\n" }, "deducciones_autorizadas": { "type": "object", "nullable": true, "description": "Details regarding the legal entity's deductions." }, "cifras_cierre_ejercicio": { "type": "object", "nullable": true, "description": "Details regarding key numbers at the end of the fiscal exercise." }, "determinacion_del_impuesto_sobre_la_renta": { "type": "object", "nullable": true, "description": "Details regarding the final tax return." }, "dividendos_o_utilidades_distribuidos": { "type": "object", "nullable": true, "description": "Details regarding distributed dividends." }, "detalle_pago_r1_isr_personas_morales": { "type": "object", "nullable": true, "description": "Details of the tax payment." }, "ingressos": { "type": "object", "nullable": true, "description": "> **Note**: Only applicable for tax return filed on or after 2022. For tax returns filed before 2022, this field will return `null`.\n\nDetails regarding the total amounts earned in the fiscal year.\n" }, "determinacion": { "type": "object", "nullable": true, "description": "> **Note**: Only applicable for tax return filed on or after 2022. For tax returns filed before 2022, this field will return `null`.\n\nDetails regarding the tax due or tax credit.\n" }, "pdf": { "type": "string", "nullable": true, "format": "binary", "description": "Tax return PDF as a binary.", "example": "=PDF-STRING=" }, "receipt_pdf": { "type": "string", "nullable": true, "format": "binary", "description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n", "example": "=PDF-STRING=" } } }, "TaxReturnBusinessMonthly": { "type": "object", "additionalProperties": true, "title": "Tax Return Business (Monthly)", "x-tags": [ "Tax returns" ], "required": [ "informacion_general", "determinacion_isr", "pdf", "type", "collected_at", "detalle_pago_isr", "determinacion_iva", "detalle_pago_iva" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "informacion_general": { "type": "object", "nullable": true, "description": "General information regarding the tax return (year, RFC, return type,\nperson/company name, and so on).\n" }, "determinacion_isr": { "type": "object", "nullable": true, "description": "Information used to calculate the provisional income tax for the period." }, "detalle_pago_isr": { "type": "object", "nullable": true, "description": "Information on the monthly provisional payments for the income tax." }, "determinacion_iva": { "type": "object", "nullable": true, "description": "Information used to calculate the provisional VAT tax for the period." }, "detalle_pago_iva": { "type": "object", "nullable": true, "description": "Information on the monthly provisional payments for the VAT tax." }, "pdf": { "type": "string", "nullable": true, "format": "binary", "description": "Tax return PDF as a binary.", "example": "=PDF-STRING=" }, "receipt_pdf": { "type": "string", "nullable": true, "format": "binary", "description": "The acknowledgement receipt from the fiscal institution confirming that\nthey received the tax return.\n", "example": "=PDF-STRING=" }, "type": { "type": "string", "nullable": true, "description": "The type of tax return. Can be either monthly or annual.", "example": "monthly" } } }, "TaxReturnsMonthlyRequest": { "type": "object", "title": "Monthly Tax Returns", "description": "Request body for monthly tax returns", "required": [ "link", "type", "date_from", "date_to" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" }, "type": { "type": "string", "default": "monthly", "description": "The type of tax return to return. For monthly tax returns, this field must be set to `monthly`.\n" }, "date_from": { "$ref": "#/components/schemas/date_from" }, "date_to": { "$ref": "#/components/schemas/date_to" } } }, "TaxReturnsYearlyRequest": { "type": "object", "title": "Yearly Tax Returns", "description": "Request body for yearly tax returns", "required": [ "link", "type", "year_to", "year_from" ], "properties": { "link": { "$ref": "#/components/schemas/link_request" }, "attach_pdf": { "$ref": "#/components/schemas/attach_pdf" }, "save_data": { "$ref": "#/components/schemas/save_data" }, "type": { "type": "string", "default": "yearly", "description": "The type of tax return to return. For yearly tax returns this must be set to `yearly`.\n\nBy default, Belvo returns the yearly (annual) tax returns.\n" }, "year_from": { "type": "string", "pattern": "^(19|20)\\d{2}$", "description": "The starting year you want to get data for, in `YYYY` format.", "example": "2018" }, "year_to": { "type": "string", "pattern": "^(19|20)\\d{2}$", "description": "The year you want to stop getting data for, in `YYYY` format.", "example": "2019" } } }, "EnumTaxRetentionReceiverNationality": { "type": "string", "nullable": true, "enum": [ "NATIONAL", "FOREIGN" ], "description": "Whether the invoice receiver is a Mexican national or not. If the receiver is not considered a Mexican national, the retained taxes can be calculated differently. Possible values:\n - `NATIONAL`\n - `FOREIGN`\n", "example": "NATIONAL" }, "EnumTaxRetentionPaymentStatus": { "type": "string", "nullable": true, "enum": [ "PAID", "PROVISIONED" ], "description": "Indicates whether or not the tax has been paid or not. Can be either:\n - `PAID`\n - `PROVISIONED`\n", "example": "PAID" }, "RetentionBreakdown": { "type": "object", "required": [ "base_amount", "tax_type", "retained_amount", "payment_status" ], "description": "A breakdown of the retained taxes", "properties": { "base_amount": { "type": "number", "nullable": true, "format": "float", "description": "The base amount that was used to calculate the tax retention.\n", "example": 0.03 }, "tax_type": { "type": "string", "nullable": true, "description": "Optional attribute to indicate the type of tax withheld for the period or year according to the SAT catalog.\n", "example": "01" }, "retained_amount": { "type": "number", "nullable": true, "format": "float", "description": "The amount retained.\n", "example": 0 }, "payment_status": { "$ref": "#/components/schemas/EnumTaxRetentionPaymentStatus" } } }, "TaxRetentions": { "type": "object", "title": "Tax Retentions Object (Mexico)", "x-tags": [ "Tax retentions" ], "required": [ "collected_at", "invoice_identification", "version", "code", "issued_at", "certified_at", "cancelled_at", "sender_id", "sender_name", "receiver_nationality", "receiver_id", "receiver_name", "total_invoice_amount", "total_taxable_amount", "total_exempt_amount", "total_retained_amount", "retention_breakdown", "xml" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "invoice_identification": { "type": "string", "nullable": true, "format": "uuid", "description": "The fiscal institution's unique ID for the invoice that the tax retention relates to.\n", "example": "def404af-5eef-4112-aa99-d1ec8493b89a" }, "version": { "type": "string", "nullable": true, "description": "The CFDI version of the tax retentions.\n", "example": "1.0" }, "code": { "type": "integer", "nullable": true, "format": "int32", "description": "The tax retention code. For more information, see our SAT Catalogs DevPortal article.\n", "example": 25 }, "issued_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the tax retention was issued.\n", "example": "2019-01-03T21:10:40.000Z" }, "certified_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the tax retention was certified.\n", "example": "2019-01-03T21:10:41.000Z" }, "cancelled_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the tax retention was canceled (if applicable).\n", "example": null }, "sender_id": { "type": "string", "nullable": true, "description": "The fiscal ID of the invoice sender.\n", "example": "JKUF980404P0" }, "sender_name": { "type": "string", "nullable": true, "description": "The name of the invoice sender.\n", "example": "Roberto Nunez Batman" }, "receiver_nationality": { "$ref": "#/components/schemas/EnumTaxRetentionReceiverNationality" }, "receiver_id": { "type": "string", "nullable": true, "description": "The fiscal ID of the invoice receiver.\n", "example": "GYGK3207809L1" }, "receiver_name": { "type": "string", "nullable": true, "description": "The name of the invoice receiver.\n", "example": "ACME LTD" }, "total_invoice_amount": { "type": "number", "nullable": true, "format": "float", "description": "The total amount of the invoice that the tax retention relates to.\n", "example": 53249.8 }, "total_exempt_amount": { "type": "number", "nullable": true, "format": "float", "description": "Total amount that is exempt from taxation.\n", "example": 1000.8 }, "total_retained_amount": { "type": "number", "nullable": true, "format": "float", "description": "Total tax retained.\n", "example": 1550.7 }, "total_taxable_amount": { "type": "number", "nullable": true, "format": "float", "description": "The total amount that can be taxed. Calculated as `total_invoice_amount` - `total_exempt_amount`.\n", "example": 43249 }, "retention_breakdown": { "type": "array", "nullable": true, "description": "A breakdown of the retained taxes.\n", "items": { "$ref": "#/components/schemas/RetentionBreakdown" } }, "xml": { "type": "string", "nullable": true, "description": "The tax retention document in XML form.\n", "example": "=XML-STRING=" } } }, "EnumTaxRetentionType": { "type": "string", "enum": [ "OUTFLOW", "INFLOW" ], "description": "The type of tax retention in relation to the invoice (from the perspective of the Link owner).\n\n- `OUTFLOW` relates to a tax retention for a sent invoice.\n- `INFLOW` related to a tax retention for a received invoice.\n", "example": "INFLOW" }, "TaxStatusTaxPayerInformationSat": { "type": "object", "nullable": true, "required": [ "rfc", "start_operations_date", "status_padron", "last_status_change_date" ], "description": "Details regarding the taxpayer.", "properties": { "rfc": { "type": "string", "nullable": true, "description": "The tax payers's identification number (For Mexico, this is the RFC).\n", "example": "BEMP12345G58" }, "curp": { "type": "string", "nullable": true, "description": "The tax payers's *Clave Única de Registro de Población* (CURP) number.\n", "example": null }, "name": { "type": "string", "nullable": true, "description": "The tax payers's first name.", "example": "JOHN" }, "first_last_name": { "type": "string", "nullable": true, "description": "The tax payers's first last name.", "example": "DOE" }, "second_last_name": { "type": "string", "nullable": true, "description": "The tax payers's second last name.", "example": "SCHMOE" }, "start_operations_date": { "type": "string", "nullable": true, "format": "date", "description": "Date when the tax payer commenced taxable commercial activities, in `YYYY-MM-DD` format.\n", "example": null }, "status_padron": { "type": "string", "nullable": true, "description": "Status of the taxpayer in the Federal Register of Taxpayers (RFC). Can be `ACTIVO` or `INACTIVO`.\n", "example": null }, "last_status_change_date": { "type": "string", "nullable": true, "format": "date", "description": "Date when `status_padron` was most recently updated, in `YYYY-MM-DD` format.\n", "example": null }, "commercial_name": { "type": "string", "nullable": true, "description": "The name of the business designated for consumers and the general public.\n\n**Note**: Only applicable for businesses.\n", "example": "Jar Jar Transport" }, "social_name": { "type": "string", "nullable": true, "description": "The unique and exclusive name within the national territory that companies\nreceive for legal or administrative purposes.\n\n**Note**: Only applicable for businesses.\n", "example": "John Doe SA DE CV" }, "email": { "type": "string", "nullable": true, "description": "Contact email address for the tax payer.", "example": "john_doe@gmail.com" }, "phone": { "type": "string", "nullable": true, "description": "Contact phone number for the tax payer.", "example": "1234567890" } } }, "TaxStatusAddressBetweenStreetSat": { "type": "object", "properties": { "street_one": { "type": "string", "nullable": true, "description": "The first street that `street` is located between.", "example": "CALLE PRINCIPE" }, "street_two": { "type": "string", "nullable": true, "description": "The second street that `street` is located between.", "example": "CALLE NUEVA ROMA" } } }, "TaxStatusAddressSat": { "type": "object", "nullable": true, "required": [ "postal_code" ], "description": "The tax payer's address details.", "properties": { "postal_code": { "type": "string", "nullable": true, "description": "The postcode of the address.\n", "example": "21255" }, "street_type": { "type": "string", "nullable": true, "description": "The `street` type.", "example": "CALLE" }, "street": { "type": "string", "nullable": true, "description": "The tax payers street.", "example": "LA MALINCHE" }, "exterior_number": { "type": "string", "nullable": true, "description": "The street number.", "example": "432" }, "interior_number": { "type": "string", "nullable": true, "description": "Additional address information.", "example": "PLANTA BAJA" }, "suburb": { "type": "string", "nullable": true, "description": "The suburb of the tax payer.\n", "example": "BUENAVENTURA" }, "locality": { "type": "string", "nullable": true, "description": "The locality of the address.\n", "example": "none" }, "municipality": { "type": "string", "nullable": true, "description": "The municipality of the address.", "example": "CDMX DC" }, "state": { "type": "string", "nullable": true, "description": "The state that the address is in.", "example": "Federal" }, "between_street": { "type": "array", "nullable": true, "description": "Additional information about where the `street` is located.\n", "items": { "$ref": "#/components/schemas/TaxStatusAddressBetweenStreetSat" } } } }, "TaxStatusEconomicActivitySat": { "type": "object", "properties": { "economic_activity": { "type": "string", "nullable": true, "description": "The description of the economic activity.", "example": "Asalariado" }, "initial_date": { "type": "string", "nullable": true, "description": "The start date of the economic activity, in `YYYY-MM-DD` format.", "example": "2020-12-06" }, "end_date": { "type": "string", "nullable": true, "format": "date", "description": "The end date of the economic activity, in `YYYY-MM-DD` format.\n", "example": null }, "order": { "type": "string", "nullable": true, "description": "The order of the economic activity.", "example": "2" }, "percentage": { "type": "string", "nullable": true, "description": "The percentage of the economic activity.\n", "example": "1" } } }, "TaxStatusRegimensSat": { "type": "object", "required": [ "regimen", "initial_date", "end_date" ], "properties": { "end_date": { "type": "string", "nullable": true, "format": "date", "description": "The end date of the regimen, in `YYYY-MM-DD` format.\n", "example": null }, "initial_date": { "type": "string", "nullable": true, "format": "date", "description": "The start date of the regimen, in `YYYY-MM-DD` format.\n", "example": "2020-12-06" }, "regimen": { "type": "string", "nullable": true, "description": "The description of the regimen.", "example": "Régimen de Ingresos por Dividendos (socios y accionistas)" } } }, "TaxStatusObligationsSat": { "type": "object", "description": "Details regarding a business's obligations.\n\nℹ️ For non-business accounts, this field will return empty.\n", "properties": { "obligation": { "type": "string", "nullable": true, "description": "The description of the obligation.\n", "example": "Declaración informativa de IVA con la anual de ISR" }, "expiration": { "type": "string", "nullable": true, "description": "The deadline to fulfill the obligation, as imposed by the tax authority.\n", "example": "Conjuntamente con la declaración anual del ejercicio." }, "initial_date": { "type": "string", "nullable": true, "format": "date", "description": "The date when obligation started, in `YYYY-MM-DD` format.\n", "example": "2020-12-06" }, "end_date": { "type": "string", "nullable": true, "format": "date", "description": "The date when obligation ended, in `YYYY-MM-DD` format.\n", "example": null } } }, "TaxStatusSat": { "type": "object", "title": "Tax Status Object (Mexico)", "x-tags": [ "Tax status" ], "required": [ "id", "link", "collected_at", "created_at", "place_and_date_of_issuance", "official_name", "id_cif", "tax_payer_information", "address", "economic_activity", "regimes", "obligations", "digital_stamp", "digital_stamp_chain", "pdf" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "place_and_date_of_issuance": { "type": "string", "nullable": true, "description": "The place and date of that the tax status was issued.", "example": "TLALPAN , CIUDAD DE MEXICO A 19 DE MARZO DE 2020" }, "official_name": { "type": "string", "nullable": true, "description": "The name of the person or business.", "example": "John Doe" }, "id_cif": { "type": "string", "nullable": true, "description": "The taxpayer's *Cédula de Identificación Fiscal* (CIF) ID.\n", "example": "12345678901" }, "tax_payer_information": { "$ref": "#/components/schemas/TaxStatusTaxPayerInformationSat" }, "address": { "$ref": "#/components/schemas/TaxStatusAddressSat" }, "economic_activity": { "type": "array", "nullable": true, "description": "A list of economic activity objects.\n", "items": { "$ref": "#/components/schemas/TaxStatusEconomicActivitySat" } }, "regimes": { "type": "array", "nullable": true, "description": "A list of regimen objects.\n", "items": { "$ref": "#/components/schemas/TaxStatusRegimensSat" } }, "obligations": { "type": "array", "nullable": true, "description": "Details regarding a business's obligations.\n\nℹ️ For non-business accounts, this field will return empty.\n", "items": { "$ref": "#/components/schemas/TaxStatusObligationsSat" } }, "digital_stamp": { "type": "string", "nullable": true, "description": "The validation certificate of the document.", "example": "||2020/04/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN\nFISCAL|2044441088666600000034||\n" }, "digital_stamp_chain": { "type": "string", "nullable": true, "description": "A data chain containing the basic structure of a fiscal digital check. For Mexico, this is the *Comprobante Fiscal Digital por Internet* (CFDI).\n", "example": "EtenSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjow=\n" }, "pdf": { "type": "string", "nullable": true, "format": "binary", "description": "Tax status PDF as a binary string.", "example": "=PDF-STRING=" } } }, "invoice_chile": { "type": "object", "title": "Invoice Object (Chile)", "x-tags": [ "Invoices Chile" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "total_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total amount of the invoice, including VAT and other taxes or charges.", "example": 3272500.02 }, "net_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total invoice amount after VAT and other taxes.", "example": 2750000.02 }, "vat_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total VAT amount of the invoice.", "example": 522500.02 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The three-letter currency code (ISO-4217) of the invoice.", "example": "CLP" }, "issue_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date that the invoice was issued, in `YYYY-MM-DD` format.", "example": "2024-09-23" }, "received_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the invoice was received.", "example": "2024-09-02T15:23:47-03:00" }, "acknowledged_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the invoice was acknowledged as received.", "example": "2024-09-02T15:23:47-03:00" }, "claim_date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true, "description": "The date when a claim or dispute was raised about the invoice, in `YYYY-MM-DD` format.", "example": null }, "status": { "type": "string", "description": "The status of the invoice. Can be either:\n \n - `REGISTERED`\n - `PENDING`\n - `REJECTED`\n - `CANCELLED`\n \n", "example": "REGISTERED" }, "document_code": { "type": "integer", "description": "A code that indicates whether the document is a invoice, a credit or debit note, and so on.", "example": 33 }, "category": { "type": "string", "description": "The category of the invoice, according to the institution.", "example": "Del Giro" }, "folio": { "type": "string", "description": "The institution's unique code for the invoice.", "example": "23559723" }, "sender_id": { "type": "string", "description": "The identification number of the sender. For SII Chile, this is the RUT.", "example": "59324768-2" }, "sender_name": { "type": "string", "description": "The registered name of the sender.", "example": "Cafe del Sur" }, "receiver_id": { "type": "string", "description": "The identification number of the receiver. For SII Chile, this is the RUT.", "example": "82136549-6" }, "receiver_name": { "type": "string", "description": "The registered name of the receiver.", "example": "Alejandra Gonzalez" }, "type": { "type": "string", "enum": [ "INFLOW", "OUTFLOW" ], "description": "Indicates whether the invoice is an INFLOW or OUTFLOW.", "example": "INFLOW" }, "purchase_invoice_details": { "type": "object", "nullable": true, "description": "Details regarding the purchase invoice. If the invoice is a sales invoice (`type` = `OUTFLOW`), this field will return `null`.", "properties": { "vat_refundable_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of VAT paid that is eligible to be claimed back as a tax credit.", "example": 300.02 }, "vat_non_refundable_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of VAT paid that cannot be claimed back as a tax credit.", "example": 20.02 }, "vat_non_refundable_code": { "type": "integer", "format": "int32", "nullable": true, "description": "A code that identifies the reason why the VAT is not recoverable.", "example": 90 }, "net_amount_fixed_assets": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The net value of the purchased fixed assets.", "example": 8000.02 }, "vat_fixed_assets": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The VAT value on the purchase of fixed assets.", "example": 80.02 }, "vat_common_use": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The VAT that applies to purchases used for both taxable and non-taxable purposes.", "example": 129.02 }, "tax_non_credit_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The tax amount that cannot be claimed as a credit.", "example": 5.02 }, "vat_non_withheld": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The VAT amount that was not withheld by the purchaser.", "example": 8.02 }, "tax_exempt_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The portion of the purchase that is exempt from VAT.", "example": 33.02 }, "credit_or_debit_note_on_purchase": { "type": "boolean", "nullable": true, "description": "Indicates whether the invoice is linked with a credit or debit note.", "example": false }, "tax_cigarettes_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total tax amount applied on cigarettes.", "example": 50.02 }, "tax_cigar_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total tax amount applied on cigars.", "example": 51.02 }, "tax_processed_tobacco_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total tax amount applied on processed tobacco.", "example": 49.02 }, "additional_tax_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total tax amount of the additional tax.", "example": 1005.02 }, "additional_tax_rate": { "type": "string", "nullable": true, "description": "The tax rate of the additional tax.", "example": "2.1" }, "additional_tax_code": { "type": "integer", "format": "int32", "nullable": true, "description": "The tax code for the additional tax.", "example": 50993 } } }, "sales_invoice_details": { "type": "object", "nullable": true, "description": "Details regarding the sales invoice. If the invoice is a purchase invoice (`type` = `INFLOW`), this field will return `null`.", "properties": { "construction_sector_tax_credit": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of tax credit applicable for construction companies.", "example": 50000.02 }, "tax_free_trade_zone_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "Tax applicable for transactions in free trade zones.", "example": 38490.02 }, "container_deposit_guarantee": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "Refers to deposits or guarantees on containers, if applicable.", "example": 0.02 }, "is_free_of_charge": { "type": "boolean", "nullable": true, "description": "Indicated whether or not this sale was made at no cost (for example, the invoice is for promotional material, periodic free-of-charge resupplies, and similar).", "example": false }, "periodic_billing_type": { "type": "boolean", "nullable": true, "description": "Marks if the invoice is for periodic services.", "example": false }, "non_billable_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The portion of the transaction that is not billable.", "example": 40.02 }, "total_amount_for_period": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total amount for a specific period, often used for periodic billing." }, "domestic_transportation_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total amount spent on domestic transportation.", "example": 67.02 }, "international_transportation_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total amount spent on international transportation.", "example": 56.02 }, "branch_code": { "type": "integer", "format": "int32", "nullable": true, "description": "The code of the fiscal branch where the sales invoice was issued.", "example": 76129014 }, "tax_exempt_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The portion of the sale that is exempt from VAT.", "example": 4000.02 }, "credit_or_debit_note_on_purchase": { "type": "boolean", "nullable": true, "description": "Indicates whether the invoice is linked with a credit or debit note.", "example": false }, "additional_tax_code": { "type": "integer", "nullable": true, "description": "The tax code for the additional tax.", "example": 50993 }, "additional_tax_rate": { "type": "string", "nullable": true, "description": "The tax rate of the additional tax.", "example": "2.1" }, "additional_tax_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total tax amount of the additional tax.", "example": 1005.02 }, "vat_total_withheld": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total VAT withheld.", "example": 33.02 }, "vat_partially_withheld": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of VAT partially withheld.", "example": 30.02 }, "vat_non_withheld": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of VAT that was not withheld.", "example": 40.02 }, "vat_sales": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The VAT amount corresponding to the seller's own sales.", "example": 100.02 }, "vat_third_party": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "VAT amount related to third-party sales if acting as an intermediary.", "example": 1000.02 }, "vat_past_due": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "VAT that is accounted for or paid after the due date.", "example": 31.02 }, "invoice_settlement_sender_id": { "type": "string", "nullable": true, "description": "The RUT of the entity that issued the settlement for the invoice.", "example": "55524768-7" }, "invoice_settlement_net_commission": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The net amount of commission in the invoice settlement.", "example": 54.02 }, "invoice_settlement_exempt_commission": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The portion of the commission in the invoice settlement that is exempt from tax.", "example": 16.02 }, "invoice_settlement_vat_commission": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "VAT charged on the commission amount in the invoice settlement.", "example": 78.02 }, "reference_document_type": { "type": "string", "nullable": true, "description": "Indicates the type of document that this invoice refers to or is linked with.", "example": null }, "reference_document_folio": { "type": "string", "nullable": true, "description": "The folio number of the document referred to.", "example": null }, "foreign_recipient_id": { "type": "string", "nullable": true, "description": "The identification number of a foreign individual.", "example": "JANM-7820234" }, "foreign_recipient_nationality": { "type": "string", "nullable": true, "description": "The nationality of the foreign individual.", "example": "Peru" } } }, "summary_invoice_details": { "type": "object", "description": "Details regarding the summary of `BOLETA_ELECTRONICA` or `COMPROBANTE_PAGO` invoices.", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "The year and month of the invoices, in `YYYY-MM` format.", "example": "2024-08" }, "updated_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the list of invoices was last updated.", "example": "2024-09-02T15:23:47-03:00" }, "total_documents": { "type": "integer", "format": "int32", "description": "The total number of invoices in the summary.", "example": 23 }, "tax_exempt_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total invoice value (from all invoices in the summary) that is exempt from VAT.", "example": 4000.02 } } } } }, "tax_status_sii_entity_details": { "type": "object", "description": "Details regarding the fiscal entity's (key dates and identification information).", "required": [ "incorporation_date", "start_date", "end_date", "document_id_type", "document_id_number", "name" ], "properties": { "incorporation_date": { "type": "string", "format": "date", "description": "The date that the fiscal entity was incorporated, in `YYYY-MM-DD` format.", "example": "24-09-2010" }, "start_date": { "type": "string", "format": "date", "description": "The date that the fiscal entity started operating, in `YYYY-MM-DD` format.", "example": "24-09-2010" }, "end_date": { "type": "string", "format": "date", "nullable": true, "description": "The date that the fiscal entity ceased operations, in `YYYY-MM-DD` format. If the entity is still operating, this field will return `null`", "example": null }, "document_id_type": { "type": "string", "description": "The type of document ID that the fiscal entity has. For Chile, this will be the `RUT`.", "example": "RUT" }, "document_id_number": { "type": "string", "description": "The document ID number of the fiscal entity.", "example": "197476427-K" }, "name": { "type": "string", "description": "The name of the fiscal entity.", "example": "Empresa de Prueba" } } }, "tax_status_sii_address": { "type": "object", "description": "Details regarding the address of the fiscal entity.", "required": [ "type", "date", "address" ], "properties": { "type": { "type": "string", "enum": [ "PRIMARY", "SECONDARY", "MAILING_ADDRESS", "NOTIFICATION_ADDRESS" ], "description": "The type of address. Can be either:\n\n - `PRIMARY` (*domicilio*)\n - `SECONDARY` (*sucursal*)\n - `MAILING_ADDRESS` (*DOM. POSTAL*)\n - `NOTIFICATION_ADDRESS` (*DOM. URBANO_VALIDO_NOTIFICACIONES*)\n", "example": "PRIMARY" }, "date": { "type": "string", "format": "date", "description": "The date that the address was added to the fiscal entity's records, in `YYYY-MM-DD` format.", "example": "24-09-2010" }, "address": { "type": "string", "description": "The address of the fiscal entity.", "example": "Calle Falsa 123" } } }, "tax_status_sii_emails": { "type": "object", "description": "Details regarding the email addresses of the fiscal entity.", "required": [ "type", "email" ], "properties": { "type": { "type": "string", "enum": [ "CONTACT", "NOTIFICATION", "OTHER" ], "description": "The type of email. Can be either:\n\n- `CONTACT` (*Correo electrónico de contacto*)\n- `NOTIFICATION` (*Correo electrónico para notificaciones*)\n- `OTHER`.\n", "example": "CONTACT" }, "email": { "type": "string", "format": "email", "description": "The email address of the fiscal entity.", "example": "mi-email@empresa.cl" } } }, "tax_status_sii_phone": { "type": "object", "description": "Details regarding the phone numbers of the fiscal entity.", "required": [ "number", "type" ], "properties": { "type": { "type": "string", "nullable": true, "enum": [ "LANDLINE", "MOBILE", "OTHER", "null" ], "description": "The type of phone number. Can be either:\n \n - `LANDLINE`\n - `MOBILE`\n - `OTHER`\n", "example": "LANDLINE" }, "number": { "type": "string", "description": "The phone number of the fiscal entity.", "example": 123456789 } } }, "tax_status_sii_economic_activity": { "type": "object", "description": "Details regarding the economic activity of the fiscal entity.", "required": [ "type", "activity", "code", "tax_category", "vat_affected", "start_date" ], "properties": { "type": { "type": "string", "description": "The overall economic activity type, according to Servicio de Impuestos Internos (SII).", "example": "ASESORIA EN INGENIERIA" }, "activity": { "type": "string", "description": "The specific economic activity, according to Servicio de Impuestos Internos (SII).", "example": "ACTIVIDADES DE CONSULTORIA DE GESTION" }, "code": { "type": "string", "description": "The economic activity code, according to Servicio de Impuestos Internos (SII).", "example": "702000" }, "tax_category": { "type": "integer", "description": "The tax category of the economic activity, according to Servicio de Impuestos Internos (SII).", "example": 1 }, "vat_affected": { "type": "boolean", "description": "Indicates whether the economic activity is VAT-affected.", "example": true }, "start_date": { "type": "string", "format": "date", "description": "The date that the fiscal entity started this economic activity, in `YYYY-MM-DD` format.", "example": "24-09-2010" } } }, "tax_status_sii_legal_representative": { "type": "object", "description": "Details regarding the legal representatives of the fiscal entity.", "required": [ "is_current", "name", "document_id_type", "document_id_number", "start_date" ], "properties": { "is_current": { "type": "boolean", "description": "Indicates whether the legal representative is the current legal representative of the fiscal entity.", "example": true }, "name": { "type": "string", "description": "The name of the legal representative.", "example": "Juan Perez" }, "document_id_type": { "type": "string", "enum": [ "RUT" ], "description": "The type of document ID of the legal representative. For Chile, this will be always set to `RUT`.", "example": "RUT" }, "document_id_number": { "type": "string", "description": "The document ID number of the legal representative. For Chile, this will be the RUT number.", "example": "12345678-9" }, "start_date": { "type": "string", "format": "date", "description": "The date that the legal representative started representing the fiscal entity, in `YYYY-MM-DD` format.", "example": "24-09-2010" }, "end_date": { "type": "string", "format": "date", "nullable": true, "description": "The date that the legal representative ceased representing the fiscal entity, in `YYYY-MM-DD` format. If the legal representative is still representing the fiscal entity, this field will return `null`.", "example": null } } }, "tax_status_sii_equity_holder": { "type": "object", "description": "Detaiuls regarding the equity holders of the fiscal entity.", "required": [ "is_current", "name", "document_id_type", "document_id_number", "inactive", "start_date", "capital_contributed", "capital_contribution_outstanding", "ownership_share", "profit_share" ], "properties": { "is_current": { "type": "boolean", "description": "Indicates whether the equity holder is currently active.", "example": true }, "name": { "type": "string", "description": "The name of the equity holder.", "example": "Juan Perez" }, "document_id_type": { "type": "string", "enum": [ "RUT" ], "description": "The type of document ID of the equity holder. For Chile, this will be always set to `RUT`.", "example": "RUT" }, "document_id_number": { "type": "string", "description": "The document ID number of the equity holder. For Chile, this will be the RUT number.", "example": "12345678-9" }, "inactive": { "type": "boolean", "description": "Indicates whether the equity holder is currently inactive.", "example": false }, "start_date": { "type": "string", "format": "date", "description": "The date that the equity holder started holding equity in the fiscal entity, in `YYYY-MM-DD` format.", "example": "24-09-2010" }, "end_date": { "type": "string", "format": "date", "nullable": true, "description": "The date that the equity holder ceased holding equity in the fiscal entity, in `YYYY-MM-DD` format. If the equity holder is still holding equity in the fiscal entity, this field will return `null`.", "example": null }, "capital_contributed": { "type": "number", "description": "The amount of capital contributed by the equity holder.", "example": 1000000 }, "capital_contribution_outstanding": { "type": "number", "description": "The amount of capital contribution outstanding by the equity holder.", "example": 3750 }, "ownership_share": { "type": "number", "description": "The percentage of ownership share of the equity holder.", "example": 25.25 }, "profit_share": { "type": "number", "description": "The percentage of profit share of the equity holder.", "example": 31.25 } } }, "tax_status_sii_company_stake": { "type": "object", "description": "Details regarding the company stakes of the fiscal entity.", "required": [ "name", "document_id_type", "document_id_number", "inactive", "start_date", "capital_contributed", "capital_contribution_outstanding", "ownership_share", "profit_share" ], "properties": { "name": { "type": "string", "description": "The name of the entity that this fiscal entity.", "example": "Empresa de Prueba" }, "document_id_type": { "type": "string", "enum": [ "RUT" ], "description": "The type of document ID of the business. For Chile, this will be always set to `RUT`.", "example": "RUT" }, "document_id_number": { "type": "string", "description": "The document ID number of the business. For Chile, this will be the RUT number.", "example": "12345678-9" }, "inactive": { "type": "boolean", "description": "Indicates whether the business is currently active.", "example": false }, "start_date": { "type": "string", "format": "date", "description": "The date that the company started holding equity in the fiscal entity, in `YYYY-MM-DD` format.", "example": "24-09-2010" }, "end_date": { "type": "string", "format": "date", "nullable": true, "description": "The date that the company holder ceased holding equity in the fiscal entity, in `YYYY-MM-DD` format. If the equity holder is still holding equity in the fiscal entity, this field will return `null`.", "example": null }, "capital_contributed": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount of capital contributed by the company.", "example": 1000000.02 }, "capital_contribution_outstanding": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The amount of capital contribution outstanding by the company.", "example": 3750.02 }, "ownership_share": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The percentage of ownership share of the company.", "example": 25.25 }, "profit_share": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The percentage of profit share of the company.", "example": 31.25 } } }, "tax_status_sii_regime": { "type": "object", "description": "Details regarding the tax regime of the fiscal entity.", "required": [ "type", "start_date" ], "properties": { "type": { "type": "string", "description": "The tax regime type, as defined by the Servicio de Impuestos Internos (SII).", "example": "MICRO EMPRESA" }, "start_date": { "type": "string", "format": "date", "description": "The date that the fiscal entity started this tax regime, in `YYYY-MM-DD` format.", "example": "2023-01-01" } } }, "tax_status_sii_authorized_tax_document": { "type": "object", "description": "Details regarding an authorized tax document for the fiscal entity.\n", "required": [ "type", "document_limit", "authorization_date" ], "properties": { "type": { "type": "string", "description": "The type of authorized tax document, as defined by the Servicio de Impuestos Internos (SII).\n", "example": "CONTABILIDAD EN HOJAS SUELTAS CON NRO.UN" }, "document_limit": { "type": "integer", "description": "The maximum number of documents that can be issued under this authorization.\n", "example": 2000 }, "authorization_date": { "type": "string", "format": "date", "description": "The date that the tax document and limit were established, in `YYYY-MM-DD` format.\n", "example": "2010-18-11" } } }, "tax_status_sii_property_tax_liabilities": { "type": "object", "description": "Details regarding the tax liabilities of a property that the entity is associated with.", "required": [ "property_id", "district", "address", "type", "overdue_tax_payments", "scheduled_tax_payments" ], "properties": { "property_id": { "type": "string", "description": "The unique identifier of the property, according to the Servicio de Impuestos Internos (SII).\n", "example": "12345" }, "district": { "type": "string", "description": "The district where the property is located.\n", "example": "NUNAO" }, "address": { "type": "string", "description": "The address of the property.\n", "example": "123 Example Street" }, "type": { "type": "string", "description": "The type of property associated with the tax liability.\n", "example": "HABITACIONAL" }, "overdue_tax_payments": { "type": "array", "description": "A list of overdue tax payments for the property.\n", "items": { "type": "object", "required": [ "year", "installment", "due_date", "amount_due" ], "properties": { "year": { "type": "integer", "description": "The year for which the tax payment is overdue.\n", "example": 2023 }, "installment": { "type": "integer", "description": "The instalment number of the overdue tax payment.\n", "example": 1 }, "due_date": { "type": "string", "format": "date", "description": "The due date of the overdue tax payment, in `YYYY-MM-DD` format.\n", "example": "2023-04-30" }, "amount_due": { "type": "number", "format": "float", "description": "The amount due for the overdue tax payment.\n", "example": 19.864 } } } }, "scheduled_tax_payments": { "type": "array", "description": "A list of scheduled tax payments for the property.\n", "items": { "type": "object", "required": [ "year", "installment", "due_date", "amount_due" ], "properties": { "year": { "type": "integer", "description": "The year for which the tax payment is scheduled.\n", "example": 2023 }, "installment": { "type": "integer", "description": "The instalment number of the scheduled tax payment.\n", "example": 1 }, "due_date": { "type": "string", "format": "date", "description": "The due date of the scheduled tax payment, in `YYYY-MM-DD` format.\n", "example": "2023-04-30" }, "amount_due": { "type": "number", "format": "float", "description": "The amount due for the scheduled tax payment.\n", "example": 19.864 } } } } } }, "tax_status_sii_fiscal_office": { "type": "object", "description": "Details regarding fiscal office where the fiscal entity is registered.\n", "required": [ "name", "address" ], "properties": { "name": { "type": "string", "description": "The name of the fiscal office where the fiscal entity is registered.\n", "example": "VIÑA DEL MAR" }, "address": { "type": "string", "description": "The address of the fiscal office where the fiscal entity is registered.\n", "example": "ARLEGUI 525, VIÑA DEL MAR" } } }, "tax_status_sii": { "type": "object", "title": "Tax Status Object (Chile)", "x-tags": [ "Tax Status Chile" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "entity_details": { "$ref": "#/components/schemas/tax_status_sii_entity_details" }, "addresses": { "type": "array", "description": "An array of addresses for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_address" } }, "emails": { "type": "array", "description": "An array of email addresses for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_emails" } }, "phone_numbers": { "type": "array", "description": "An array of phone numbers for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_phone" } }, "economic_activities": { "type": "array", "description": "An array of economic activities for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_economic_activity" } }, "legal_representative": { "type": "array", "description": "An array of legal representatives for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_legal_representative" } }, "equity_holders": { "type": "array", "description": "An array of equity holders for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_equity_holder" } }, "company_partnership_stakes": { "type": "array", "description": "An array of company partnership stakes for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_company_stake" } }, "regimes": { "type": "array", "nullable": true, "description": "A list of tax regimes for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_regime" } }, "authorized_tax_documents": { "type": "array", "nullable": true, "description": "A list of authorized tax documents for the fiscal entity.", "items": { "$ref": "#/components/schemas/tax_status_sii_authorized_tax_document" } }, "property_tax_liabilities": { "type": "array", "nullable": true, "description": "A list of tax liabilities of a property that the entity is associated with.", "items": { "$ref": "#/components/schemas/tax_status_sii_property_tax_liabilities" } }, "fiscal_office": { "$ref": "#/components/schemas/tax_status_sii_fiscal_office" } } }, "debt_chile": { "type": "object", "title": "Debt Report Object (Chile)", "x-tags": [ "Debt Reports Chile" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "link": { "$ref": "#/components/schemas/link" }, "collected_at": { "$ref": "#/components/schemas/collected_at" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "personal_data": { "type": "object", "properties": { "full_name": { "type": "string", "description": "The full name of the individual.", "example": "Cabezas Pérez Martín Vicente " }, "document_id_type": { "type": "string", "enum": [ "RUT" ], "description": "The type of document ID of the individual. For Chile, this will be always set to `RUT`.", "example": "RUT" }, "document_id_number": { "type": "string", "description": "The document ID number of the individual. For Chile, this will be the RUT number.", "example": "12345678-9" } } }, "debt_data_last_update": { "type": "string", "format": "date", "description": "The date when the debt data was last updated, in `YYYY-MM-DD` format.", "example": "2023-07-02" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The currency of the debts. For Chile, this will be the `CLP`.", "example": "CLP" }, "total": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The total amount of debt including current, delinquent, severely delinquent, and defaulted debts.", "example": 6506000.02 }, "current": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is currently outstanding but not past due.", "example": 5350000.02 }, "delinquent": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 30-59 days past due.", "example": null }, "severely_delinquent": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 60-89 days past due.", "example": 56000.02 }, "defaulted": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 90 days past due.", "example": 1100000.02 }, "direct_debts": { "type": "array", "nullable": true, "description": "A list of debts that are directly atttribued to the individual.", "items": { "type": "object", "properties": { "financial_institution": { "type": "string", "description": "The name of the financial institution where the debt is held.", "example": "Banco Santander" }, "credit_type": { "type": "string", "description": "The type of credit issued by the financial institution. For example, `Vivienda`, `Comercial`, `Consumo`, or `Otro`.", "example": "Vivienda" }, "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total amount of the debt at the financial institution.", "example": 5000000.02 }, "current": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The current outstanding amount of the debt at the financial institution.", "example": 5000000.02 }, "delinquent": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 30-59 days past due.", "example": null }, "severely_delinquent": { "type": "number", "format": "float", "nullable": true, "description": "The amount of debt that is 60-89 days past due.", "example": null }, "defaulted": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 90 days past due.", "example": null } } } }, "indirect_debts": { "type": "array", "nullable": true, "description": "List of indirect debts from financial institutions.", "items": { "type": "object", "properties": { "financial_institution": { "type": "string", "description": "Name of the financial institution providing the indirect debt.", "example": "Banco BCI" }, "credit_type": { "type": "string", "description": "The type of credit issued by the financial institution. For example, `Vivienda`, `Comercial`, `Consumo`, or `Otro`.", "example": "Consumo" }, "amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "description": "The total amount of the debt at the financial institution.", "example": 200000.02 }, "current": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The current outstanding amount of the debt at the financial institution.", "example": null }, "delinquent": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 30-59 days past due.", "example": null }, "severely_delinquent": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 60-89 days past due.", "example": null }, "defaulted": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of debt that is 90 days past due.", "example": 200000.02 } } } }, "credit_lines": { "type": "array", "nullable": true, "description": "List of credit lines (such as credit cards) available to the individual.", "items": { "type": "object", "properties": { "financial_institution": { "type": "string", "description": "The name of the financial institution providing the credit line.", "example": "Banco BCI" }, "direct_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of direct credit available.", "example": 5000000.02 }, "indirect_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of indirect credit available.", "example": null } } } }, "other_credits": { "type": "array", "nullable": true, "description": "List of other credits (such as guarantee notes, foreign credit, and so on) available to the individual.", "items": { "type": "object", "properties": { "financial_institution": { "type": "string", "description": "The name of the financial institution providing the credit.", "example": "Banco BCI" }, "direct_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of direct credit available.", "example": null }, "indirect_amount": { "type": "number", "format": "float", "pattern": "^\\d{1,15}\\.\\d{2,4}$", "nullable": true, "description": "The amount of indirect credit available.", "example": 250000.02 } } } } } }, "payments_common_pagination_properties": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "The total number of results in your Belvo account.", "example": 130 }, "next": { "type": "string", "nullable": true, "format": "uri", "description": "The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is `null`.\n\nIn our documentation example, we use `{endpoint}` as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, `accounts` or `owners`).\n", "example": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2" }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "The URL to the previous page of results. If there is no previous page, the\nvalue is `null`.\n", "example": null } } }, "paymentInstitutionBR": { "type": "object", "required": [ "id", "active", "name", "display_name", "legal_entity_name", "website", "logo", "icon_logo", "text_logo", "primary_color", "country", "form_fields", "sort_priority", "description" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the institution.", "example": "bbaceead-7b96-46d8-9354-38dec9707004" }, "code": { "type": "string", "description": "The ISPB code of the institution.", "example": "12345678" }, "active": { "type": "boolean", "description": "Indicates whether this institution is available for use or not.", "example": true }, "institution_type": { "type": "string", "enum": [ "BUSINESS", "INDIVIDUAL" ], "description": "The type of institution. Can be either `BUSINESS` or `INDIVIDUAL`.", "example": "INDIVIDUAL" }, "name": { "type": "string", "description": "The name of the institution, as designated by Belvo.", "example": "wakanda_national" }, "display_name": { "type": "string", "description": "The customer-facing name of the institution.", "example": "Wakanda National Bank" }, "legal_entity_name": { "type": "string", "nullable": true, "description": "The name of the legal entity of the institution, as registered with the relevant regulatory authority. Only applicable for 🇧🇷 Brazil OFPI.\n", "example": "Wakanda Bank, National Association" }, "website": { "type": "string", "description": "The URL of the institution's website.", "example": "https://www.wakandanational.com" }, "logo": { "type": "string", "description": "The URL of the institution's logo.", "example": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_logo.svg" }, "icon_logo": { "type": "string", "description": "The URL of the institution's icon logo.", "example": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_icon_logo.svg" }, "text_logo": { "type": "string", "description": "The URL of the institution's text logo.", "example": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_text_logo.svg" }, "primary_color": { "type": "string", "description": "The primary color on the institution's website.", "example": "#fdbc24" }, "country": { "type": "string", "maxLength": 3, "description": "The country that the institution is located in. For Brazil, this is always set to `BRA`.\n", "example": "BRA" }, "form_fields": { "type": "array", "nullable": true, "description": "This field is not applicable for OFPI and will return an empty array.", "example": [] }, "sort_priority": { "type": "integer", "format": "int32", "description": "Number that represents the order in which the institution should be displayed in an application, with `1` being the highest.\n", "example": 1 }, "description": { "type": "string", "nullable": true, "description": "A brief description of the insitution.", "example": "Simple, transparent and secure: Wakanda Bank is the leading financial technology company in Latin America." } } }, "EnumPaymentLinkProvider": { "type": "string", "deprecated": true, "enum": [ "belvo" ], "description": "**Note**: This field has been deprecated and will be removed from the API in the future.\n\n*The provider used for the payment link.*\n", "example": "belvo" }, "scheduled_single": { "type": "object", "nullable": true, "title": "Single", "description": "Details regarding the scheduled (one-off) payment.", "properties": { "single": { "type": "object", "nullable": true, "description": "Details regarding the scheduled (one-off) payment.", "properties": { "date": { "type": "string", "format": "date", "description": "The date the one-off scheduled payment should be made, in `YYYY-MM-DD` format.\n", "example": "2024-10-22" } } } } }, "scheduled_daily": { "type": "object", "title": "Daily", "description": "Details regarding the daily recurring payment.", "properties": { "daily": { "type": "object", "description": "Details regarding the daily recurring payment.", "properties": { "start_date": { "type": "string", "format": "date", "description": "The date the recurring daily payment should start on, in `YYYY-MM-DD` format.\n\n>**Note**: The `start_date` must be at least 1 day in the future.\n", "example": "2024-10-22" }, "occurrences": { "type": "integer", "minimum": 2, "maximum": 60, "description": "The number of times the payment should repeat. \n\n>**Note**: You must schedule at least `2` occurrences and no more than `60`.\n", "example": 10 } } } } }, "scheduled_weekly": { "type": "object", "title": "Weekly", "description": "Details regarding the weekly recurring payment.", "properties": { "weekly": { "type": "object", "description": "Details regarding the weekly recurring payment.", "properties": { "start_date": { "type": "string", "format": "date", "description": "The date the recurring weekly payment should start on, in `YYYY-MM-DD` format.\n\n>**Note**: The `start_date` must correspond to the first `day_of_week` specified and be at least 1 day in the future.\n", "example": "2024-10-22" }, "day_of_week": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "description": "The day of the week the payment should be made. Can be one of the following values:\n\n - `MONDAY`\n - `TUESDAY`\n - `WEDNESDAY`\n - `THURSDAY`\n - `FRIDAY`\n - `SATURDAY`\n - `SUNDAY`\n", "example": "MONDAY" }, "occurrences": { "type": "integer", "minimum": 2, "maximum": 60, "description": "The number of times the payment should repeat. \n\n>**Note**: You must schedule at least `2` occurrences and no more than `60`.\n", "example": 10 } } } } }, "scheduled_monthly": { "type": "object", "title": "Monthly", "description": "Details regarding the monthly recurring payment.", "properties": { "monthly": { "type": "object", "description": "Details regarding the monthly recurring payment.", "properties": { "start_date": { "type": "string", "format": "date", "description": "The date the recurring monthly payment should start on, in `YYYY-MM-DD` format.\n\n>**Note**: The `start_date` must correspond to the first `day_of_month` specified and be at least 1 day in the future.\n", "example": "2024-10-26" }, "day_of_month": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the month the payment should be made. Can be any integer between `1` and `31`.\n", "example": 26 }, "occurrences": { "type": "integer", "minimum": 2, "maximum": 24, "description": "The number of times the payment should repeat. \n\n>**Note**: You must schedule at least `2` occurrences and no more than `24`.\n", "example": 12 } } } } }, "scheduled_custom": { "type": "object", "title": "Custom", "description": "Details regarding the custom recurring payment.", "properties": { "custom": { "type": "object", "description": "Details regarding the custom recurring payment.", "properties": { "dates": { "type": "array", "minItems": 2, "maxItems": 60, "description": "The unique dates the recurring payment should be made, in `YYYY-MM-DD` format.\n\n>**Note**: The dates must be at least 1 day in the future and no more than 720 days in the future.\n", "items": { "type": "string", "format": "date", "description": "The date of the payment, in `YYYY-MM-DD` format.\n", "example": "2024-10-22" }, "example": [ "2024-10-22", "2024-10-26" ] }, "description": { "type": "string", "maxLength": 256, "description": "A description of the custom recurring payment that will display to your user when they are redirected to their bank to accept the payment.\n\n> **Note**: We highly recommend that this message be in Brazilian Portuguese, and that it clearly explains the purpose as well as recurring nature of the payment.\n", "example": "Os pagamentos ocorrerão a cada três dias até a data final (30.09.2024)" } } } } }, "schedule": { "type": "object", "nullable": true, "title": "Schedule a payment", "description": "Details regarding the scheduled payment (optional). For more information on how to schedule payments, please see our dedicated OFPI Scheduled Payments guide.\n", "oneOf": [ { "$ref": "#/components/schemas/scheduled_single" }, { "$ref": "#/components/schemas/scheduled_daily" }, { "$ref": "#/components/schemas/scheduled_weekly" }, { "$ref": "#/components/schemas/scheduled_monthly" }, { "$ref": "#/components/schemas/scheduled_custom" } ] }, "ChargePaymentMethodDetailsOfpiContent": { "type": "object", "description": "Information about the payer of a OFPI payment.", "properties": { "schedule": { "$ref": "#/components/schemas/schedule" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Unique identifier for the payer's institution.\n", "example": "db201c6a-e0ee-4caa-92d6-72b480d6d86f" }, "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" } } }, "ChargePaymentMethodDetailsOfpi": { "type": "object", "title": "OFPI", "description": "Details about the payment method.\n", "properties": { "open_finance": { "$ref": "#/components/schemas/ChargePaymentMethodDetailsOfpiContent" } } }, "PaymentMethodInformationBodyOfpi": { "type": "object", "description": "Payment method type selected.", "properties": { "provider_request_id": { "type": "string", "nullable": true, "description": "Unique ID for the payment, as sent by the provider.\n", "example": "978c0c97ea847e78e8849634473c1f1" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL that redirects the user to their institution's website to authorize the payment.\n", "example": "https://wakandanational.com/" }, "end_to_end_id": { "type": "string", "nullable": true, "description": "A unique ID for the transaction in the Brazil's PIX payment system.", "example": "F203262942022211117487a213b1d140" }, "settlement_date": { "type": "string", "format": "date", "description": "The `settlement_date` field indicates the date on which a scheduled payment (charge) is planned to be settled. This field is relevant in various states of the charge's lifecycle:\n\n - Scheduled Charges: When a charge has the status `SCHEDULED`, this field represents the planned settlement date.\n - Completed Charges: When a charge has the status `SUCCEEDED`, this field reflects the date that the payment was made.\n - Failed or Canceled Charges: When a charge has the status `CANCELED` or `FAILED`, this field will still contain the originally calculated settlement date, indicating when the charge was intended to be settled.\n\n\n> **Note**: The `settlement_date` does not change based on the success or failure of the charge. It consistently reflects the original planned settlement date.\n", "example": "2024-10-22" } } }, "PaymentMethodInformationOfpi": { "type": "object", "title": "OFPI", "description": "Information about the payment method selected.\n", "properties": { "open_finance": { "$ref": "#/components/schemas/PaymentMethodInformationBodyOfpi" } } }, "ChargePayerInformation": { "type": "object", "description": "Information about the ChargePayerInformation.yaml", "properties": { "bank_account": { "type": "object", "description": "Information about the payer's bank account.", "properties": { "type": { "type": "string", "description": "The type of the payer's bank account. Can be either `CHECKINGS`, `SAVINGS`, or `PAYMENTS`.", "example": "CHECKINGS" }, "agency": { "type": "string", "description": "The agency number of the payer's bank account.", "example": "1234" }, "number": { "type": "string", "description": "The account number of the payer's bank account.", "example": "123456789" }, "institution_id": { "type": "string", "format": "uuid", "description": "The Belvo institution ID of the payer's bank account.", "example": "528228e2-d40d-4cec-948d-ec5edd7d081c" } } } } }, "EnumPaymentsCurrency": { "type": "string", "enum": [ "BRL" ], "description": "The currency of the amount paid, for example, `BRL` (Brazilian Real).\n", "example": "BRL" }, "EnumPaymentTransactionType": { "type": "string", "enum": [ "INFLOW", "OUTFLOW" ], "description": "The direction of the transaction.\n\n - `INFLOW` indicates money coming into the account.\n - `OUTFLOW` indicates money coming out of the account.\n", "example": "INFLOW" }, "paymentTransaction": { "type": "object", "required": [ "id", "created_at", "created_by", "amount", "currency", "description", "transaction_type", "beneficiary", "payer", "charge" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "amount": { "type": "string", "description": "The transaction amount.\n\n\n**Note**: The amount displayed is always positive as we indicate the direction of the transaction in `transaction_type` parameter.\n", "example": "1020.00" }, "currency": { "$ref": "#/components/schemas/EnumPaymentsCurrency" }, "description": { "type": "string", "maxLength": 128, "description": "The description of the payment.\n", "example": "Training shoes" }, "transaction_type": { "$ref": "#/components/schemas/EnumPaymentTransactionType" }, "beneficiary": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "payer": { "description": "**Note**: For OFPI, this will return an empty object `{}`.\n" }, "payment_intent": { "type": "string", "format": "uuid", "description": "The unique ID of the payment intent associated with the transaction.", "example": "004a28bb-fac2-4172-884b-5b6ea15314ad" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the customer asscociated with this transaction.", "example": "9eebd63b-3339-44a9-8a5a-72bb6cb2f310" } } }, "ChargeBrazil": { "type": "object", "title": "Charge (V1 - Bank Account Beneficiary)", "required": [ "id", "created_at", "failure_code", "failure_message", "status", "updated_at", "amount", "beneficiary", "provider", "metadata", "payment_method_details", "payment_method_information" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the status of the charge was last updated.\n", "example": "2022-02-09T08:45:50.406032Z" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the customer that the charge was created for.", "example": "531aa631-70a0-4eeb-ab97-51dea3e90c89" }, "payment_intent": { "type": "string", "format": "uuid", "description": "The `payment_intent.id` associated with this charge.", "example": "50c04229-7b1d-4a53-951c-8ad53e10c6ca" }, "status": { "type": "string", "enum": [ "CANCELED", "PENDING", "SCHEDULED", "SUCCEEDED", "FAILED", "PARTIAL" ], "description": "The current status of the charge. Can be one of the following values:\n\n - `CANCELED`\n - `PENDING`\n - `SCHEDULED`\n - `SUCCEEDED`\n - `FAILED`\n - `PARTIAL`\n", "example": "PENDING" }, "amount": { "type": "string", "nullable": true, "description": "The amount of the charge.\n", "example": "100.12" }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "The currency of the amount paid. For 🇧🇷 Brazil, the value must be `BRL` (Brazilian Real).\n", "example": "BRL" }, "description": { "type": "string", "description": "The description of the payment.\n", "example": "Training shoes" }, "statement_description": { "type": "string", "maxLength": 50, "description": "The description that will appear on the customer's bank statement (if provided).\n", "example": "Super Shoe Store - Brown Sneakers" }, "beneficiary": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary’s bank account.", "example": "58524ccc-89ac-4ab6-b62b-c3da3f19a722" }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" }, "payment_method_type": { "type": "string", "enum": [ "open_finance" ], "description": "Selected payment method type. For 🇧🇷 Brazil's OFPI, the value must be `open_finance`.\n", "example": "open_finance" }, "payment_method_details": { "$ref": "#/components/schemas/ChargePaymentMethodDetailsOfpi" }, "payment_method_information": { "$ref": "#/components/schemas/PaymentMethodInformationOfpi" }, "payer_information": { "description": "Information about the payer's bank account.\n\n> **Note**: This object is only returned when the charge `status` is `SUCCEEDED`.\n", "allOf": [ { "$ref": "#/components/schemas/ChargePayerInformation" } ] }, "transactions": { "type": "array", "description": "An array of Transaction objects relating to the charge.", "items": { "$ref": "#/components/schemas/paymentTransaction" } }, "failure_code": { "type": "string", "nullable": true, "description": "Error code that explains the reason behind a payment being unsuccessful (if applicable).\n", "example": null }, "failure_message": { "type": "string", "nullable": true, "description": "Further information regarding the `failure_code`.\n", "example": null }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } } } }, "ChargePaymentMethodDetailsPixContent": { "type": "object", "description": "Information about the payer of a Pix payment.", "properties": { "payer_institution": { "type": "string", "format": "uuid", "description": "Unique identifier for the payer's institution.\n", "example": "db201c6a-e0ee-4caa-92d6-72b480d6d86f" }, "pix_key": { "type": "string", "description": "The Pix key associated with the beneficiary of the transaction. Can be an email, phone number, CPF/CNPJ, or a random key.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "schedule": { "$ref": "#/components/schemas/schedule" } } }, "ChargePaymentMethodDetailsPix": { "type": "object", "title": "Pix", "description": "Details about the payment method.\n", "properties": { "open_finance": { "$ref": "#/components/schemas/ChargePaymentMethodDetailsPixContent" } } }, "PaymentMethodInformationPixKeysConfirmed": { "type": "object", "title": "Confirmed", "description": "Information about the Pix Key payment method after the payment intent has been confirmed via a PATCH request.\n", "properties": { "open_finance": { "type": "object", "title": "Pix Key", "properties": { "provider_request_id": { "type": "string", "nullable": true, "description": "Unique ID for the payment, as sent by the provider.\n", "example": "978c0c97ea847e78e8849634473c1f1" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL that redirects the payer to their institution's website to authorize the payment.\n", "example": "https://wakandanational.com/" }, "end_to_end_id": { "type": "string", "nullable": true, "description": "A unique ID for the transaction in the Brazil's PIX payment system.", "example": "F203262942022211117487a213b1d140" }, "settlement_date": { "type": "string", "format": "date", "description": "The `settlement_date` field indicates the date on which a scheduled payment (charge) is planned to be settled. This field is relevant in various states of the charge's lifecycle:\n\n - Scheduled Charges: When a charge has the status `SCHEDULED`, this field represents the planned settlement date.\n - Completed Charges: When a charge has the status `SUCCEEDED`, this field reflects the date that the payment was made.\n - Failed or Canceled Charges: When a charge has the status `CANCELED` or `FAILED`, this field will still contain the originally calculated settlement date, indicating when the charge was intended to be settled.\n\n\n> **Note**: The `settlement_date` does not change based on the success or failure of the charge. It consistently reflects the original planned settlement date.\n", "example": "2024-10-22" }, "pix_key_details": { "type": "object", "description": "Details about the Pix key used for the payment.", "properties": { "identifier": { "type": "string", "description": "The masked identifier of the owner.\n", "example": "23******00" }, "name": { "type": "string", "description": "The name of the Pix key holder.", "example": "João da Silva" } } } } } } }, "ChargeBrazilPix": { "type": "object", "title": "Charge (V1 - Pix Key Beneficiary)", "required": [ "id", "created_at", "failure_code", "failure_message", "status", "updated_at", "amount", "beneficiary", "provider", "metadata", "payment_method_details", "payment_method_information" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the status of the charge was last updated.\n", "example": "2022-02-09T08:45:50.406032Z" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the customer that the charge was created for.", "example": "531aa631-70a0-4eeb-ab97-51dea3e90c89" }, "payment_intent": { "type": "string", "format": "uuid", "description": "The `payment_intent.id` associated with this charge.", "example": "50c04229-7b1d-4a53-951c-8ad53e10c6ca" }, "status": { "type": "string", "enum": [ "CANCELED", "PENDING", "SCHEDULED", "SUCCEEDED", "FAILED", "PARTIAL" ], "description": "The current status of the charge. Can be one of the following values:\n\n - `CANCELED`\n - `PENDING`\n - `SCHEDULED`\n - `SUCCEEDED`\n - `FAILED`\n - `PARTIAL`\n", "example": "PENDING" }, "amount": { "type": "string", "nullable": true, "description": "The amount of the charge.\n", "example": "100.12" }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "The currency of the amount paid. For 🇧🇷 Brazil, the value must be `BRL` (Brazilian Real).\n", "example": "BRL" }, "description": { "type": "string", "description": "The description of the payment.\n", "example": "Training shoes" }, "statement_description": { "type": "string", "maxLength": 50, "description": "The description that will appear on the customer's bank statement (if provided).\n", "example": "Super Shoe Store - Brown Sneakers" }, "beneficiary": { "type": "string", "format": "uuid", "nullable": true, "description": "Belvo's unique ID used to identify the beneficiary’s bank account. In the case that the beneficiary is a Pix Key, this field will be `null`.", "example": null }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" }, "payment_method_type": { "type": "string", "enum": [ "open_finance" ], "description": "Selected payment method type. For 🇧🇷 Brazil's OFPI, the value must be `open_finance`.\n", "example": "open_finance" }, "payment_method_details": { "$ref": "#/components/schemas/ChargePaymentMethodDetailsPix" }, "payment_method_information": { "$ref": "#/components/schemas/PaymentMethodInformationPixKeysConfirmed" }, "payer_information": { "$ref": "#/components/schemas/ChargePayerInformation" }, "transactions": { "description": "For Pix Key payments, this will be an empty array.", "example": [] }, "failure_code": { "type": "string", "nullable": true, "description": "Error code that explains the reason behind a payment being unsuccessful (if applicable).\n", "example": null }, "failure_message": { "type": "string", "nullable": true, "description": "Further information regarding the `failure_code`.\n", "example": null }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } } } }, "external_id__payments": { "type": "string", "format": "uuid", "description": "An additional unique identifier for the resource for internal purposes.\n\n{% admonition type=\"success\" name=\"Highly Recommended\" %}\n We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.\n{% /admonition %}\n", "example": "4b8a81a0-e33c-45a6-8567-479efb105f73" }, "metadata__payments": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.\n\n{% admonition type=\"info\" name=\"Metadata Limitations\" %}\n You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n{% /admonition %}\n", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500, "pattern": "^[\u0000-]*$" }, "example": { "internal_reference_id": "GGq73487w2" } }, "ChargeV2": { "type": "object", "title": "Charge (V2)", "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "status_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The ISO-8601 timestamp of when the status of the Charge was last updated.\n", "example": "2025-06-09T08:45:50.406032Z" }, "status": { "type": "string", "enum": [ "PENDING", "SCHEDULED", "SETTLED", "CANCELED", "FAILED" ], "description": "The current status of the Charge. Can be one of the following values:\n\n - `PENDING`\n - `SCHEDULED`\n - `SETTLED`\n - `CANCELED`\n - `FAILED`\n", "example": "PENDING" }, "status_reason_code": { "type": "string", "nullable": true, "description": "The reason code for the current status of the Charge, if applicable.\n", "example": null }, "status_reason_message": { "type": "string", "nullable": true, "description": "Further information regarding the `status_reason_code`.\n", "example": null }, "amount": { "type": "string", "nullable": true, "description": "The amount of the Charge.\n", "example": "100.12" }, "date": { "type": "string", "format": "date", "nullable": true, "description": "The original date of the Charge.\n", "example": "2025-06-09" }, "end_to_end_id": { "type": "string", "nullable": true, "description": "The end-to-end ID of the Charge. This is a unique identifier for the transaction that can be used to track it across different systems.\n", "example": "1234567890abcdef" }, "statement_description": { "type": "string", "minLength": 1, "maxLength": 140, "description": "The description that will appear on the customer's bank statement (if provided).\n", "example": "Super Shoe Store - Brown Sneakers" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "beneficiary": { "type": "object", "description": "Information about the beneficiary of the Charge.", "properties": { "bank_account": { "type": "object", "description": "Information about the beneficiary's bank account.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.", "example": "088bc38f-1430-40c5-a5d2-80bd67189d11" }, "holder": { "type": "object", "description": "Information about the holder of the beneficiary's bank account.", "properties": { "name": { "type": "string", "description": "The full name of the holder of the beneficiary's bank account.", "example": "Jane Smith" }, "identifier": { "type": "string", "description": "The identifier of the holder of the beneficiary's bank account. Can be either a CPF (11 characters) or CNPJ (14 characters).", "minLength": 11, "maxLength": 14, "example": "12345678901" } } }, "details": { "type": "object", "description": "Details of the beneficiary's bank account.", "properties": { "institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "agency": { "type": "string", "description": "The agency number of the beneficiary's bank account.", "example": "5678" }, "number": { "type": "string", "description": "The account number of the beneficiary's bank account.", "example": "987654321" }, "account_type": { "type": "string", "description": "The type of the beneficiary's bank account. Can be either `CHECKINGS`, `SAVINGS`, or `PAYMENTS`.", "example": "SAVINGS" }, "code": { "type": "string", "description": "The ISPB code of the beneficiary's bank.", "example": "678901" } } } } } } }, "payer": { "type": "object", "description": "Information about the payer of the Charge.", "properties": { "bank_account": { "type": "object", "description": "Information about the payer's bank account.", "properties": { "holder": { "type": "object", "description": "Information about the holder of the payer's bank account.", "properties": { "identifier": { "type": "string", "description": "The identifier of the holder of the payer bank account. Can be either a CPF (11 characters) or CNPJ (14 characters).", "minLength": 11, "maxLength": 14, "example": "12345678902" } } }, "details": { "type": "object", "description": "Details of the payer's bank account.", "properties": { "institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the payer's bank." }, "code": { "type": "string", "description": "The ISPB code of the payer's bank.", "example": "123345" }, "account_type": { "type": "string", "description": "The type of the payer's bank account. Can be either `CHECKINGS`, `SAVINGS`, or `PAYMENTS`.", "example": "CHECKINGS" }, "agency": { "type": "string", "description": "The agency number of the payer's bank account.", "example": "1234" }, "number": { "type": "string", "description": "The account number of the payer's bank account.", "example": "123456789" } } } } } } }, "metadata": { "$ref": "#/components/schemas/metadata__payments" }, "next": { "type": "string", "format": "uuid", "nullable": true, "description": "The Belvo ID of the next Charge in the sequence (only applicable if the Charge was retried). If `null`, it indicates that there are no further Charges in the sequence.", "example": "7d159b21-9f25-4365-9fa2-734d20797819" }, "previous": { "type": "string", "format": "uuid", "nullable": true, "description": "The Belvo ID of the previous Charge in the sequence (only applicable if the Charge was retried). If `null`, it indicates that there are no previous Charges in the sequence.", "example": "7d159b21-9f25-4365-9fa2-734d20797818" } } }, "updated_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the data point was updated in Belvo's database.\n", "example": "2022-02-09T08:45:50.406032Z" }, "CustomerV2": { "type": "object", "title": "V2 - Customer", "required": [ "id", "created_at", "updated_at", "name", "identifier" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "updated_at": { "$ref": "#/components/schemas/updated_at" }, "name": { "type": "string", "maxLength": 120, "pattern": "^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\\\$%\\d' -]{0,120})$", "description": "The full name or business name of the customer.", "example": "Frangos Enlatados" }, "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^(?:[0-9]{11}|[0-9]{14})$", "description": "The CPF (11 digits) or CNPJ (14 digits) of the customer.\n", "example": "12345678901122" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" } } }, "EnumCustomerType": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "minLength": 8, "maxLength": 10, "description": "The type of customer. Can be either:\n\n - `INDIVIDUAL`\n - `BUSINESS` (Brazil OFPI only)\n", "example": "INDIVIDUAL" }, "EnumPaymentsCountry": { "type": "string", "nullable": true, "enum": [ "BRA", "null" ], "maxLength": 3, "description": "The customer's country of residence.\n- BRA (🇧🇷 Brazil)\n", "example": "BRA" }, "EnumCustomerIdentifierTypeOfpi": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "The customer's ID document type. For Brazil, this can be either:\n\n- `CPF` (when `customer_type` is `INDIVIDUAL`)\n- `CNPJ` (when `customer_type` is `BUSINESS`)\n", "example": "CPF" }, "CustomerOfpi": { "type": "object", "title": "V1 - Customer", "required": [ "id", "created_at", "created_by", "customer_type", "name", "country", "email", "identifier", "identifier_type" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "customer_type": { "$ref": "#/components/schemas/EnumCustomerType" }, "name": { "type": "string", "nullable": true, "minLength": 5, "maxLength": 200, "description": "The full name of the customer.\n", "example": "Gustavo Veloso" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "country": { "$ref": "#/components/schemas/EnumPaymentsCountry" }, "email": { "type": "string", "nullable": true, "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", "description": "The customer's email address.\n", "example": "gustavo.veloso@musicabrazil.br" }, "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "description": "The document number of the customer's ID (depending on the `identifier_type`).\n", "example": "00000000000191" }, "identifier_type": { "$ref": "#/components/schemas/EnumCustomerIdentifierTypeOfpi" }, "address": { "type": "string", "nullable": true, "minLength": 5, "maxLength": 150, "description": "The customers physical address.\n", "example": "Rua de Gustavo Veloso 432, 70200 Brasilia" }, "phone": { "type": "string", "nullable": true, "pattern": "\\+55\\d{11}$", "description": "The customer's phone number.\n", "example": "+5511987654321" } } }, "CreateCustomerV2": { "type": "object", "title": "V2 - Create Customer", "required": [ "identifier", "name" ], "properties": { "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^(?:[0-9]{11}|[0-9]{14})$", "description": "The CPF (11 digits) or CNPJ (14 digits) of the customer.\n", "example": "12345678901122" }, "name": { "type": "string", "maxLength": 120, "pattern": "^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\\\$%\\d' -]{0,120})$", "description": "The full name or business name of the customer.", "example": "Frangos Enlatados" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" } } }, "CreateCustomerOfpi": { "type": "object", "title": "V1 - Create Customer", "description": "Create a customer for Payment Initiation", "required": [ "identifier" ], "properties": { "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "description": "The customer's CPF or CNPJ number.\n", "example": "10187609363" }, "name": { "type": "string", "minLength": 5, "maxLength": 200, "description": "The full name of the customer you want to create.\n", "example": "Gustavo Veloso" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "email": { "type": "string", "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", "description": "The customer's email address.\n", "example": "gustavo.veloso@musicabrazil.br" }, "phone": { "type": "string", "nullable": true, "pattern": "\\+55\\d{11}$", "description": "The customer's phone number.\n", "example": "+5511987654321" }, "address": { "type": "string", "nullable": true, "description": "The customer's physical address.\n", "example": "Rua de Gustavo Veloso 432, 70200 Brasilia" } } }, "400_validation_error": { "type": "object", "title": "Validation Error", "required": [ "code", "message", "request_id" ], "description": "This error occurs when the parameters provided did not match the expected fields or the item you are trying to create is already in our database, leading to a field validation errors.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`null`, `does_not_exist`, `required`, `already_registered`, `invalid_choice`, `max_length`, `min_length`, `blank`, `null`, `cancellation_error`, `idempotency_key_invalid`) that allows you to classify and handle the error programmatically.\n", "example": "required" }, "message": { "type": "string", "description": "A short description of the error.\n\n\nThe description can be (among others):\n\n - `This field is required.`\n - `Object with name=narnia does not exist.`\n - `This field may not be null.`\n - `This field may not be blank.`\n - `This customer is already registered`\n - `Ensure this field has at least 2 characters.`\n - `Ensure this field has no more than 4 characters.`\n - `Entered value is not valid.`\n - `You must set all required fields: username, password, username_type.`\n - `Payment Intent cannot be canceled because it is not SCHEDULED.`\n - `Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.`\n - `The provided idempotency key is invalid.`\n", "example": "This field is required." }, "request_id": { "$ref": "#/components/schemas/request_id" }, "field": { "type": "string", "nullable": true, "description": "Name of the field where the error was encountered.\n\n> **Note**: This field is only present when the error is related to a specific field.\n", "example": "institution" } } }, "BankAccountV2": { "type": "object", "title": "V2 - Bank Account", "required": [ "id", "created_at", "updated_at", "active", "external_id", "metadata", "holder", "details" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "updated_at": { "$ref": "#/components/schemas/updated_at" }, "active": { "type": "boolean", "description": "Indicates if the bank account is active (and can be used to receive funds).", "example": true }, "holder": { "type": "object", "description": "Details of the account holder.", "required": [ "name", "identifier" ], "properties": { "name": { "type": "string", "maxLength": 120, "pattern": "^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\\\$%\\d' -]{0,120})$", "description": "The full name or business name of the account holder.", "example": "Frangos Enlatados" }, "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^(?:[0-9]{11}|[0-9]{14})$", "description": "The CPF (11 digits) or CNPJ (14 digits) of the account holder.\n", "example": "12345678901122" } } }, "details": { "type": "object", "description": "Details of the bank account.", "required": [ "account_type", "agency", "institution", "number" ], "properties": { "institution": { "type": "string", "format": "uuid", "description": "The Belvo ID of the financial institution.", "example": "f512d996-583a-4a91-8b5b-eba2e103b068" }, "account_type": { "type": "string", "enum": [ "CHECKINGS", "SAVINGS", "PAYMENTS" ], "description": "The type of bank account. Can be either:\n - `CHECKINGS` (also known as Conta Corrente in Brazil)\n - `SAVINGS` (also known as Conta Poupança in Brazil)\n - `PAYMENTS` (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)\n", "example": "CHECKINGS" }, "agency": { "type": "string", "minLength": 1, "maxLength": 4, "pattern": "^[0-9]{1,4}$", "description": "The agency (branch number) of the institution where the account was created.", "example": "0444" }, "number": { "type": "string", "pattern": "^[0-9]{1,20}$", "minLength": 1, "maxLength": 20, "description": "The bank account number.\n\n{% admonition type=\"info\" name=\"Valid Account Number characters\" %}\n You can only send through numbers (`^[0-9]+$`) in the string. For example, `\"457220\"` is a valid bank account number, while \"`45722-0`\" is invalid as it contains a hyphen (`-`).\n{% /admonition %}\n", "example": "457220" } } }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "metadata": { "$ref": "#/components/schemas/metadata__payments" } } }, "EnumBankAccountPixAccountTypeOfpi": { "type": "string", "enum": [ "CHECKINGS", "SAVINGS", "SALARY", "PAYMENTS" ], "description": "The type of bank account. Can be either:\n\n - `CHECKINGS` (also known as Conta Corrente in Brazil)\n - `SAVINGS` (also known as Conta Poupança in Brazil)\n - `SALARY` (also known as Conta Salário in Brazil)\n - `PAYMENTS` (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)\n", "example": "CHECKINGS" }, "BankAccountDetailsOfpi": { "type": "object", "title": "OFPI (PIX Account Information)", "description": "Information regarding the bank account.", "required": [ "account_type", "agency", "number" ], "properties": { "account_type": { "$ref": "#/components/schemas/EnumBankAccountPixAccountTypeOfpi" }, "agency": { "type": "string", "minLength": 1, "maxLength": 4, "pattern": "^[0-9]{1,4}$", "description": "The agency (branch number) of the institution where the account was created.", "example": "0444" }, "number": { "type": "string", "pattern": "^[0-9]{1,20}$", "minLength": 1, "maxLength": 20, "description": "The bank account number.\n\n> 📘 Valid account number characters\n>\n> You can only send through numbers (`^[0-9]+$`) in the string. For example, `\"457220\"` is a valid bank account number, while \"`45722-0`\" is invalid as it contains a hyphen (`-`).\n", "example": "457220" } } }, "HolderInformationIndividualOfpiResponse": { "type": "object", "title": "INDIVIDUAL", "description": "Details regarding the individual bank account holder.", "required": [ "first_name", "last_name", "identifier", "identifier_type" ], "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The bank account holder's first name.", "example": "Dom" }, "last_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The bank account holder's last name.", "example": "Mesa" }, "identifier_type": { "type": "string", "enum": [ "CPF" ], "description": "The customer's ID document type. For individuals in Brazil, this must be set to `CPF`.\n" }, "identifier": { "type": "string", "minLength": 11, "maxLength": 11, "pattern": "^\\d{11}$", "description": "The document number of the customer's ID.", "example": "00000000191" } } }, "HolderResponseOfpiIndividual": { "type": "object", "title": "OFPI Brazil 🇧🇷 INDIVIDUAL", "required": [ "type", "information" ], "description": "Details regarding the individual bank account holder.", "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL" ], "description": "The type of bank account. For individuals, this must be set to `INDIVIDUAL`.", "example": "INDIVIDUAL", "default": "INDIVIDUAL" }, "information": { "$ref": "#/components/schemas/HolderInformationIndividualOfpiResponse" } } }, "HolderInformationBusinessOfpiResponse": { "type": "object", "title": "BUSINESS", "required": [ "name", "identifier", "identifier_type" ], "description": "Details regarding the individual bank account holder.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The bank account holder's first name.", "example": "Gustavo Veloso Entertainment Universe" }, "identifier_type": { "type": "string", "enum": [ "CNPJ" ], "description": "The customer's ID document type. For businesses in Brazil, this must be set to `CNPJ`.\n", "example": "CNPJ", "default": "CNPJ" }, "identifier": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The CNPJ document number.", "example": "00000000000191" } } }, "HolderResponseOfpiBusiness": { "type": "object", "title": "OFPI Brazil 🇧🇷 BUSINESS", "required": [ "type", "information" ], "description": "Details regarding the business bank account holder.", "properties": { "type": { "type": "string", "enum": [ "BUSINESS" ], "description": "The type of bank account. For businesses, this must be set to `BUSINESS`.", "example": "BUSINESS", "default": "BUSINESS" }, "information": { "$ref": "#/components/schemas/HolderInformationBusinessOfpiResponse" } } }, "BankAccountOfpiResponse": { "type": "object", "title": "V1 - Bank Account (No Request Header)", "required": [ "id", "created_at", "institution", "created_by", "holder", "customer", "details" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "customer": { "type": "string", "nullable": true, "format": "uuid", "description": "Belvo's unique ID for the customer associated with the bank account.\n\nFor `BUSINESS` bank accounts, this field is `null`.\n", "example": null }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "institution": { "type": "string", "nullable": true, "format": "uuid", "description": "Belvo's unique ID for the institution that the bank account is created in.\n\nFor `BUSINESS` bank accounts that Belvo creates for organizations, this field is set to `null`.\n", "example": null }, "details": { "$ref": "#/components/schemas/BankAccountDetailsOfpi" }, "holder": { "oneOf": [ { "$ref": "#/components/schemas/HolderResponseOfpiIndividual" }, { "$ref": "#/components/schemas/HolderResponseOfpiBusiness" } ] } } }, "CreateBankAccountV2": { "type": "object", "title": "V2 - Bank Account", "required": [ "holder", "details" ], "properties": { "holder": { "type": "object", "description": "Details of the account holder.", "required": [ "name", "identifier" ], "properties": { "name": { "type": "string", "maxLength": 120, "pattern": "^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\\\$%\\d' -]{0,120})$", "description": "The full name or business name of the account holder.", "example": "Frangos Enlatados" }, "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^(?:[0-9]{11}|[0-9]{14})$", "description": "The CPF (11 digits) or CNPJ (14 digits) of the account holder.\n", "example": "12345678901122" } } }, "details": { "type": "object", "description": "Details of the bank account.", "required": [ "account_type", "agency", "institution", "number" ], "properties": { "account_type": { "type": "string", "enum": [ "CHECKINGS", "SAVINGS", "PAYMENTS" ], "description": "The type of bank account. Can be either:\n - `CHECKINGS` (also known as Conta Corrente in Brazil)\n - `SAVINGS` (also known as Conta Poupança in Brazil)\n - `PAYMENTS` (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)\n", "example": "CHECKINGS" }, "agency": { "type": "string", "minLength": 1, "maxLength": 4, "pattern": "^[0-9]{1,4}$", "description": "The agency (branch number) of the institution where the account was created.", "example": "0444" }, "institution": { "type": "string", "format": "uuid", "description": "The Belvo ID of the financial institution.", "example": "f512d996-583a-4a91-8b5b-eba2e103b068" }, "number": { "type": "string", "pattern": "^[0-9]{1,20}$", "minLength": 1, "maxLength": 20, "description": "The bank account number.\n\n{% admonition type=\"info\" name=\"Valid Account Number characters\" %}\n You can only send through numbers (`^[0-9]+$`) in the string. For example, `\"457220\"` is a valid bank account number, while \"`45722-0`\" is invalid as it contains a hyphen (`-`).\n{% /admonition %}\n", "example": "457220" } } }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "metadata": { "$ref": "#/components/schemas/metadata__payments" } } }, "CreateBankAccountOfpiBusiness": { "type": "object", "title": "V1 - OFPI Business", "required": [ "institution", "holder", "details" ], "properties": { "institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the institution that the bank account is created in.", "example": "f512d996-583a-4a91-8b5b-eba2e103b068" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "holder": { "type": "object", "title": "OFPI", "required": [ "type", "information" ], "description": "Details regarding the business bank account holder.", "properties": { "type": { "type": "string", "enum": [ "BUSINESS" ], "description": "The type of bank account. For business bank accounts, this must be set to `BUSINESS`.", "example": "BUSINESS", "default": "BUSINESS" }, "information": { "type": "object", "description": "Additional information about the bank account holder required in order to create the account for OFPI.", "title": "BUSINESS", "required": [ "name", "identifier", "identifier_type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The full name of the business", "example": "Gustavo Veloso Entertainment Universe" }, "identifier_type": { "type": "string", "enum": [ "CNPJ" ], "description": "The customer's ID document type. For businesses in Brazil, this must be set to `CNPJ`.\n", "example": "CNPJ", "default": "CNPJ" }, "identifier": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^\\d{14}$", "description": "The CNPJ document number.", "example": "00000000000191" } } } } }, "details": { "$ref": "#/components/schemas/BankAccountDetailsOfpi" } } }, "CreateBankAccountOfpiIndividual": { "type": "object", "title": "V1 - OFPI Individual", "required": [ "institution", "holder", "details" ], "properties": { "institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the institution that the bank account is created in.", "example": "f512d996-583a-4a91-8b5b-eba2e103b068" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "holder": { "type": "object", "title": "OFPI", "required": [ "type", "information" ], "description": "Details regarding the individual bank account holder.", "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL" ], "description": "The type of bank account. For individuals, this must be set to `INDIVIDUAL`.", "example": "INDIVIDUAL", "default": "INDIVIDUAL" }, "information": { "type": "object", "description": "Additional information about the bank account holder required in order to create the account for OFPI.", "title": "INDIVIDUAL", "required": [ "first_name", "last_name", "identifier", "identifier_type" ], "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The bank account holder's first name.", "example": "Gustavo" }, "last_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The bank account holder's last name.", "example": "Veloso" }, "identifier_type": { "type": "string", "enum": [ "CPF" ], "description": "The customer's ID document type. For individuals in Brazil, this must be set to `CPF`.\n", "example": "CPF", "default": "CPF" }, "identifier": { "type": "string", "minLength": 11, "maxLength": 11, "pattern": "^\\d{11}$", "description": "The document number of the customer's ID.", "example": "00000000191" } } } } }, "details": { "$ref": "#/components/schemas/BankAccountDetailsOfpi" } } }, "EnumPaymentIntentStatus": { "type": "string", "enum": [ "REQUIRES_PAYMENT_METHOD", "REQUIRES_ACTION", "SUCCEEDED", "PROCESSING", "FAILED" ], "description": "The current status of the payment intent.\n", "example": "REQUIRES_ACTION" }, "EnumPaymentLinkAllowedPaymentMethod": { "type": "string", "enum": [ "open_finance", "open_finance_biometric_pix" ], "description": "Selected payment method type. For 🇧🇷 Brazil's OFPI, can be either:\n\n - `open_finance`: For regular payments.\n - `open_finance_biometric_pix`: For biometric payments using the PIX network.\n", "example": "open_finance" }, "PaymentIntentPaymentMethodDetailsBodyIndividualOfpi": { "type": "object", "description": "Payment method type selected.", "required": [ "beneficiary_bank_account", "payer_institution", "callback_url" ], "properties": { "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "schedule": { "$ref": "#/components/schemas/schedule" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.\n", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "nullable": true, "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "23******00" } } }, "PaymentIntentPaymentMethodDetailsIndividualOfpi": { "type": "object", "title": "INDIVIDUAL", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualOfpi" } } }, "PaymentIntentPaymentMethodDetailsBodyBusinessOfpi": { "type": "object", "description": "Payment method type selected.", "required": [ "beneficiary_bank_account", "payer_institution", "callback_url", "cpf" ], "properties": { "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "schedule": { "$ref": "#/components/schemas/schedule" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.\n", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "nullable": true, "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "23******00" } } }, "PaymentIntentPaymentMethodDetailsBusinessOfpi": { "type": "object", "title": "BUSINESS", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessOfpi" } } }, "LastErrorPaymentError": { "type": "object", "title": "payment_error", "description": "Information about the error you ran into in the previous step of the payment intent, if applicable. This error can occur when something unexpected happened during the payment intent process.", "required": [ "error_code", "error_message" ], "properties": { "error_code": { "type": "string", "description": "A unique error code (`payment_error`) that allows you to classify and handle the error programmatically.\n", "example": "payment_error" }, "error_message": { "type": "string", "description": "A short description of the error.\n", "example": "Unexpected error to confirm the payment" } } }, "InstitutionFormField": { "type": "object", "properties": { "name": { "type": "string", "description": "The username, password, or username type field.", "example": "username" }, "type": { "type": "string", "description": "The input type for the form field. For example, string.", "example": "text" }, "label": { "type": "string", "description": "The label of the form field. For example:\n- Document\n- Clave\n- Token\n", "example": "Document" }, "dependency": { "type": "string", "nullable": true, "description": "Indicates whether or not this parameter depends on another parameter being provided. For example, if this field `dependency` = `username_type`, this means that you must also send through the `username_type` parameter.\n", "example": "username_type" }, "validation": { "type": "string", "description": "The type of input validation used for the field.", "example": "^.{1,}$" }, "placeholder": { "type": "string", "description": "The placeholder text in the form field.", "example": "Username" }, "validation_message": { "type": "string", "description": "The message displayed when an invalid input is provided in the form field.", "example": "Invalid client number" }, "values": { "type": "array", "description": "Array of additional form field values.\n", "items": { "$ref": "#/components/schemas/InstitutionsFormFieldValues" } }, "length": { "type": "integer", "description": "Number of digits allowed when the type is `token`.\n", "example": 6 }, "optional": { "type": "boolean", "description": "It indicates whether this form field is optional.\n", "example": false } } }, "InstitutionFormFieldUsernameType": { "type": "object", "properties": { "name": { "type": "string", "description": "The username, password, or username type field.", "example": "username" }, "type": { "type": "string", "description": "The input type for the form field. For example, string.", "example": "text" }, "placeholder": { "type": "string", "description": "The placeholder text in the form field.", "example": "Username" }, "values": { "type": "array", "description": "Array of additional form field values.\n", "items": { "$ref": "#/components/schemas/InstitutionsFormFieldValues" } }, "preselected": { "type": "integer", "description": "Indicated which option from the `username_type`s array is automatically preselected for the user.\n", "example": 6 } } }, "InstitutionFormFieldSaveCredentials": { "type": "object", "properties": { "name": { "type": "string", "description": "Whether or not the user wants to save the credentials for this institution for future payments.", "example": "save_credentials" }, "type": { "type": "string", "description": "The input type for the form field. For `save_credentials`, this is set to `checkbox`.", "example": "checkbox" }, "label": { "type": "string", "description": "The label of the form field. For `save_credentials`, this is set to `Recuérdame para futuros pagos``.\n", "example": "Recuérdame para futuros pagos" }, "validation": { "type": "string", "nullable": true, "description": "The type of input validation used for the field. For `save_credentials`, this is `null`.", "example": null } } }, "paymentInstitution": { "type": "object", "required": [ "id", "active", "name", "display_name", "legal_entity_name", "website", "logo", "icon_logo", "text_logo", "primary_color", "country", "form_fields", "sort_priority", "description" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "active": { "type": "boolean", "description": "Indicates whether this institution is available for use or not.", "example": true }, "name": { "type": "string", "description": "The name of the institution, as designated by Belvo.", "example": "wakanda_national" }, "display_name": { "type": "string", "description": "The customer-facing name of the institution.", "example": "Wakanda National Bank" }, "legal_entity_name": { "type": "string", "nullable": true, "description": "The name of the legal entity of the institution, as registered with the relevant regulatory authority. Only applicable for 🇧🇷 Brazil OFPI.\n", "example": "Wakanda Bank, National Association" }, "website": { "type": "string", "description": "The URL of the institution's website.", "example": "https://www.wakandanational.com" }, "logo": { "type": "string", "description": "The URL of the institution's logo.", "example": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_logo.svg" }, "icon_logo": { "type": "string", "description": "The URL of the institution's icon logo.", "example": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_icon_logo.svg" }, "text_logo": { "type": "string", "description": "The URL of the institution's text logo.", "example": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_text_logo.svg" }, "primary_color": { "type": "string", "description": "The primary color on the institution's website.", "example": "#fdbc24" }, "country": { "$ref": "#/components/schemas/EnumPaymentsCountry" }, "form_fields": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/InstitutionFormField" }, { "$ref": "#/components/schemas/InstitutionFormFieldUsernameType" }, { "$ref": "#/components/schemas/InstitutionFormFieldSaveCredentials" } ] } }, "sort_priority": { "type": "integer", "format": "int32", "description": "Number that represents the order in which the institution should be displayed in an application, with `1` being the highest.\n", "example": 1 }, "description": { "type": "string", "nullable": true, "description": "A brief description of the insitution.", "example": "Simple, transparent and secure: Wakanda Bank is the leading financial technology company in Latin America." } } }, "DisplayPaymentMethodInformationContentOfpi": { "type": "object", "title": "Display Open Finance Brazil payment method information", "description": "Object detailing what payment method information you need to display.", "properties": { "institutions": { "type": "array", "description": "An array of institution objects.\n", "items": { "$ref": "#/components/schemas/paymentInstitution" } } } }, "NextStepDisplayPaymentMethodInformation": { "type": "object", "title": "OFPI - Display Payment Method Information", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "type": { "type": "string", "enum": [ "open_finance_display_payment_method_information", "open_finance_display_confirmation_required", "open_finance_display_needs_redirect", "open_finance_display_payment_processing", "open_finance_display_payment_succeeded", "open_finance_display_payment_failed" ], "description": "The type of `next_step` you need to follow.\n", "example": "open_finance_display_payment_method_information" }, "open_finance_display_payment_method_information": { "$ref": "#/components/schemas/DisplayPaymentMethodInformationContentOfpi" }, "ready_to_confirm": { "type": "boolean", "default": false, "description": "Boolean that indicates whether the payment intent is ready to be confirmed. \n\n **Note:** When set to `true`, you need to confirm the payment by making a PATCH request sending through `confirm: true`.\n", "example": false } } }, "NeedsRedirectContent": { "type": "object", "description": "Details regarding the payer institution.", "properties": { "payer_institution": { "$ref": "#/components/schemas/paymentInstitution" } } }, "NextStepNeedsRedirect": { "type": "object", "title": "OFPI - Needs Redirect", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "type": { "type": "string", "enum": [ "open_finance_display_payment_method_information", "open_finance_display_confirmation_required", "open_finance_display_needs_redirect", "open_finance_display_payment_processing", "open_finance_display_payment_succeeded", "open_finance_display_payment_failed" ], "description": "The type of `next_step` you need to follow.\n", "example": "open_finance_display_needs_redirect" }, "open_finance_display_needs_redirect": { "$ref": "#/components/schemas/NeedsRedirectContent" }, "ready_to_confirm": { "type": "boolean", "default": false, "description": "Boolean that indicates whether the payment intent is ready to be confirmed. \n\n **Note:** When set to `true`, you need to confirm the payment by making a PATCH request sending through `confirm: true`.\n", "example": false } } }, "BankAccountDetailsOpenFinance": { "type": "object", "title": "OFPI (PIX Account Information)", "required": [ "country", "account_type", "agency", "number" ], "properties": { "country": { "$ref": "#/components/schemas/EnumPaymentsCountry" }, "account_type": { "$ref": "#/components/schemas/EnumBankAccountPixAccountTypeOfpi" }, "agency": { "type": "string", "description": "The agency (branch number) of the institution where the account was created.", "example": "0444" }, "number": { "type": "string", "description": "The bank account number.", "example": "45722-0" } } }, "BankAccountDetailsOpenFinancePix": { "type": "object", "title": "OFPI (PIX Keys)", "required": [ "country", "pix_key" ], "properties": { "country": { "$ref": "#/components/schemas/EnumPaymentsCountry" }, "pix_key": { "type": "string", "description": "The PIX key identifier of the bank account.", "example": "RANDOM://6c1c236c-a035-4b80-ab12-e38f88ce82ab" } } }, "EnumBankAccountHolderTypeOfpi": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "description": "The type of bank account. Can be either `INDIVIDUAL` or `BUSINESS`.", "example": "BUSINESS" }, "HolderResponseOfpi": { "type": "object", "title": "OFPI", "required": [ "type", "information" ], "description": "Details regarding the bank account holder.", "properties": { "type": { "$ref": "#/components/schemas/EnumBankAccountHolderTypeOfpi" }, "information": { "oneOf": [ { "$ref": "#/components/schemas/HolderInformationBusinessOfpiResponse" }, { "$ref": "#/components/schemas/HolderInformationIndividualOfpiResponse" } ] } } }, "BeneficiaryBankAccountOfpi": { "type": "object", "title": "Beneficiary Bank Account", "required": [ "id", "created_at", "created_by", "customer", "institution", "number", "holder" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "institution": { "$ref": "#/components/schemas/paymentInstitution" }, "details": { "oneOf": [ { "$ref": "#/components/schemas/BankAccountDetailsOpenFinance" }, { "$ref": "#/components/schemas/BankAccountDetailsOpenFinancePix" } ] }, "holder": { "$ref": "#/components/schemas/HolderResponseOfpi" } } }, "DisplayConfirmationRequiredOfpi": { "type": "object", "title": "Display Open Finance Brazil confirmation required", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "beneficiary_bank_account": { "$ref": "#/components/schemas/BeneficiaryBankAccountOfpi" }, "payer_name": { "type": "string", "description": "The name of the payer.", "example": "Gustavo Veloso" }, "payer_identifier": { "type": "string", "description": "The payer's ID.", "example": "LV890273900-23" }, "payer_institution": { "$ref": "#/components/schemas/paymentInstitution" } } }, "NextStepDisplayConfirmationRequiredOfpi": { "type": "object", "title": "OFPI - Display Confirmation Required", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "type": { "type": "string", "enum": [ "open_finance_display_payment_method_information", "open_finance_display_confirmation_required", "open_finance_display_needs_redirect", "open_finance_display_payment_processing", "open_finance_display_payment_succeeded", "open_finance_display_payment_failed" ], "description": "The type of `next_step` you need to follow.\n", "example": "open_finance_display_confirmation_required" }, "open_finance_display_confirmation_required": { "$ref": "#/components/schemas/DisplayConfirmationRequiredOfpi" }, "ready_to_confirm": { "type": "boolean", "default": true, "description": "Boolean that indicates whether the payment intent is ready to be confirmed. \n\n **Note:** When set to `true`, you need to confirm the payment by making a PATCH request sending through `confirm: true`.\n", "example": true } } }, "DisplayPaymentProcessing": { "type": "object", "description": "Details regarding the payer institution.", "properties": { "payer_institution": { "$ref": "#/components/schemas/paymentInstitution" } } }, "NextStepDisplayPaymentProcessing": { "type": "object", "title": "OFPI - Payment Processing", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "type": { "type": "string", "enum": [ "open_finance_display_payment_method_information", "open_finance_display_confirmation_required", "open_finance_display_needs_redirect", "open_finance_display_payment_processing", "open_finance_display_payment_succeeded", "open_finance_display_payment_failed" ], "description": "The type of `next_step` you need to follow.\n", "example": "open_finance_display_payment_processing" }, "open_finance_display_payment_processing": { "$ref": "#/components/schemas/DisplayPaymentProcessing" }, "ready_to_confirm": { "type": "boolean", "default": false, "description": "Boolean that indicates whether the payment intent is ready to be confirmed. \n\n **Note:** When set to `true`, you need to confirm the payment by making a PATCH request sending through `confirm: true`.\n", "example": false } } }, "DisplayPaymentSucceeded": { "type": "object", "description": "Details regarding the payer institution.", "properties": { "payer_institution": { "$ref": "#/components/schemas/paymentInstitution" } } }, "NextStepDisplayPaymentSucceeded": { "type": "object", "title": "OFPI - Payment Succeeded", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "type": { "type": "string", "enum": [ "open_finance_display_payment_method_information", "open_finance_display_confirmation_required", "open_finance_display_needs_redirect", "open_finance_display_payment_processing", "open_finance_display_payment_succeeded", "open_finance_display_payment_failed" ], "description": "The type of `next_step` you need to follow.\n", "example": "open_finance_display_payment_succeeded" }, "open_finance_display_payment_succeeded": { "$ref": "#/components/schemas/DisplayPaymentSucceeded" }, "ready_to_confirm": { "type": "boolean", "default": false, "description": "Boolean that indicates whether the payment intent is ready to be confirmed. \n\n **Note:** When set to `true`, you need to confirm the payment by making a PATCH request sending through `confirm: true`.\n", "example": false } } }, "DisplayPaymentFailed": { "type": "object", "description": "Details regarding the payer institution.", "properties": { "payer_institution": { "$ref": "#/components/schemas/paymentInstitution" } } }, "NextStepDisplayPaymentFailed": { "type": "object", "title": "OFPI - Payment Failed", "description": "Object detailing the next steps you should follow for a specific `next_step` type.\n", "properties": { "type": { "type": "string", "enum": [ "open_finance_display_payment_method_information", "open_finance_display_confirmation_required", "open_finance_display_needs_redirect", "open_finance_display_payment_processing", "open_finance_display_payment_succeeded", "open_finance_display_payment_failed" ], "description": "The type of `next_step` you need to follow.\n", "example": "open_finance_display_payment_failed" }, "open_finance_display_payment_failed": { "$ref": "#/components/schemas/DisplayPaymentFailed" }, "ready_to_confirm": { "type": "boolean", "default": false, "description": "Boolean that indicates whether the payment intent is ready to be confirmed. \n\n **Note:** When set to `true`,you need to confirm the payment by making a PATCH request sending through `confirm: true`.\n", "example": false } } }, "PaymentIntentOfpi": { "type": "object", "title": "Bank Account", "required": [ "id", "created_at", "created_by", "customer", "allowed_payment_method_types", "amount", "currency", "description", "failure_code", "failure_message", "next_step", "last_error", "payment_method_details", "payment_method_information", "provider", "status", "updated_at", "selected_payment_method_type" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the customer related to this payment intent.", "example": "1c83ead8-6665-429c-a17a-ddc76cb3a95e" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the payment intent was last updated.\n", "example": "2022-02-09T08:45:50.406032Z" }, "status": { "$ref": "#/components/schemas/EnumPaymentIntentStatus" }, "amount": { "type": "string", "description": "Amount to be paid by your customer.\n", "example": "1234.12" }, "currency": { "$ref": "#/components/schemas/EnumPaymentsCurrency" }, "description": { "type": "string", "description": "The description of the payment.\n", "example": "Training shoes" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "selected_payment_method_type": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For OFPI, the value will be `open_finance`.", "items": { "type": "string", "example": "open_finance" } }, "payment_method_details": { "description": "Details about the OFPI payment method.", "anyOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsIndividualOfpi" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBusinessOfpi" } ] }, "payment_method_information": { "$ref": "#/components/schemas/PaymentMethodInformationOfpi" }, "failure_code": { "type": "string", "nullable": true, "description": "Error code that explains the reason behind a payment being unsuccessful (if applicable).\n", "example": null }, "failure_message": { "type": "string", "nullable": true, "description": "Further information regarding the `failure_code`.\n", "example": null }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "charges": { "type": "array", "description": "An array of charge objects related to this payment intent. If no charges are associated, we return an empty array.\n", "items": { "$ref": "#/components/schemas/ChargeBrazil" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" }, "last_error": { "deprecated": true, "description": "**Note**: This field has been deprecated and will be removed from the API in the future.\n\n*Information about the error you ran into in the previous step of the payment intent, if applicable. This error can occur when something unexpected happened during the payment intent process.*\n", "oneOf": [ { "$ref": "#/components/schemas/LastErrorPaymentError" } ] }, "next_step": { "deprecated": true, "description": "**Note**: This field has been deprecated and will be removed from the API in the future.\n\n*Object detailing the next steps you should follow for a specific `next_step` type.*\n", "oneOf": [ { "$ref": "#/components/schemas/NextStepDisplayPaymentMethodInformation" }, { "$ref": "#/components/schemas/NextStepNeedsRedirect" }, { "$ref": "#/components/schemas/NextStepDisplayConfirmationRequiredOfpi" }, { "$ref": "#/components/schemas/NextStepDisplayPaymentProcessing" }, { "$ref": "#/components/schemas/NextStepDisplayPaymentSucceeded" }, { "$ref": "#/components/schemas/NextStepDisplayPaymentFailed" } ] } } }, "scheduled_single-2": { "type": "object", "title": "Single", "description": "Schedule a single (one-off) payment in the future.", "properties": { "single": { "type": "object", "description": "Schedule a single (one-off) payment in the future.", "properties": { "date": { "type": "string", "format": "date", "description": "The date the one-off scheduled payment should be made, in `YYYY-MM-DD` format.\n\n>**Note**: The date must be at least 1 day in the future and no more than 720 days in the future.\n", "example": "2024-10-22" } } } } }, "scheduled_daily-2": { "type": "object", "title": "Daily", "description": "Schedule a daily recurring payment.", "properties": { "daily": { "type": "object", "description": "Schedule a daily recurring payment.", "properties": { "start_date": { "type": "string", "format": "date", "description": "The date the recurring daily payment should start on, in `YYYY-MM-DD` format.\n\n>**Note**: The `start_date` must be at least 1 day in the future.\n", "example": "2024-10-22" }, "occurrences": { "type": "integer", "minimum": 2, "maximum": 60, "description": "The number of times the payment should repeat. \n\n>**Note**: You must schedule at least `2` occurrences and no more than `60`.\n", "example": 10 } } } } }, "scheduled_weekly-2": { "type": "object", "title": "Weekly", "description": "Schedule a weekly recurring payment.", "properties": { "weekly": { "type": "object", "description": "Schedule a weekly recurring payment.", "properties": { "start_date": { "type": "string", "format": "date", "description": "The date the recurring weekly payment should start on, in `YYYY-MM-DD` format.\n\n>**Note**: The `start_date` must correspond to the first `day_of_week` specified and be at least 1 day in the future.\n", "example": "2024-10-22" }, "day_of_week": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "description": "The day of the week the payment should be made. Can be one of the following values:\n\n - `MONDAY`\n - `TUESDAY`\n - `WEDNESDAY`\n - `THURSDAY`\n - `FRIDAY`\n - `SATURDAY`\n - `SUNDAY`\n", "example": "MONDAY" }, "occurrences": { "type": "integer", "minimum": 2, "maximum": 60, "description": "The number of times the payment should repeat. \n\n>**Note**: You must schedule at least `2` occurrences and no more than `60`.\n", "example": 10 } } } } }, "scheduled_monthly-2": { "type": "object", "title": "Monthly", "description": "Schedule a monthly recurring payment.", "properties": { "monthly": { "type": "object", "description": "Schedule a monthly recurring payment.", "properties": { "start_date": { "type": "string", "format": "date", "description": "The date the recurring monthly payment should start on, in `YYYY-MM-DD` format.\n\n>**Note**: The `start_date` must correspond to the first `day_of_month` specified and be at least 1 day in the future.\n", "example": "2024-10-26" }, "day_of_month": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the month the payment should be made. Can be any integer between `1` and `31`.\n", "example": 26 }, "occurrences": { "type": "integer", "minimum": 2, "maximum": 24, "description": "The number of times the payment should repeat. \n\n>**Note**: You must schedule at least `2` occurrences and no more than `24`.\n", "example": 12 } } } } }, "scheduled_custom-2": { "type": "object", "title": "Custom", "description": "Schedule a custom recurring payment.", "properties": { "custom": { "type": "object", "description": "Schedule a custom recurring payment.", "required": [ "dates", "description" ], "properties": { "dates": { "type": "array", "minItems": 2, "maxItems": 60, "description": "The unique dates the recurring payment should be made, in `YYYY-MM-DD` format.\n\n>**Note**: The dates must be at least 1 day in the future and no more than 720 days in the future.\n", "items": { "type": "string", "format": "date", "description": "The date of the payment, in `YYYY-MM-DD` format.\n", "example": "2024-10-22" }, "example": [ "2024-10-22", "2024-10-26" ] }, "description": { "type": "string", "maxLength": 256, "description": "A description of the custom recurring payment that will display to your user when they are redirected to their bank to accept the payment.\n\n> **Note**: We highly recommend that this message be in Brazilian Portuguese, and that it clearly explains the purpose as well as recurring nature of the payment.\n", "example": "Os pagamentos ocorrerão a cada três dias até a data final (30.09.2024)" } } } } }, "schedule-2": { "type": "object", "title": "Schedule a payment", "description": "Details regarding the scheduled payment (optional). For more information on how to schedule payments, please see our dedicated OFPI Scheduled Payments guide.\n", "oneOf": [ { "$ref": "#/components/schemas/scheduled_single-2" }, { "$ref": "#/components/schemas/scheduled_daily-2" }, { "$ref": "#/components/schemas/scheduled_weekly-2" }, { "$ref": "#/components/schemas/scheduled_monthly-2" }, { "$ref": "#/components/schemas/scheduled_custom-2" } ] }, "PaymentIntentPaymentMethodDetailsBodyIndividualRequestPixKey": { "type": "object", "title": "INDIVIDUAL", "description": "Details about the payment method when the customer (payer) is an individual customer.", "required": [ "pix_key", "payer_institution", "callback_url" ], "properties": { "pix_key": { "type": "string", "description": "The Pix key associated with the beneficiary of the transaction. Can be an email, phone number (including the country code, for example `+5511999998888`), CPF/CNPJ, or a random key.\n", "example": "53497b80-81a2-4ea8-9296-83a909c05bdf" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.", "example": "https://www.acmecorp.com/checkout/3487321" }, "schedule": { "$ref": "#/components/schemas/schedule-2" } } }, "PaymentIntentPaymentMethodDetailsBodyBusinessRequestPixKey": { "type": "object", "title": "BUSINESS", "description": "Details about the payment method when the customer (payer) is a business customer.", "required": [ "pix_key", "payer_institution", "callback_url", "cpf" ], "properties": { "pix_key": { "type": "string", "description": "The Pix key associated with the beneficiary of the transaction. Can be an email, phone number (including the country code, for example `+5511999998888`), CPF/CNPJ, or a random key.\n", "example": "53497b80-81a2-4ea8-9296-83a909c05bdf" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "09744477770" }, "schedule": { "$ref": "#/components/schemas/schedule-2" } } }, "CreatePaymentIntentPixKeys": { "type": "object", "title": "Pix Keys (With Existing Customer)", "description": "Create a Payment Intent using a Pix Key as the beneficiary details and using a previously created customer.\n\nNote: When using the Pix Keys method, you will need to make an additional PATCH request.\n", "required": [ "amount", "customer", "description", "allowed_payment_method_types", "payment_method_details", "confirm" ], "properties": { "amount": { "type": "string", "pattern": "\\d+(?:\\.\\d{1,2})?", "example": "1234.12", "description": "Amount to be paid by your customer. You can send through numbers with up to two decimal points, separated by a `.` period. For example: `1234.12` \n" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference your previously created customer.\n", "example": "06dc2f14-1217-4480-9b36-550a944a39d1" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "description": { "type": "string", "description": "A human-readable description of the payment.\n", "example": "Shoe payment" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For Brazil (OFPI), this value must be set to `open_finance`.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" } }, "payment_method_details": { "type": "object", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualRequestPixKey" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessRequestPixKey" } ] } } }, "confirm": { "type": "boolean", "default": false, "description": "Boolean that confirms the payment intent.\n\n**Note:** Sending this parameter set to `true` confirms the payment intent.\n", "example": false }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" } } }, "CreatePaymentIntentPixKeysAndCustomer": { "type": "object", "title": "Pix Keys (With New Customer)", "description": "Create a Payment Intent using a Pix Key as the beneficiary details and using a previously created customer.\n\nNote: When using the Pix Keys method, you will need to make an additional PATCH request.\n", "required": [ "amount", "customer", "description", "allowed_payment_method_types", "payment_method_details", "confirm" ], "properties": { "amount": { "type": "string", "pattern": "\\d+(?:\\.\\d{1,2})?", "example": "1234.12", "description": "Amount to be paid by your customer. You can send through numbers with up to two decimal points, separated by a `.` period. For example: `1234.12` \n" }, "customer": { "$ref": "#/components/schemas/CreateCustomerOfpi" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "description": { "type": "string", "description": "A human-readable description of the payment.\n", "example": "Shoe payment" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For Brazil (OFPI), this value must be set to `open_finance`.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" } }, "payment_method_details": { "type": "object", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualRequestPixKey" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessRequestPixKey" } ] } } }, "confirm": { "type": "boolean", "default": false, "description": "Boolean that confirms the payment intent.\n\n**Note:** Sending this parameter set to `true` confirms the payment intent.\n", "example": false }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" } } }, "PaymentIntentPaymentMethodDetailsBodyIndividualRequestOfpi": { "type": "object", "title": "INDIVIDUAL", "description": "Payment method type selected.", "required": [ "beneficiary_bank_account", "callback_url" ], "properties": { "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "schedule": { "$ref": "#/components/schemas/schedule-2" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.", "example": "https://www.acmecorp.com/checkout/3487321" } } }, "PaymentIntentPaymentMethodDetailsBodyBusinessRequestOfpi": { "type": "object", "title": "BUSINESS", "description": "Payment method type selected.", "required": [ "beneficiary_bank_account", "payer_institution", "callback_url", "cpf" ], "properties": { "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "schedule": { "$ref": "#/components/schemas/schedule-2" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "09744477770" } } }, "CreatePaymentIntentOfpi": { "type": "object", "title": "Bank Account (With Existing Customer)", "description": "Create a payment intent using a bank account as the beneficiary and a previously created customer.", "required": [ "amount", "customer", "description", "allowed_payment_method_types", "payment_method_details", "confirm" ], "properties": { "amount": { "type": "string", "title": "string", "pattern": "\\d+(?:\\.\\d{1,2})?", "example": "1234.12", "description": "Amount to be paid by your customer. For OFPI, you can send through numbers with up to two decimal points, separated by a `.` period. For example: `1234.12` \n" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference your previously created customer.\n", "example": "06dc2f14-1217-4480-9b36-550a944a39d1" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "description": { "type": "string", "description": "A human-readable description of the payment.\n", "example": "Shoe payment" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For Brazil (OFPI), this value must be set to `open_finance`.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" } }, "payment_method_details": { "type": "object", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualRequestOfpi" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessRequestOfpi" } ] } } }, "confirm": { "type": "boolean", "default": false, "description": "Boolean that confirms the payment intent.\n\n**Note:** Sending this parameter set to `true` confirms the payment intent.\n", "example": false }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" } } }, "PaymentIntentPaymentMethodDetailsBodyIndividualRequestOfpiBankAccount": { "type": "object", "title": "INDIVIDUAL", "description": "Payment method type selected.", "required": [ "beneficiary_bank_account", "payer_institution", "callback_url" ], "properties": { "beneficiary_bank_account": { "$ref": "#/components/schemas/CreateBankAccountOfpiIndividual" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.", "example": "https://www.acmecorp.com/checkout/3487321" }, "schedule": { "$ref": "#/components/schemas/schedule-2" } } }, "PaymentIntentPaymentMethodDetailsBodyBusinessRequestOfpiBankAccount": { "type": "object", "title": "BUSINESS", "description": "Payment method type selected.", "required": [ "beneficiary_bank_account", "payer_institution", "callback_url", "cpf" ], "properties": { "beneficiary_bank_account": { "$ref": "#/components/schemas/CreateBankAccountOfpiBusiness" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "schedule": { "$ref": "#/components/schemas/schedule-2" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "09744477770" } } }, "CreatePaymentIntentAndCustomerOfpi": { "type": "object", "title": "Bank Account (With New Customer)", "description": "Create a payment intent using a bank account as the beneficiary and a register a new customer.", "required": [ "amount", "customer", "description", "allowed_payment_method_types", "payment_method_details", "confirm" ], "properties": { "amount": { "type": "string", "title": "string", "pattern": "\\d+(?:\\.\\d{1,2})?", "example": "1234.12", "description": "Amount to be paid by your customer. For OFPI, you can send through numbers with up to two decimal points, separated by a `.` period. For example: `1234.12`\n" }, "customer": { "$ref": "#/components/schemas/CreateCustomerOfpi" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "description": { "type": "string", "description": "A human-readable description of the payment.\n", "example": "Shoe payment" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For Brazil (OFPI), this value must be set to `open_finance`.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" } }, "payment_method_details": { "type": "object", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualRequestOfpiBankAccount" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessRequestOfpiBankAccount" } ] } } }, "confirm": { "type": "boolean", "default": false, "description": "Boolean that confirms the payment intent.\n\n> 📘 Provide `payer_institution`\n>\n> In order to confirm the payment intent (`confirm: true`), you must provide the `payer_institution` parameter.\n\n**Note:** Sending this parameter set to `true` confirms the payment intent.\n", "example": false }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" } } }, "CreatePaymentIntentAndBankAccountAndCustomerOfpi": { "type": "object", "title": "Bank Account (With New Customer and Beneficiary Bank Account)", "description": "Create a customer, bank account, and payment intent for Brazil (OFPI).\n", "required": [ "amount", "customer", "description", "allowed_payment_method_types", "payment_method_details", "confirm" ], "properties": { "amount": { "type": "string", "title": "string", "pattern": "\\d+(?:\\.\\d{1,2})?", "example": "1234.12", "description": "Amount to be paid by your customer. For OFPI, you can send through numbers with up to two decimal points, separated by a `.` period. For example: `1234.12`\n" }, "customer": { "$ref": "#/components/schemas/CreateCustomerOfpi" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "description": { "type": "string", "description": "A human-readable description of the payment.\n", "example": "Shoe payment" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For Brazil (OFPI), this value must be set to `open_finance`.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" } }, "payment_method_details": { "type": "object", "description": "Details about the OFPI payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "oneOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualRequestOfpiBankAccount" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessRequestOfpiBankAccount" } ] } } }, "confirm": { "type": "boolean", "default": false, "description": "Boolean that confirms the payment intent.\n\n> 📘 Provide `payer_institution`\n>\n> In order to confirm the payment intent (`confirm: true`), you must provide the `payer_institution` parameter.\n\n**Note:** Sending this parameter set to `true` confirms the payment intent.\n", "example": false }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" } } }, "PaymentIntentPaymentMethodDetailsBodyIndividualPixKeys": { "type": "object", "description": "Payment method type selected.", "required": [ "pix_key", "payer_institution", "callback_url" ], "properties": { "pix_key": { "type": "string", "description": "The Pix key associated with the beneficiary of the transaction. Can be an email, phone number (including the country code, for example `+5511999998888`), CPF/CNPJ, or a random key.\n\n{% admonition type=\"info\" name=\"Pix Key Masking\" %}\n In the case that the provided Pix Key is a CPF, email address, or phone number, value in `payment_method_details.open_finance.pix_key` will be masked. If it is a CNPJ or random Pix Key UUID, the value will not be masked.\n{% /admonition %}\n", "example": "53497b80-81a2-4ea8-9296-83a909c05bdf" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.\n", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "nullable": true, "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "23******00" }, "schedule": { "$ref": "#/components/schemas/schedule" } } }, "PaymentIntentPaymentMethodDetailsIndividualPixKeys": { "type": "object", "title": "INDIVIDUAL", "description": "Details about the Pix Key payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyIndividualPixKeys" } } }, "PaymentIntentPaymentMethodDetailsBodyBusinessPixKeys": { "type": "object", "description": "Payment method type selected.", "required": [ "pix_key", "payer_institution", "callback_url", "cpf" ], "properties": { "pix_key": { "type": "string", "description": "The Pix key associated with the beneficiary of the transaction. Can be an email, phone number (including the country code, for example `+5511999998888`), CPF/CNPJ, or a random key.\n\n{% admonition type=\"info\" name=\"Pix Key Masking\" %}\n In the case that the provided Pix Key is a CPF, email address, or phone number, value in `payment_method_details.open_finance.pix_key` will be masked. If it is a CNPJ or random Pix Key UUID, the value will not be masked.\n{% /admonition %}\n", "example": "53497b80-81a2-4ea8-9296-83a909c05bdf" }, "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "schedule": { "$ref": "#/components/schemas/schedule" }, "callback_url": { "type": "string", "description": "The callback URL that your user will be redirected to after confirming the payment in their banking application.\n", "example": "https://www.acmecorp.com/checkout/3487321" }, "cpf": { "type": "string", "nullable": true, "description": "The customer's CPF number. Provided when available; this value is obfuscated in responses.\n", "example": "23******00" } } }, "PaymentIntentPaymentMethodDetailsBusinessPixKeys": { "type": "object", "title": "BUSINESS", "description": "Details about the Pix Key payment method.", "required": [ "open_finance" ], "properties": { "open_finance": { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBodyBusinessPixKeys" } } }, "PaymentMethodInformationPixKeysInitial": { "type": "object", "title": "Initial", "description": "Information about the Pix Key payment method at the time of payment intent creation. It will only include the `pix_key_details` property, which you need to show your user to confirm that their details are correct. After they confirm and you send through the PATCH request, this object will be populated with additional properties (see the **Confirmed** schema).\n", "properties": { "open_finance": { "type": "object", "title": "Pix Key", "properties": { "pix_key_details": { "type": "object", "description": "Details about the Pix Key used for the payment. You need to display this information to your user for them to confirm that the details are correct. After they confirm, you can send a PATCH request to confirm the Payment Intent.", "properties": { "identifier": { "type": "string", "description": "The masked identifier of the owner.\n", "example": "23******00" }, "name": { "type": "string", "description": "The name of the Pix Key holder.", "example": "João da Silva" } } } } } } }, "PaymentIntentPixKeys": { "type": "object", "title": "Pix Key", "required": [ "id", "created_at", "created_by", "customer", "allowed_payment_method_types", "amount", "currency", "description", "failure_code", "failure_message", "next_step", "last_error", "payment_method_details", "payment_method_information", "provider", "status", "updated_at", "selected_payment_method_type" ], "properties": { "id": { "$ref": "#/components/schemas/id" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the customer related to this payment intent.", "example": "1c83ead8-6665-429c-a17a-ddc76cb3a95e" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "created_at": { "$ref": "#/components/schemas/created_at" }, "created_by": { "$ref": "#/components/schemas/created_by" }, "updated_at": { "type": "string", "nullable": true, "format": "date-time", "description": "The ISO-8601 timestamp of when the payment intent was last updated.\n", "example": "2022-02-09T08:45:50.406032Z" }, "status": { "$ref": "#/components/schemas/EnumPaymentIntentStatus" }, "amount": { "type": "string", "description": "Amount to be paid by your customer.\n", "example": "1234.12" }, "currency": { "$ref": "#/components/schemas/EnumPaymentsCurrency" }, "description": { "type": "string", "description": "The description of the payment.\n", "example": "Training shoes" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "selected_payment_method_type": { "$ref": "#/components/schemas/EnumPaymentLinkAllowedPaymentMethod" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For OFPI, the value will be `open_finance`.", "items": { "type": "string", "example": "open_finance" } }, "payment_method_details": { "description": "Details about the Pix Key payment method.", "anyOf": [ { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsIndividualPixKeys" }, { "$ref": "#/components/schemas/PaymentIntentPaymentMethodDetailsBusinessPixKeys" } ] }, "payment_method_information": { "description": "Information about the Pix Key payment method.\n\nAt the time of payment intent creation, it will only include the `open_finance.pix_key_details` property, which you need to show your user to confirm that their details are correct (see the **Initial** schema).\n\nAfter they confirm their details in your application and you send through the PATCH request, this object will be populated with additional properties (see the **Confirmed** schema).\n", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodInformationPixKeysInitial" }, { "$ref": "#/components/schemas/PaymentMethodInformationPixKeysConfirmed" } ] }, "failure_code": { "type": "string", "nullable": true, "description": "Error code that explains the reason behind a payment being unsuccessful (if applicable).\n", "example": null }, "failure_message": { "type": "string", "nullable": true, "description": "Further information regarding the `failure_code`.\n", "example": null }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } }, "charges": { "type": "array", "description": "An array of charge objects related to this payment intent. If no charges are associated, we return an empty array.\n", "items": { "$ref": "#/components/schemas/ChargeBrazilPix" } }, "provider": { "$ref": "#/components/schemas/EnumPaymentLinkProvider" }, "last_error": { "deprecated": true, "description": "**Note**: This field has been deprecated and will be removed from the API in the future.\n\n*Information about the error you ran into in the previous step of the payment intent, if applicable. This error can occur when something unexpected happened during the payment intent process.*\n", "oneOf": [ { "$ref": "#/components/schemas/LastErrorPaymentError" } ] }, "next_step": { "deprecated": true, "description": "**Note**: This field has been deprecated and will be removed from the API in the future.\n\n*Object detailing the next steps you should follow for a specific `next_step` type.*\n", "oneOf": [ { "$ref": "#/components/schemas/NextStepDisplayPaymentMethodInformation" }, { "$ref": "#/components/schemas/NextStepNeedsRedirect" }, { "$ref": "#/components/schemas/NextStepDisplayConfirmationRequiredOfpi" }, { "$ref": "#/components/schemas/NextStepDisplayPaymentProcessing" }, { "$ref": "#/components/schemas/NextStepDisplayPaymentSucceeded" }, { "$ref": "#/components/schemas/NextStepDisplayPaymentFailed" } ] } } }, "IdempotencyConflictError": { "type": "object", "title": "Idempotency Conflict Error", "required": [ "code", "message", "request_id" ], "description": "The API responds with this error when it receives a request containing an idempotency key that has been previously used in another request which hasn't yet finished processing. To correctly maintain an idempotent state, the server cannot process duplicate requests simultaneously.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`idempotency_key_conflict`) that allows you to classify and handle the error programmatically.\n", "example": "idempotency_key_conflict" }, "message": { "type": "string", "description": "A short description of the error.\n\nFor `idempotency_key_conflict` errors, the description is:\n\n - `A request with this idempotency key is already being processed.`\n", "example": "A request with this idempotency key is already being processed." }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "IdempotencyMismatchError": { "type": "object", "title": "Idempotency Key Mismatch Error", "required": [ "code", "message", "request_id" ], "description": "This error occurs when a request is made with an idempotency key that was previously used with a different request payload. Each unique idempotency key must be associated with the same request body.\n", "properties": { "code": { "type": "string", "description": "A unique error code (`idempotency_payload_mismatch`) that allows you to classify and handle the error programmatically.\n", "example": "idempotency_payload_mismatch" }, "message": { "type": "string", "description": "A short description of the error.\n\nFor `idempotency_payload_mismatch` errors, the description is:\n\n - `A different request with the same idempotency key already exists.`\n", "example": "A different request with the same idempotency key already exists." }, "request_id": { "$ref": "#/components/schemas/request_id" } } }, "PatchPaymentIntentPixKeys": { "type": "object", "title": "Pix Key", "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean", "description": "Boolean that indicates whether this request confirms the payment intent. Must be set to `true` to confirm the payment intent.\n", "example": true } } }, "PatchPaymentIntentOfpi": { "type": "object", "title": "Bank Account", "required": [ "payment_method_details" ], "properties": { "payment_method_details": { "type": "object", "required": [ "open_finance" ], "description": "Object containing additional required fields for the payment intent flow.", "properties": { "open_finance": { "type": "object", "properties": { "payer_institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the payer’s institution.\n", "example": "db201c6a-e0ee-4caa-92d6-72b480d6d86f" }, "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID for the beneficiary bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" } } } } }, "confirm": { "type": "boolean", "description": "Boolean that indicates whether this request confirms the payment intent. \n", "example": true } } }, "PaymentConfigurationImmediate": { "type": "object", "title": "PIX_OF_IMMEDIATE", "description": "Configuration details for the `PIX_OF_IMMEDIATE` payment method.", "properties": { "amount": { "type": "string", "pattern": "^-?\\d{1,15}\\.\\d{2,4}$", "description": "The amount that your customer will be charged.\n", "example": "10000.05" }, "statement_description": { "type": "string", "minLength": 1, "maxLength": 140, "pattern": "[\\w\\W\\s]{1,140}", "description": "The description that will appear on your customer's bank statement.", "example": "Blue Suede Shoes - Premium" }, "authorization_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "description": "The URL where the user should be redirected to authorize the payment.", "example": "https://auth.belvo.com/authorize?token=abc123def456" } } }, "PaymentConfigurationScheduled": { "type": "object", "title": "PIX_OF_SCHEDULED", "description": "Configuration details for the `PIX_OF_SCHEDULED` payment method.", "properties": { "amount": { "type": "string", "pattern": "^-?\\d{1,15}\\.\\d{2,4}$", "description": "The amount that your customer will be charged.\n", "example": "10000.05" }, "statement_description": { "type": "string", "minLength": 1, "maxLength": 140, "pattern": "[\\w\\W\\s]{1,140}", "description": "The description that will appear on your customer's bank statement.", "example": "Blue Suede Shoes - Premium" }, "dates": { "type": "array", "description": "The date that the payment is scheduled to be made, in `YYYY-MM-DD` format.", "minItems": 1, "maxItems": 1, "items": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": [ "2025-10-30" ] }, "authorization_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "description": "The URL where the user should be redirected to authorize the payment.", "example": "https://auth.belvo.com/authorize?token=abc123def456" } } }, "PaymentAuthorization": { "type": "object", "title": "Payment Authorization", "description": "Payment Authorization details.", "required": [ "id", "created_at", "updated_at", "status", "status_reason_code", "status_reason_message", "status_updated_at", "authorized_at", "external_id", "description", "return_url", "payment_method", "payer", "beneficiary", "payment_method_configuration", "charges" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The Belvo ID for the Payment Authorization.", "example": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432" }, "created_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the Payment Authorization was created.", "example": "2025-05-20T09:55:02Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the Payment Authorization was last updated.", "example": "2025-05-20T09:55:02Z" }, "status": { "type": "string", "description": "The current status of the Payment Authorization.\n", "enum": [ "AWAITING_AUTHORIZATION", "PARTIALLY_ACCEPTED", "AUTHORIZED", "FAILED", "CONSUMED", "REVOKED" ], "example": "AWAITING_AUTHORIZATION" }, "status_reason_code": { "type": "string", "nullable": true, "description": "A code indicating the reason for the current status (when applicable). For a full list of possible codes and messages, please see our dedicated Error Codes and Messages article.", "example": null }, "status_reason_message": { "type": "string", "nullable": true, "description": "A human-readable message explaining the reason for the current status (when applicable).", "example": null }, "status_updated_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the status was last updated.", "example": "2025-05-20T09:55:02Z" }, "authorized_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The ISO-8601 timestamp of when the Payment Authorization was authorized by the user.", "example": "2025-05-20T09:55:02Z" }, "external_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "nullable": true, "description": "The merchant's internal ID for the authorization.", "example": "c169a8a9-e9f5-48db-9f4a-818caef9356b" }, "description": { "type": "string", "minLength": 1, "maxLength": 140, "pattern": "^[\\w\\W\\s]+$", "description": "An internal description used by the merchant only.", "example": "Internal description used by the merchant only" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "description": "The URL where the user will be redirected after authorization.", "example": "https://merchant.com/return" }, "payment_method": { "type": "string", "enum": [ "PIX_OF_IMMEDIATE", "PIX_OF_SCHEDULED" ], "description": "The payment method that was authorized.\n", "example": "PIX_OF_IMMEDIATE" }, "payer": { "type": "object", "description": "Details regarding the payer.", "properties": { "customer": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The Belvo ID for the customer.", "example": "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044" }, "institution": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The Belvo ID of the institution that the payer will use.", "example": "770932b4-8f1f-4b0f-8470-1c605903fdb2" }, "representative_identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^[0-9]{11,14}$", "description": "In the case that the customer is a business, the CPF of the representative authorized to make payments.\n", "example": "12345678901122" } } }, "beneficiary": { "type": "object", "description": "Details regarding the beneficiary of the payment.", "properties": { "type": { "type": "string", "enum": [ "BANK_ACCOUNT" ], "description": "The type of beneficiary account.", "example": "BANK_ACCOUNT" }, "target": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The Belvo ID of the bank account that will receive funds.", "example": "b6278377-f710-4d1a-a026-7bab757256d0" } } }, "payment_method_configuration": { "type": "object", "description": "Configuration details for the payment method.", "oneOf": [ { "$ref": "#/components/schemas/PaymentConfigurationImmediate" }, { "$ref": "#/components/schemas/PaymentConfigurationScheduled" } ] }, "charges": { "type": "array", "minItems": 0, "description": "A list of Charge IDs associated with the Payment Authorization.", "items": { "type": "string", "format": "uuid", "description": "The Belvo ID of the Charge.", "example": "7d159b21-9f25-4365-9fa2-734d20797819" } }, "metadata": { "$ref": "#/components/schemas/metadata__payments" } } }, "CustomerObject": { "type": "object", "title": "CPF or CNPJ", "description": "Details of the customer making payments to the beneficiary. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.", "required": [ "identifier", "name" ], "properties": { "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^(?:[0-9]{11}|[0-9]{14})$", "description": "The CPF or CNPJ of the customer. For CPF, must be 11 characters. For CNPJ, must be 14 characters.\n", "example": "12345678901" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\\\$%\\d' -]{0,120})$", "description": "The full name of the customer.", "example": "João da Silva" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" } } }, "CustomerId": { "type": "string", "title": "Belvo ID", "format": "uuid", "description": "The Belvo ID of previously created customer that will make the payments to the beneficiary.\n\n{% admonition type=\"warning\" name=\"Customer from Payments-BR.V2\" %}\n The provided customer ID must be one that was created using the `Payments-BR.V2` version of our API. For example, using either the Bank Account Details option when created the Payment Authorization, or the Create a Customer endpoint with the `X-Belvo-API-Resource-Version: Payments-BR.V2` header.\n If you provide an ID that is not `Payments-BR.V2` version compliant, you will receive the following error: `The customer does not exist or is invalid.`.\n{% /admonition %}\n", "example": "c169a8a9-e9f5-48db-9f4a-818caef9356b" }, "BankAccountObject": { "type": "object", "title": "Bank Account Details", "description": "Details of the bank account to be registered. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID.", "required": [ "details", "holder" ], "properties": { "holder": { "type": "object", "description": "Details of the account holder.", "required": [ "identifier", "name" ], "properties": { "identifier": { "type": "string", "minLength": 11, "maxLength": 14, "pattern": "^(?:[0-9]{11}|[0-9]{14})$", "description": "The CPF (11 digits) or CNPJ (14 digits) of the account holder.\n", "example": "12345678901122" }, "name": { "type": "string", "maxLength": 120, "pattern": "^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\\\$%\\d' -]{0,120})$", "description": "The full name or business name of the account holder.", "example": "Frangos Enlatados" } } }, "details": { "type": "object", "description": "Details of the bank account.", "required": [ "account_type", "agency", "institution", "number" ], "properties": { "account_type": { "type": "string", "enum": [ "CHECKINGS", "SAVINGS", "PAYMENTS" ], "description": "The type of bank account. Can be either:\n - `CHECKINGS` (also known as Conta Corrente in Brazil)\n - `SAVINGS` (also known as Conta Poupança in Brazil)\n - `PAYMENTS` (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)\n", "example": "CHECKINGS" }, "agency": { "type": "string", "minLength": 1, "maxLength": 4, "pattern": "^[0-9]{1,4}$", "description": "The agency (branch number) of the institution where the account was created.", "example": "0444" }, "institution": { "type": "string", "format": "uuid", "description": "The Belvo ID of the financial institution.", "example": "f512d996-583a-4a91-8b5b-eba2e103b068" }, "number": { "type": "string", "pattern": "^[0-9]{1,20}$", "minLength": 1, "maxLength": 20, "description": "The bank account number.\n\n{% admonition type=\"info\" name=\"Valid Account Number characters\" %}\n You can only send through numbers (`^[0-9]+$`) in the string. For example, `\"457220\"` is a valid bank account number, while \"`45722-0`\" is invalid as it contains a hyphen (`-`).\n{% /admonition %}\n", "example": "457220" } } }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "metadata": { "$ref": "#/components/schemas/metadata__payments" } } }, "BankAccountId": { "type": "string", "title": "Bank Account ID", "format": "uuid", "description": "The Belvo ID of the bank account you previously registered that will receive funds.\n\n{% admonition type=\"warning\" name=\"Bank Account from Payments-BR.V2\" %}\n The provided bank account ID must be one that was created using the `Payments-BR.V2` version of our API. For example, using either the Bank Account Details option when created the Payment Authorization, or the Register Bank Account endpoint with the `X-Belvo-API-Resource-Version: Payments-BR.V2` header.\n If you provide an ID that is not `Payments-BR.V2` version compliant, you will receive the following error: `The bank account does not exist or is invalid.`.\n{% /admonition %}\n", "example": "b6278377-f710-4d1a-a026-7bab757256d0" }, "CreatePaymentAuthorizationImmediate": { "type": "object", "title": "Immediate", "description": "Create an Immediate Payment Authorization.", "required": [ "payment_method", "description", "return_url", "payer", "beneficiary", "payment_method_configuration" ], "properties": { "payment_method": { "type": "string", "enum": [ "PIX_OF_IMMEDIATE" ], "description": "The payment method to authorize. For immediate one-time payments, this must be set to `PIX_OF_IMMEDIATE`.\n", "example": "PIX_OF_IMMEDIATE" }, "description": { "type": "string", "description": "An internal description for the merchant.", "minLength": 1, "maxLength": 140, "pattern": "[\\w\\W\\s]{1,140}", "example": "Blue Suede Shoes - Premium 3429123" }, "external_id": { "type": "string", "format": "uuid", "description": "(Highly Recommended) The merchant's internal ID for the authorization.", "example": "c169a8a9-e9f5-48db-9f4a-818caef9356b" }, "return_url": { "type": "string", "format": "uri", "description": "The URL that the user should be redirected to after authorizing the payment in the institution.", "example": "https://merchant.com/return" }, "payer": { "type": "object", "description": "Details regarding the payer.", "required": [ "customer" ], "properties": { "customer": { "description": "Details of the customer making payments to the beneficiary. You can either provide the customer's CPF or CNPJ, or their Belvo ID. If you provide the Belvo ID, it must be a UUID of a customer that has already been created in Belvo. If you provide the CPF or CNPJ, we will check if the customer exists in Belvo. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.\n", "oneOf": [ { "$ref": "#/components/schemas/CustomerObject" }, { "$ref": "#/components/schemas/CustomerId" } ] }, "institution": { "type": "string", "description": "The Belvo ID of the institution that they payer will use to pay for the merchant's service. To get the Belvo ID of an institution, use the [Institutions endpoint](https://developers.belvo.com/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil).", "example": "ef685cf7-d143-4671-a1e5-4d1d019a3f5c" }, "representative_identifier": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^[0-9]{14}$", "description": "In the case that the customer is a business, this is the CPF of the representative authorized to make payments for the business.\n", "example": "12345678901234" } } }, "beneficiary": { "type": "object", "description": "Details regarding the beneficiary of the payment.", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "BANK_ACCOUNT" ], "description": "The type of beneficiary account. At present, this must be set to `BANK_ACCOUNT`.", "example": "BANK_ACCOUNT" }, "target": { "oneOf": [ { "$ref": "#/components/schemas/BankAccountObject" }, { "$ref": "#/components/schemas/BankAccountId" } ], "description": "Details regarding the bank account that will receive funds. You can either provide the complete details of the bank account or the Belvo ID. If you provide the complete bank account details, we will check if the bank account exists in Belvo. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID." } } }, "payment_method_configuration": { "type": "object", "description": "Details regarding the payment.", "required": [ "amount", "statement_description" ], "properties": { "amount": { "type": "number", "format": "float", "description": "The amount that your customer will be charged.\n", "example": 10000.05 }, "statement_description": { "type": "string", "minLength": 1, "maxLength": 140, "pattern": "[\\w\\W\\s]{1,140}", "description": "The description that will appear on your customer's bank statement.", "example": "Blue Suede Shoes - Premium" } } }, "metadata": { "$ref": "#/components/schemas/metadata__payments" } } }, "CreatePaymentAuthorizationScheduled": { "type": "object", "title": "Scheduled", "description": "Create a Scheduled Payment Authorization.", "required": [ "payment_method", "description", "return_url", "payer", "beneficiary", "payment_method_configuration" ], "properties": { "payment_method": { "type": "string", "enum": [ "PIX_OF_SCHEDULED" ], "description": "The payment method to authorize. For scheduled one-time payments, this must be set to `PIX_OF_SCHEDULED`.\n", "example": "PIX_OF_SCHEDULED" }, "description": { "type": "string", "description": "An internal description for the merchant.", "minLength": 1, "maxLength": 140, "pattern": "[\\w\\W\\s]{1,140}", "example": "Layaway Shoe Payment 3429123" }, "external_id": { "type": "string", "format": "uuid", "description": "(Highly Recommended) The merchant's internal ID for the authorization.", "example": "c169a8a9-e9f5-48db-9f4a-818caef9356b" }, "return_url": { "type": "string", "format": "uri", "description": "The URL that the user should be redirected to after authorizing the payment in the institution.", "example": "https://merchant.com/return" }, "payer": { "type": "object", "description": "Details regarding the payer.", "required": [ "customer" ], "properties": { "customer": { "description": "Details of the customer making payments to the beneficiary. You can either provide the customer's CPF or CNPJ, or their Belvo ID. If you provide the Belvo ID, it must be a UUID of a customer that has already been created in Belvo. If you provide the CPF or CNPJ, we will check if the customer exists in Belvo. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.\n", "oneOf": [ { "$ref": "#/components/schemas/CustomerObject" }, { "$ref": "#/components/schemas/CustomerId" } ] }, "institution": { "type": "string", "description": "The Belvo ID of the institution that they payer will use to pay for the merchant's service. To get the Belvo ID of an institution, use the [Institutions endpoint](https://developers.belvo.com/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil).", "example": "ef685cf7-d143-4671-a1e5-4d1d019a3f5c" }, "representative_identifier": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^[0-9]{14}$", "description": "In the case that the customer is a business, this is the CPF of the representative authorized to make payments for the business.\n", "example": "12345678901234" } } }, "beneficiary": { "type": "object", "description": "Details regarding the beneficiary of the payment.", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "BANK_ACCOUNT" ], "description": "The type of beneficiary account. At present, this must be set to `BANK_ACCOUNT`.", "example": "BANK_ACCOUNT" }, "target": { "oneOf": [ { "$ref": "#/components/schemas/BankAccountObject" }, { "$ref": "#/components/schemas/BankAccountId" } ], "description": "Details regarding the bank account that will receive funds. You can either provide the complete details of the bank account or the Belvo ID. If you provide the complete bank account details, we will check if the bank account exists in Belvo. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID." } } }, "payment_method_configuration": { "type": "object", "description": "Details regarding the payment.", "required": [ "amount", "statement_description", "dates" ], "properties": { "amount": { "type": "number", "format": "float", "description": "The amount that your customer will be charged.\n", "example": 10000.05 }, "statement_description": { "type": "string", "minLength": 1, "maxLength": 140, "pattern": "[\\w\\W\\s]{1,140}", "description": "The description that will appear on your customer's bank statement.", "example": "Blue Suede Shoes - Premium" }, "dates": { "type": "array", "description": "The date that the payment is scheduled to be made, in `YYYY-MM-DD` format. Must be at least one day into the future.", "minItems": 1, "maxItems": 1, "items": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": [ "2025-10-30" ] } } }, "metadata": { "$ref": "#/components/schemas/metadata__payments" } } }, "EnrollmentBiometricPix": { "type": "object", "description": "Details regarding the device enrollment for Biometric Pix payments.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Belvo's unique identifier of the enrollment.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "created_by": { "type": "string", "format": "uuid", "description": "The Belvo ID of the merchant that created the enrollment.", "example": "dbdce1e9-d089-4b7d-804b-51dd07748202" }, "created_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the data point was created in Belvo's database.", "example": "2024-11-26T11:20:57.389056Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the enrollment was last updated.", "example": "2024-11-26T11:20:57.389058Z" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "type": { "type": "string", "enum": [ "open_finance_biometric_pix" ], "description": "The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:\n\n - `open_finance_biometric_pix`: For biometric payments using the PIX network.\n", "example": "open_finance_biometric_pix" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "CANCELED", "FAILED" ], "description": "The status of the device enrollment. Can be either:\n\n- `PENDING`: The enrollment is pending.\n- `SUCCEEDED`: The enrollment was successful.\n- `CANCELED`: The enrollment was canceled.\n- `FAILED`: The enrollment failed.\n", "example": "PENDING" }, "status_reason_code": { "type": "string", "nullable": true, "description": "A machine-readable code providing the reason for a failed enrollment. Only present when `status` is `FAILED`.\n\nPossible values:\n - `send_risk_signals_failed`: Enrollment rejected due to timeout while sending risk signals.\n - `redirection_to_institution_failed`: Enrollment rejected because the redirection to the institution was not successfully completed.\n - `biometric_registration_failed`: Enrollment rejected because the biometric registration was not completed successfully within the allowed time.\n - `too_many_device_registration_attempts`: Enrollment rejected due to too many failed device registration attempts.\n - `rejected_by_user`: Enrollment was manually cancelled by the user.\n - `device_not_supports_biometric_authentication`: Enrollment rejected because the device is not compatible with biometric authentication.\n - `institution_infra_failed`: Enrollment rejected due to infrastructure issues at the institution.\n - `blocked_by_institution_security_policy`: Enrollment rejected due to the institution security policy decisions based on risk evaluation.\n - `redirection_back_from_institution_failed`: Enrollment rejected because the redirection back from the institution was not successfully completed.\n - `biometric_validation_error`: Enrollment failed due to biometric validation or public key registration issues.\n - `rejected_other`: Enrollment rejected for an unspecified reason.\n - `canceled_due_to_expiration`: Enrollment canceled due to expiration of validity period.\n", "example": "biometric_registration_failed" }, "status_reason_message": { "type": "string", "nullable": true, "description": "A human-readable message providing more details about the reason for a failed enrollment. Only present when `status` is `FAILED`. Please see `status_reason_code` for example messages for each reason code.\n", "example": "Enrollment rejected because the biometric registration was not completed successfully within the allowed time." }, "details": { "type": "object", "description": "Details regarding the enrollment", "properties": { "status": { "type": "string", "enum": [ "AWAITING_ACCOUNT_HOLDER_VALIDATION", "AWAITING_ENROLLMENT", "AUTHORIZED", "REJECTED", "REVOKED" ], "description": "The status of the Biometric Pix enrollment. Can be either:\n\n - `AWAITING_ACCOUNT_HOLDER_VALIDATION`: The account holder needs to validate the enrollment by sending their biometric data.\n - `AWAITING_ENROLLMENT`: The enrollment information has been sent to the institution and is being evaluated.\n - `AUTHORIZED`: The enrollment has been authorized.\n - `REJECTED`: The institution has rejected the enrollment.\n - `REVOKED`: The user or the institution has revoked the enrollment.\n", "example": "AWAITING_ACCOUNT_HOLDER_VALIDATION" }, "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the customer.", "example": "c860809f-e96d-4d50-9588-f40ffab77302" }, "institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the institution the device is enrolled at.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "platform": { "type": "string", "enum": [ "ANDROID", "BROWSER", "CROSS_PLATFORM", "IOS" ], "description": "The platform of the device to be enrolled. Can be either:\n\n - `ANDROID`: For Android devices.\n - `BROWSER`: For web browsers.\n - `CROSS_PLATFORM`: For cross-platform devices.\n - `IOS`: For iOS devices.\n", "example": "ANDROID" }, "name": { "type": "string", "nullable": true, "description": "An internal name for this device enrollment.\n", "example": "600f1b4a-Mobile" }, "callback_url": { "type": "string", "format": "uri", "description": "The URL to redirect your user to after the enrollment process is completed.\n", "example": "https://example.com/enrollment-in-progress" }, "redirect_url": { "type": "string", "format": "uri", "description": "The URL to redirect the user to complete their enrollment at the institution.\n", "example": "https://www.acmecorp.com/checkout/3487321" }, "risk_signals": { "type": "string", "description": "An obfuscated string (`******`) used to indicate that risk signals have been provided.", "example": "******" }, "expires_at": { "type": "string", "format": "date-time", "description": "The ISO-8601 timestamp of when the enrollment will expire. After this time, the enrollment will no longer be valid and the `status` will transition to `CANCELED` and the `status_reason_code` will be set to `canceled_due_to_expiration`.\n", "example": "2026-12-26T11:20:57.389056Z" } } }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the enrollment.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } } } }, "CreateEnrollmentBiometricPix": { "type": "object", "description": "Request body to create a new device enrollment.", "required": [ "type", "details" ], "properties": { "type": { "type": "string", "enum": [ "open_finance_biometric_pix" ], "description": "The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:\n\n - `open_finance_biometric_pix`: For biometric payments using the PIX network.\n", "example": "open_finance_biometric_pix" }, "details": { "type": "object", "required": [ "customer", "institution", "platform", "risk_signals" ], "description": "The details of the enrollment to be created.\n", "properties": { "customer": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the customer.", "example": "c860809f-e96d-4d50-9588-f40ffab77302" }, "institution": { "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the payer's institution.", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" }, "name": { "type": "string", "maxLength": 140, "description": "A human-readable name for the device enrollment.\n", "example": "600f1b4a-Mobile" }, "callback_url": { "type": "string", "format": "uri", "description": "The URL to redirect your user to after the enrollment process is completed.\n", "example": "https://example.com/enrollment-in-progress" }, "platform": { "type": "string", "enum": [ "ANDROID", "BROWSER", "CROSS_PLATFORM", "IOS" ], "description": "The platform of the device to be enrolled. Can be either:\n\n - `ANDROID`: For Android devices.\n - `BROWSER`: For web browsers.\n - `CROSS_PLATFORM`: For cross-platform devices.\n - `IOS`: For iOS devices.\n", "example": "ANDROID" }, "risk_signals": { "type": "object", "description": "Details regarding the device to be enrolled. This is the JSON-formatted object received from the Belvo Android or iOS SDK." } } } } }, "CustomerIdPaymentWidget": { "title": "Belvo Customer ID", "type": "string", "format": "uuid", "description": "Belvo's unique ID to reference the customer.", "example": "c860809f-e96d-4d50-9588-f40ffab77302" }, "CustomerPaymentWidget": { "title": "Customer CPF", "type": "object", "required": [ "identifier" ], "properties": { "identifier": { "type": "string", "minLength": 11, "maxLength": 11, "description": "The customer's CPF number.\n", "example": "10187609363" }, "name": { "type": "string", "minLength": 5, "maxLength": 200, "description": "The full name of the customer you want to create or list enrollments for.\n", "example": "Gustavo Veloso" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" } } }, "EnrollmentBiometricPaymentWidget": { "type": "object", "description": "The `enrollment` object contains key information that is required in order to enroll the user's device with their institution or to list the enrollments associated with the user.", "required": [ "type", "details", "metadata" ], "properties": { "type": { "type": "string", "enum": [ "open_finance_biometric_pix" ], "description": "The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:\n\n - `open_finance_biometric_pix`: For biometric payments using the PIX network.\n", "example": "open_finance_biometric_pix" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "details": { "type": "object", "required": [ "customer" ], "description": "The details of the enrollment to be created.\n", "properties": { "name": { "type": "string", "maxLength": 140, "description": "A human-readable name for the device enrollment.\n", "example": "600f1b4a-Mobile" }, "customer": { "description": "The customer you want to create or list enrollments for. You can provide either the Belvo ID or the CPF for the customer.\n\n> 📘 New customers\n>\n> If you provide a CPF for a user that does not exist in Belvo, we will create a new customer with the provided CPF.\n", "oneOf": [ { "$ref": "#/components/schemas/CustomerIdPaymentWidget" }, { "$ref": "#/components/schemas/CustomerPaymentWidget" } ] }, "institution": { "type": "string", "format": "uuid", "description": "**Optional**: Belvo's unique ID to reference the payer's institution.\n\nIf you provide the institution ID, the widget will skip the institution selection step.\n", "example": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0" } } }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } } } }, "IndividualRequestBiometricPix": { "type": "object", "title": "INDIVIDUAL", "description": "Details about the Biometric Pix payment method.", "required": [ "open_finance_biometric_pix" ], "properties": { "open_finance_biometric_pix": { "type": "object", "description": "Details regarding the Biometric Pix payment method for individual customers.", "required": [ "beneficiary_bank_account" ], "properties": { "beneficiary_bank_account": { "type": "string", "format": "uuid", "description": "Belvo's unique ID used to identify the beneficiary's bank account.\n", "example": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" }, "enrollment": { "type": "string", "format": "uuid", "description": "The `enrollment.id` for the payment intent.\n\n> 📘 Note\n>\n> If you pass the `enrollment.id` in the request, the widget will skip the \"List enrollments\" screen and automatically prompt the user for their biometric scan.\n", "example": "7dc245e3-5f75-4534-bafa-431fc0893593" } } } } }, "PaymentIntentBiometricWidget": { "type": "object", "title": "Payment Intent for Biometric Pix", "description": "Create a Biometric Pix Payment for Brazil (OFPI).\n", "required": [ "amount", "description", "allowed_payment_method_types", "payment_method_details", "metadata" ], "properties": { "amount": { "type": "string", "title": "string", "pattern": "\\d+(?:\\.\\d{1,2})?", "example": "1234.12", "description": "Amount to be paid by your customer. For OFPI, you can send through numbers with up to two decimal points, separated by a `.` period. For example: `1234.12`\n" }, "external_id": { "$ref": "#/components/schemas/external_id__payments" }, "description": { "type": "string", "description": "A human-readable description of the payment.\n", "example": "Shoe payment" }, "statement_description": { "type": "string", "maxLength": 50, "description": "A description that will appear on the customer's bank statement (recommended).\n\n\n> **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description.\n", "example": "Super Shoe Store - Brown Sneakers" }, "allowed_payment_method_types": { "type": "array", "description": "A list of payment method types allowed in this payment intent. For 🇧🇷 Brazil's OFPI, can be either:\n\n - `open_finance`: For regular payments.\n - `open_finance_biometric_pix`: For biometric payments using the PIX network.\n", "minItems": 1, "maxItems": 1, "items": { "type": "string", "enum": [ "open_finance_biometric_pix" ], "description": "Selected payment method type. For Biometric Pix payments in Brazil, this must be set to `open_finance_biometric_pix`.\n", "example": "open_finance_biometric_pix" } }, "payment_method_details": { "$ref": "#/components/schemas/IndividualRequestBiometricPix" }, "metadata": { "type": "object", "description": "Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number.\n\n\n⚠️ **Note**: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.\n", "example": { "internal_reference_id": "GGq73487w2" } } } }, "CallbackUrlsBiometricPaymentWidget": { "type": "object", "description": "In the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases:\n\n- success (your user successfully completed the enrollment or payment process)\n- exit (your user exited the widget before they completed the enrollment or payment process)\n", "required": [ "success", "exit" ], "properties": { "success": { "type": "string", "description": "The URL your user is redirected to when they successfully complete the enrollment or payment.", "example": "your_deeplink_here://success" }, "exit": { "type": "string", "description": "The URL your user is redirected to when they exit the process before completing the enrollment or payment.", "example": "your_deeplink_here://exit" } } }, "BrandingBiometricWidget": { "type": "object", "description": "Add customized branding elements to the Biometric Pix widget.", "required": [ "company_name" ], "properties": { "color_scheme": { "type": "string", "enum": [ "LIGHT", "DARK" ], "description": "The color scheme of the widget. You can choose between `LIGHT` and `DARK`. By default, the widget uses the `LIGHT` color scheme.\n\n> 📘 Customizing the color scheme\n>\n> If you want to further customize the colors for these modes, please see the `theme` parameter.\n", "default": "LIGHT", "example": "LIGHT" }, "company_name": { "type": "string", "description": "The name of the company that will be displayed in the widget.\n", "example": "Acme Inc." } } }, "ThemeBiometricWidget": { "type": "object", "description": "Use the `theme` array to add further customization to your chosen color scheme. For details regarding all the possible customizations, please see our dedicated Branding and Customization (Biometric Pix Widget) guide.\n", "required": [ "css_key", "value" ], "properties": { "css_key": { "type": "string", "description": "Widget CSS variable name.\n", "example": "--color-primary-base" }, "value": { "type": "string", "description": "The HEX code for the `css_key`.", "example": "#907AD6" } } }, "BiometricPaymentWidgetRequest": { "type": "object", "title": "Payment Widget (Biometric Pix) Access Token", "required": [ "use_cases", "widget" ], "properties": { "use_cases": { "type": "array", "minItems": 1, "maxItems": 2, "description": "The use case of the Biometric Pix widget. You can choose:\n\n - `ENROLLMENT`: Use this option if you want to enroll you user's device in the Biometric Pix service.\n - `PAYMENT_INTENT`: Use this option if you want to create a payment for a Biometric Pix transaction.\n\n> 📘 Using the widget for both enrollment and payments.\n>\n> If you pass both the `ENROLLMENT` and `PAYMENT_INTENT` use cases, the widget will first enroll the user and then create a payment intent.\n", "items": { "type": "string", "enum": [ "ENROLLMENT", "PAYMENT_INTENT" ] }, "example": [ "ENROLLMENT", "PAYMENT_INTENT" ] }, "widget": { "type": "object", "required": [ "callback_urls", "branding" ], "description": "The `widget` object contains additional information about how to set up the widget, including enrollment details\\*, payment information\\*, and callback URLs.\n\n> 📘 Conditionally requireed objects\n>\n> The `enrollment` and `payment_intent` objects are conditionally required, based on the `use_cases` you provide. To simplify your integration, we recommend you always pass both use cases (`ENROLLMENT` as well as `PAYMENT_INTENT`), and then pass both the `enrollment` and `payment_intent` objects.\n", "properties": { "enrollment": { "$ref": "#/components/schemas/EnrollmentBiometricPaymentWidget" }, "payment_intent": { "$ref": "#/components/schemas/PaymentIntentBiometricWidget" }, "callback_urls": { "$ref": "#/components/schemas/CallbackUrlsBiometricPaymentWidget" }, "branding": { "$ref": "#/components/schemas/BrandingBiometricWidget" }, "top_tier_institutions": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "description": "(Optional) An array of institutions to initially display in the widget (users will still be able to search for other institutions). You can select between 1 to 5 institutions from the available list. The institutions will display in the order you provide them in the array. If you do not pass this parameter, the widget will display all available institutions. \n", "items": { "type": "string", "enum": [ "nubank_retail", "inter_retail", "picpay_retail", "mercadopago_retail", "itau_retail", "santander_retail", "c6_retail", "bradesco_retail", "banco_do_brasil_retail", "sicredi_retail", "btg_retail", "caixa_retail", "pan_retail", "pagseguro_retail" ] }, "example": [ "nubank_retail", "picpay_retail", "mercadopago_retail", "itau_retail" ] }, "theme": { "type": "array", "description": "Use the `theme` array to add further customization to your chosen color scheme. For details regarding all the possible customizations, please see our dedicated Branding and Customization (Biometric Pix Widget) guide.\n", "items": { "$ref": "#/components/schemas/ThemeBiometricWidget" } } } } } } }, "responses": { "401_unauthorized_error": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/UnauthorizedError" }, { "$ref": "#/components/schemas/ConsentWithoutAccountsError" } ] } } } } }, "403_access_denied_error": { "description": "Access to Belvo API denied", "content": { "application/json": { "schema": { "type": "array", "description": "This error occurs when you try to access Belvo's resource without the correct permissions.\n", "items": { "$ref": "#/components/schemas/AccessToResourceDenied" } } } } }, "404_not_found_error": { "description": "Not Found Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotFoundError" } } } } }, "408_request_timeout_error": { "description": "Request Timeout", "content": { "application/json": { "schema": { "type": "array", "title": "Request Timeout", "description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n", "items": { "$ref": "#/components/schemas/RequestTimeoutError" } } } } }, "500_unexpected_error": { "description": "Unexpected Error", "content": { "application/json": { "schema": { "type": "array", "title": "Unexpected Error", "description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n", "items": { "$ref": "#/components/schemas/UnexpectedError" } } } } }, "400_bad_request_error": { "description": "Bad request error", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TooManySessionsError" }, { "$ref": "#/components/schemas/LoginError" }, { "$ref": "#/components/schemas/SessionExpiredError" }, { "$ref": "#/components/schemas/ValidationError" }, { "$ref": "#/components/schemas/InstitutionDownError" }, { "$ref": "#/components/schemas/InstitutionUnavailableError" }, { "$ref": "#/components/schemas/InstitutionInactiveError" }, { "$ref": "#/components/schemas/InvalidLinkError" }, { "$ref": "#/components/schemas/InvalidCredentialsStorageError" }, { "$ref": "#/components/schemas/InvalidFetchHistorical" }, { "$ref": "#/components/schemas/InvalidResourcesError" }, { "$ref": "#/components/schemas/UnconfirmedLinkError" }, { "$ref": "#/components/schemas/UnsupportedOperationError" }, { "$ref": "#/components/schemas/InvalidPeriodError" } ] } } } } }, "428_token_required_error": { "description": "MFA Token Required", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TokenRequiredResponse" } } } } }, "409_link_already_refreshed": { "description": "Conflict - Link Already Refreshed", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkAlreadyRefreshedError" } } } } }, "202_accepted_response": { "description": "Request Accepted (when `X-Belvo-Request-Mode` is `async`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique ID for this request. We recommend you store this value to later identify which webhook event relates to an asynchronous request.", "example": "b5d0106ac9cc43d5b36199fe831f6bbe" } } } } } }, "409_idempotency_conflict_error": { "description": "Idempotency Conflict", "headers": { "Belvo-Idempotency-Key": { "$ref": "#/components/headers/header_idempotency_key_response" }, "Belvo-Idempotency-Status": { "$ref": "#/components/headers/header_idempotency_key_status_response" } }, "content": { "application/json": { "schema": { "type": "array", "description": "This error occurs when a request with the same idempotency key is already being processed. Check the `Belvo-Idempotency-Status` response header to determine the use status of the idempotency key.\n", "items": { "$ref": "#/components/schemas/IdempotencyConflictError" } } } } }, "422_idempotency_mismatch_error": { "description": "Unprocessable Entity - Idempotency Key Mismatch", "headers": { "Belvo-Idempotency-Key": { "$ref": "#/components/headers/header_idempotency_key_response" }, "Belvo-Idempotency-Status": { "$ref": "#/components/headers/header_idempotency_key_status_response" } }, "content": { "application/json": { "schema": { "type": "array", "description": "This error occurs when the same idempotency key is reused with a different request payload. To retry this request, generate a new unique idempotency key.\n", "items": { "$ref": "#/components/schemas/IdempotencyMismatchError" } } } } } }, "examples": { "AccountsOfdaChecking": { "summary": "Checking OFDA Brazil", "description": "Example of an checking account (OFDA Brazil).", "value": [ { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "CHECKING_ACCOUNT", "balance_type": "ASSET", "overdraft": { "used": 10000.99, "arranged": 99.99, "unarranged": 99.99 }, "type": "CONTA_DEPOSITO_A_VISTA", "subtype": "INDIVIDUAL", "name": null, "number": "11188222", "agency": "6272", "check_digit": "4", "balance": { "current": 999.99, "available": 15000, "blocked": 41233.07, "automatically_invested": 15000 }, "currency": "BRL", "public_identification_name": "AGENCY/NUMBER", "public_identification_value": "6272/11188222", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": null, "loan_data": null, "funds_data": null } ] }, "AccountsOfdaCreditCard": { "summary": "Credit Card OFDA Brazil", "description": "Example of an credit card account (OFDA Brazil).", "value": [ { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "CREDIT_CARD", "balance_type": "LIABILITY", "overdraft": null, "type": "GRAFITE", "subtype": "Dinners Elo Grafite", "name": "Dinners Grafite", "number": "4057068115181", "agency": "6272", "check_digit": "7", "balance": { "current": 5874.13, "available": 5621.12, "blocked": 60.32, "automatically_invested": 131.5 }, "currency": "BRL", "public_identification_name": "CREDIT_CARD_NUMBER", "public_identification_value": "8921", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": { "cards": [ { "is_multiple": false, "identification_number": "8921" } ], "limits": [ { "type": "LIMITE_CREDITO_TOTAL", "line_name": "CREDITO_A_VISTA", "card_number": "8921", "used_amount": 7500.05, "credit_limit": 23000.98, "available_amount": 15500.93, "is_limit_flexible": true, "consolidation_type": "CONSOLIDADO", "line_name_additional_info": "NA" } ], "network": "DINERS_CLUB", "collected_at": "2023-07-24T00:46:24.431038Z", "credit_limit": 23000.98, "cutting_date": null, "interest_rate": null, "minimum_payment": 0, "monthly_payment": null, "last_payment_date": null, "next_payment_date": null, "last_period_balance": null, "no_interest_payment": null, "network_additional_info": null }, "loan_data": null, "funds_data": null } ] }, "AccountsOfdaLoanData": { "summary": "Loan OFDA Brazil", "description": "Example of an loan account (OFDA Brazil).", "value": [ { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "LOAN_ACCOUNT", "balance_type": "LIABILITY", "overdraft": null, "type": "EMPRESTIMOS", "subtype": "CREDITO_PESSOAL_SEM_CONSIGNACAO", "name": "Aquisição de equipamentos", "number": "4057068115181", "agency": "6272", "check_digit": "7", "balance": { "current": 5874.13, "available": 5621.12, "blocked": 0, "automatically_invested": 0 }, "currency": "BRL", "public_identification_name": "NUMBER", "public_identification_value": "90847453264", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": null, "loan_data": { "fees": [ { "code": "ADMNISTRACAO", "name": "Taxa de administracao", "rate": 0, "type": null, "value": 200.5, "fee_charge": "FIXED", "fee_charge_type": "SINGLE" } ], "loan_code": "01181521040211011740907325668478542336597", "loan_type": "CREDITO_PESSOAL_SEM_CONSIGNACAO", "principal": null, "limit_date": null, "collaterals": [ { "type": "CESSAO_DIREITOS_CREDITORIOS", "amount": 15000.31, "subtype": "ACOES_DEBENTURES", "currency": "BRL" } ], "cutting_day": null, "payment_day": null, "collected_at": "2023-07-24T00:46:44.756806Z", "consignee_id": "13832718000196", "credit_limit": null, "cutting_date": null, "interest_rate": null, "interest_rates": [ { "name": "NOMINAL", "type": "YEARLY", "value": 0.015, "interest_rate_data": { "type": "AA", "tax_type": "NOMINAL_TAX", "rate_type": "SIMPLE_RATE", "pre_fixed_rate": 0.015, "additional_info": "NA", "post_fixed_rate": 0, "calculation_base": "21/252", "reference_index_info": null, "reference_index_type": "PRE_FIXED", "reference_index_subtype": "PRE_FIXADO" } } ], "contract_amount": 12070.6, "contract_number": "90847453264", "monthly_payment": null, "payment_due_day": null, "settlement_date": "2021-06-21", "balloon_payments": [ { "amount": 0, "currency": "BRL", "due_date": "2020-01-10" } ], "contract_end_date": "2023-01-08", "last_payment_date": null, "next_payment_date": null, "contracted_charges": [ { "info": "NA", "rate": 0.06, "type": "LATE_PAYMENT_PENALTY_FEE" } ], "disbursement_dates": [ "2022-01-08" ], "contract_start_date": "2022-01-08", "last_period_balance": null, "no_interest_payment": null, "outstanding_balance": 14402.379, "total_effective_cost": 0.015, "amortization_schedule": "PRICE", "installment_frequency": "OTHER", "outstanding_principal": null, "contract_remaining_total": 727, "amortization_schedule_info": "NA", "first_installment_due_date": "2022-01-08", "installment_frequency_info": "DIA", "number_of_installments_paid": 3, "contract_remaining_frequency": "DAY", "number_of_installments_total": 730, "number_of_installments_past_due": 1, "number_of_installments_outstanding": 727, "installments_contract_term_frequency": "DAY" }, "funds_data": null } ] }, "AccountsOfdaCheckingDetail": { "summary": "Checking OFDA Brazil", "description": "Example of an checking account (OFDA Brazil).", "value": { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "CHECKING_ACCOUNT", "balance_type": "ASSET", "overdraft": { "used": 10000.99, "arranged": 99.99, "unarranged": 99.99 }, "type": "CONTA_DEPOSITO_A_VISTA", "subtype": "INDIVIDUAL", "name": null, "number": "11188222", "agency": "6272", "check_digit": "4", "balance": { "current": 999.99, "available": 15000, "blocked": 41233.07, "automatically_invested": 15000 }, "currency": "BRL", "public_identification_name": "AGENCY/NUMBER", "public_identification_value": "6272/11188222", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": null, "loan_data": null, "funds_data": null } }, "AccountsOfdaCreditCardDetail": { "summary": "Credit Card OFDA Brazil", "description": "Example of an credit card account (OFDA Brazil).", "value": { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "CREDIT_CARD", "balance_type": "LIABILITY", "overdraft": null, "type": "GRAFITE", "subtype": "Dinners Elo Grafite", "name": "Dinners Grafite", "number": "4057068115181", "agency": "6272", "check_digit": "7", "balance": { "current": 5874.13, "available": 5621.12, "blocked": 60.32, "automatically_invested": 131.5 }, "currency": "BRL", "public_identification_name": "CREDIT_CARD_NUMBER", "public_identification_value": "8921", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": { "cards": [ { "is_multiple": false, "identification_number": "8921" } ], "limits": [ { "type": "LIMITE_CREDITO_TOTAL", "line_name": "CREDITO_A_VISTA", "card_number": "8921", "used_amount": 7500.05, "credit_limit": 23000.98, "available_amount": 15500.93, "is_limit_flexible": true, "consolidation_type": "CONSOLIDADO", "line_name_additional_info": "NA" } ], "network": "DINERS_CLUB", "collected_at": "2023-07-24T00:46:24.431038Z", "credit_limit": 23000.98, "cutting_date": null, "interest_rate": null, "minimum_payment": 0, "monthly_payment": null, "last_payment_date": null, "next_payment_date": null, "last_period_balance": null, "no_interest_payment": null, "network_additional_info": null }, "loan_data": null, "funds_data": null } }, "AccountsOfdaLoanDataDetail": { "summary": "Loan OFDA Brazil", "description": "Example of an loan account (OFDA Brazil).", "value": { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "LOAN_ACCOUNT", "balance_type": "LIABILITY", "overdraft": null, "type": "EMPRESTIMOS", "subtype": "CREDITO_PESSOAL_SEM_CONSIGNACAO", "name": "Aquisição de equipamentos", "number": "4057068115181", "agency": "6272", "check_digit": "7", "balance": { "current": 5874.13, "available": 5621.12, "blocked": 0, "automatically_invested": 0 }, "currency": "BRL", "public_identification_name": "NUMBER", "public_identification_value": "90847453264", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": null, "loan_data": { "fees": [ { "code": "ADMNISTRACAO", "name": "Taxa de administracao", "rate": 0, "type": null, "value": 200.5, "fee_charge": "FIXED", "fee_charge_type": "SINGLE" } ], "loan_code": "01181521040211011740907325668478542336597", "loan_type": "CREDITO_PESSOAL_SEM_CONSIGNACAO", "principal": null, "limit_date": null, "collaterals": [ { "type": "CESSAO_DIREITOS_CREDITORIOS", "amount": 15000.31, "subtype": "ACOES_DEBENTURES", "currency": "BRL" } ], "cutting_day": null, "payment_day": null, "collected_at": "2023-07-24T00:46:44.756806Z", "consignee_id": "13832718000196", "credit_limit": null, "cutting_date": null, "interest_rate": null, "interest_rates": [ { "name": "NOMINAL", "type": "YEARLY", "value": 0.015, "interest_rate_data": { "type": "AA", "tax_type": "NOMINAL_TAX", "rate_type": "SIMPLE_RATE", "pre_fixed_rate": 0.015, "additional_info": "NA", "post_fixed_rate": 0, "calculation_base": "21/252", "reference_index_info": null, "reference_index_type": "PRE_FIXED", "reference_index_subtype": "PRE_FIXADO" } } ], "contract_amount": 12070.6, "contract_number": "90847453264", "monthly_payment": null, "payment_due_day": null, "settlement_date": "2021-06-21", "balloon_payments": [ { "amount": 0, "currency": "BRL", "due_date": "2020-01-10" } ], "contract_end_date": "2023-01-08", "last_payment_date": null, "next_payment_date": null, "contracted_charges": [ { "info": "NA", "rate": 0.06, "type": "LATE_PAYMENT_PENALTY_FEE" } ], "disbursement_dates": [ "2022-01-08" ], "contract_start_date": "2022-01-08", "last_period_balance": null, "no_interest_payment": null, "outstanding_balance": 14402.379, "total_effective_cost": 0.015, "amortization_schedule": "PRICE", "installment_frequency": "OTHER", "outstanding_principal": null, "contract_remaining_total": 727, "amortization_schedule_info": "NA", "first_installment_due_date": "2022-01-08", "installment_frequency_info": "DIA", "number_of_installments_paid": 3, "contract_remaining_frequency": "DAY", "number_of_installments_total": 730, "number_of_installments_past_due": 1, "number_of_installments_outstanding": 727, "installments_contract_term_frequency": "DAY" }, "funds_data": null } }, "OwnerOfdaIndividualPaginated": { "summary": "Individual OFDA Brazil", "description": "Example of an individual (OFDA Brazil).", "value": { "count": 108, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "c749315b-eec2-435d-a458-06912878564f", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "internal_identification": "7e5838e4", "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "display_name": "Jack Oswald White", "social_name": "O Piadista", "birth_date": "1988-07-15", "marital_status": "SINGLE", "marital_status_additional_info": "It's complicated", "gender": "MALE", "companies_id": [ "01773247000103" ], "is_local_resident": true, "document_id": { "document_type": "CPF", "document_number": "235578435-S" }, "additional_documents": [ { "type": "DRIVERS_LICENSE", "type_additional_info": "Learner's licence", "number": "DL-7896829-7", "check_digit": "7", "issue_date": "2019-01-01", "expiration_date": "2019-01-01", "country_of_issuance": "CAN", "additional_info": "The document has water damage" } ], "nationalities": [ { "info": "CAN", "documents": [ { "type": "DRIVERS_LICENSE", "number": "DL-7896829-7", "issue_date": "2019-01-01", "expiration_date": "2019-01-01", "country_of_issuance": "CAN", "additional_info": "The document has water damage" } ] } ], "email": "johndoe@belvo.com", "emails": [ { "is_main": true, "email": "homen_morcego@gmail.com" } ], "address": "Carrer de la Llacuna, 162, 08018 Barcelona", "addresses": [ { "is_main": true, "address": "Av Naburo Ykesaki, 1270", "additional_info": "In between two palm trees", "district_name": "CENTRO", "town": "Brasilia", "town_code": "3550308", "state": "SP", "postcode": "17500001", "country_name": "Brasil", "country_code": "BRA", "latitude": "-23.5475000", "longitude": "-46.6361100" } ], "phone_number": "+52-XXX-XXX-XXXX", "phone_numbers": [ { "is_main": true, "type": "MOBILE", "additional_info": "This is their work mobile number.", "number": "29875132", "country_code": "351", "area_code": "21", "extension": "932" } ], "filiations": [ { "type": "MOTHER", "civil_name": "Bruce Wayne", "social_name": "The Dark Knight" } ], "financial_profile": { "company_id": "50685362000135", "occupation_code": "BRAZIL_OCCUPATION_CODE", "occupation_description": "01", "informed_income": { "frequency": "MONTHLY", "amount": 45391.89, "currency": "BRL", "date": "2020-03-19" }, "patrimony": { "amount": 45391.89, "currency": "BRL", "year": 2020 } }, "financial_relation": { "start_date": "2021-05-21T08:30:00Z", "product_services": [ "CONTA_DEPOSITO_A_VISTA" ], "product_services_additional_info": "Joint account with Robin", "procurators": [ { "type": "LEGAL_REPRESENTATIVE", "civil_name": "Alfred Thaddeus Pennyworth", "social_name": "Alfred Pennyworth", "document_number": "73677831148" } ], "products": [ { "type": "SAVINGS_ACCOUNT", "subtype": "CONJUNTA_SIMPLES", "agency": "6272", "clearing_code": "001", "number": "24550245", "check_digit": "7" } ] } } ] } }, "OwnerOfdaBusinessPaginated": { "summary": "Business OFDA Brazil", "description": "Example of a business (OFDA Brazil).", "value": { "count": 108, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "c749315b-eec2-435d-a458-06912878564f", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "internal_identification": "7e5838e4", "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "company_name": "Wayne Enterprises", "trade_name": "WayneCorp", "incorporation_date": "1988-07-15", "companies_id": [ "01773247000103" ], "document_id": { "document_type": "CPF", "document_number": "235578435-S" }, "additional_documents": [ { "type": "EIN", "number": "DL-7896829-7", "expiration_date": "2019-01-01", "country_of_issuance": "CAN" } ], "email": "johndoe@belvo.com", "emails": [ { "is_main": true, "email": "homen_morcego@gmail.com" } ], "address": "Carrer de la Llacuna, 162, 08018 Barcelona", "addresses": [ { "is_main": true, "address": "Av Naburo Ykesaki, 1270", "additional_info": "In between two palm trees", "district_name": "CENTRO", "town": "Brasilia", "town_code": "3550308", "state": "SP", "postcode": "17500001", "country_name": "Brasil", "country_code": "BRA", "latitude": "-23.5475000", "longitude": "-46.6361100" } ], "phone_number": "+52-XXX-XXX-XXXX", "phone_numbers": [ { "is_main": true, "type": "MOBILE", "additional_info": "This is their work mobile number.", "number": "29875132", "country_code": "351", "area_code": "21", "extension": "932" } ], "parties": [ { "person_type": "INDIVIDUAL", "type": "MEMBER", "display_name": "Jack Oswald White", "social_name": "O Piadista", "company_name": "Wayne Enterprises", "trade_name": "WayneCorp", "start_date": "2021-07-15", "percentage_type": 0.51, "document_type": "CPF", "document_number": "DL-7896829-7", "document_issue_date": "2019-01-01", "document_expiration_date": "2019-01-01", "document_country": "CAN", "document_additional_info": "Confirmed CPF with their driver's licence." } ], "financial_profile": { "economic_activities": [ { "is_main": true, "code": "8599604" } ], "informed_revenue": { "frequency": "MONTHLY", "frequency_additional_info": "Recently switched from weekly to monthly.", "amount": 45391.89, "currency": "BRL", "year": 2022 }, "patrimony": { "amount": 45391.89, "currency": "BRL", "date": "2022-12-12" } }, "financial_relation": { "start_date": "2021-05-21T08:30:00Z", "product_services": [ "CONTA_DEPOSITO_A_VISTA" ], "procurators": [ { "type": "LEGAL_REPRESENTATIVE", "civil_name": "Alfred Thaddeus Pennyworth", "social_name": "Alfred Pennyworth", "document_number": "73677831148" } ], "products": [ { "type": "SAVINGS_ACCOUNT", "subtype": "CONJUNTA_SIMPLES", "agency": "6272", "clearing_code": "001", "number": "24550245", "check_digit": "7" } ] } } ] } }, "OwnerOfdaIndividual": { "summary": "Individual OFDA Brazil", "description": "Example of an individual (OFDA Brazil).", "value": [ { "id": "c749315b-eec2-435d-a458-06912878564f", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "internal_identification": "7e5838e4", "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "display_name": "Jack Oswald White", "social_name": "O Piadista", "birth_date": "1988-07-15", "marital_status": "SINGLE", "marital_status_additional_info": "It's complicated", "gender": "MALE", "companies_id": [ "01773247000103" ], "is_local_resident": true, "document_id": { "document_type": "CPF", "document_number": "235578435-S" }, "additional_documents": [ { "type": "DRIVERS_LICENSE", "type_additional_info": "Learner's licence", "number": "DL-7896829-7", "check_digit": "7", "issue_date": "2019-01-01", "expiration_date": "2019-01-01", "country_of_issuance": "CAN", "additional_info": "The document has water damage" } ], "nationalities": [ { "info": "CAN", "documents": [ { "type": "DRIVERS_LICENSE", "number": "DL-7896829-7", "issue_date": "2019-01-01", "expiration_date": "2019-01-01", "country_of_issuance": "CAN", "additional_info": "The document has water damage" } ] } ], "email": "johndoe@belvo.com", "emails": [ { "is_main": true, "email": "homen_morcego@gmail.com" } ], "address": "Carrer de la Llacuna, 162, 08018 Barcelona", "addresses": [ { "is_main": true, "address": "Av Naburo Ykesaki, 1270", "additional_info": "In between two palm trees", "district_name": "CENTRO", "town": "Brasilia", "town_code": "3550308", "state": "SP", "postcode": "17500001", "country_name": "Brasil", "country_code": "BRA", "latitude": "-23.5475000", "longitude": "-46.6361100" } ], "phone_number": "+52-XXX-XXX-XXXX", "phone_numbers": [ { "is_main": true, "type": "MOBILE", "additional_info": "This is their work mobile number.", "number": "29875132", "country_code": "351", "area_code": "21", "extension": "932" } ], "filiations": [ { "type": "MOTHER", "civil_name": "Bruce Wayne", "social_name": "The Dark Knight" } ], "financial_profile": { "company_id": "50685362000135", "occupation_code": "BRAZIL_OCCUPATION_CODE", "occupation_description": "01", "informed_income": { "frequency": "MONTHLY", "amount": 45391.89, "currency": "BRL", "date": "2020-03-19" }, "patrimony": { "amount": 45391.89, "currency": "BRL", "year": 2020 } }, "financial_relation": { "start_date": "2021-05-21T08:30:00Z", "product_services": [ "CONTA_DEPOSITO_A_VISTA" ], "product_services_additional_info": "Joint account with Robin", "procurators": [ { "type": "LEGAL_REPRESENTATIVE", "civil_name": "Alfred Thaddeus Pennyworth", "social_name": "Alfred Pennyworth", "document_number": "73677831148" } ], "products": [ { "type": "SAVINGS_ACCOUNT", "subtype": "CONJUNTA_SIMPLES", "agency": "6272", "clearing_code": "001", "number": "24550245", "check_digit": "7" } ] } } ] }, "OwnerOfdaBusiness": { "summary": "Business OFDA Brazil", "description": "Example of a business (OFDA Brazil).", "value": [ { "id": "c749315b-eec2-435d-a458-06912878564f", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "internal_identification": "7e5838e4", "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "company_name": "Wayne Enterprises", "trade_name": "WayneCorp", "incorporation_date": "1988-07-15", "companies_id": [ "01773247000103" ], "document_id": { "document_type": "CPF", "document_number": "235578435-S" }, "additional_documents": [ { "type": "EIN", "number": "DL-7896829-7", "expiration_date": "2019-01-01", "country_of_issuance": "CAN" } ], "email": "johndoe@belvo.com", "emails": [ { "is_main": true, "email": "homen_morcego@gmail.com" } ], "address": "Carrer de la Llacuna, 162, 08018 Barcelona", "addresses": [ { "is_main": true, "address": "Av Naburo Ykesaki, 1270", "additional_info": "In between two palm trees", "district_name": "CENTRO", "town": "Brasilia", "town_code": "3550308", "state": "SP", "postcode": "17500001", "country_name": "Brasil", "country_code": "BRA", "latitude": "-23.5475000", "longitude": "-46.6361100" } ], "phone_number": "+52-XXX-XXX-XXXX", "phone_numbers": [ { "is_main": true, "type": "MOBILE", "additional_info": "This is their work mobile number.", "number": "29875132", "country_code": "351", "area_code": "21", "extension": "932" } ], "parties": [ { "person_type": "INDIVIDUAL", "type": "MEMBER", "display_name": "Jack Oswald White", "social_name": "O Piadista", "company_name": "Wayne Enterprises", "trade_name": "WayneCorp", "start_date": "2021-07-15", "percentage_type": 0.51, "document_type": "CPF", "document_number": "DL-7896829-7", "document_issue_date": "2019-01-01", "document_expiration_date": "2019-01-01", "document_country": "CAN", "document_additional_info": "Confirmed CPF with their driver's licence." } ], "financial_profile": { "economic_activities": [ { "is_main": true, "code": "8599604" } ], "informed_revenue": { "frequency": "MONTHLY", "frequency_additional_info": "Recently switched from weekly to monthly.", "amount": 45391.89, "currency": "BRL", "year": 2022 }, "patrimony": { "amount": 45391.89, "currency": "BRL", "date": "2022-12-12" } }, "financial_relation": { "start_date": "2021-05-21T08:30:00Z", "product_services": [ "CONTA_DEPOSITO_A_VISTA" ], "procurators": [ { "type": "LEGAL_REPRESENTATIVE", "civil_name": "Alfred Thaddeus Pennyworth", "social_name": "Alfred Pennyworth", "document_number": "73677831148" } ], "products": [ { "type": "SAVINGS_ACCOUNT", "subtype": "CONJUNTA_SIMPLES", "agency": "6272", "clearing_code": "001", "number": "24550245", "check_digit": "7" } ] } } ] }, "OwnerOfdaIndividuaDetail": { "summary": "Individual OFDA Brazil", "description": "Example of an individual (OFDA Brazil).", "value": { "id": "c749315b-eec2-435d-a458-06912878564f", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "internal_identification": "7e5838e4", "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "display_name": "Jack Oswald White", "social_name": "O Piadista", "birth_date": "1988-07-15", "marital_status": "SINGLE", "marital_status_additional_info": "It's complicated", "gender": "MALE", "companies_id": [ "01773247000103" ], "is_local_resident": true, "document_id": { "document_type": "CPF", "document_number": "235578435-S" }, "additional_documents": [ { "type": "DRIVERS_LICENSE", "type_additional_info": "Learner's licence", "number": "DL-7896829-7", "check_digit": "7", "issue_date": "2019-01-01", "expiration_date": "2019-01-01", "country_of_issuance": "CAN", "additional_info": "The document has water damage" } ], "nationalities": [ { "info": "CAN", "documents": [ { "type": "DRIVERS_LICENSE", "number": "DL-7896829-7", "issue_date": "2019-01-01", "expiration_date": "2019-01-01", "country_of_issuance": "CAN", "additional_info": "The document has water damage" } ] } ], "email": "johndoe@belvo.com", "emails": [ { "is_main": true, "email": "homen_morcego@gmail.com" } ], "address": "Carrer de la Llacuna, 162, 08018 Barcelona", "addresses": [ { "is_main": true, "address": "Av Naburo Ykesaki, 1270", "additional_info": "In between two palm trees", "district_name": "CENTRO", "town": "Brasilia", "town_code": "3550308", "state": "SP", "postcode": "17500001", "country_name": "Brasil", "country_code": "BRA", "latitude": "-23.5475000", "longitude": "-46.6361100" } ], "phone_number": "+52-XXX-XXX-XXXX", "phone_numbers": [ { "is_main": true, "type": "MOBILE", "additional_info": "This is their work mobile number.", "number": "29875132", "country_code": "351", "area_code": "21", "extension": "932" } ], "filiations": [ { "type": "MOTHER", "civil_name": "Bruce Wayne", "social_name": "The Dark Knight" } ], "financial_profile": { "company_id": "50685362000135", "occupation_code": "BRAZIL_OCCUPATION_CODE", "occupation_description": "01", "informed_income": { "frequency": "MONTHLY", "amount": 45391.89, "currency": "BRL", "date": "2020-03-19" }, "patrimony": { "amount": 45391.89, "currency": "BRL", "year": 2020 } }, "financial_relation": { "start_date": "2021-05-21T08:30:00Z", "product_services": [ "CONTA_DEPOSITO_A_VISTA" ], "product_services_additional_info": "Joint account with Robin", "procurators": [ { "type": "LEGAL_REPRESENTATIVE", "civil_name": "Alfred Thaddeus Pennyworth", "social_name": "Alfred Pennyworth", "document_number": "73677831148" } ], "products": [ { "type": "SAVINGS_ACCOUNT", "subtype": "CONJUNTA_SIMPLES", "agency": "6272", "clearing_code": "001", "number": "24550245", "check_digit": "7" } ] } } }, "OwnerOfdaBusinessDetail": { "summary": "Business OFDA Brazil", "description": "Example of a business (OFDA Brazil).", "value": { "id": "c749315b-eec2-435d-a458-06912878564f", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "internal_identification": "7e5838e4", "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "company_name": "Wayne Enterprises", "trade_name": "WayneCorp", "incorporation_date": "1988-07-15", "companies_id": [ "01773247000103" ], "document_id": { "document_type": "CPF", "document_number": "235578435-S" }, "additional_documents": [ { "type": "EIN", "number": "DL-7896829-7", "expiration_date": "2019-01-01", "country_of_issuance": "CAN" } ], "email": "johndoe@belvo.com", "emails": [ { "is_main": true, "email": "homen_morcego@gmail.com" } ], "address": "Carrer de la Llacuna, 162, 08018 Barcelona", "addresses": [ { "is_main": true, "address": "Av Naburo Ykesaki, 1270", "additional_info": "In between two palm trees", "district_name": "CENTRO", "town": "Brasilia", "town_code": "3550308", "state": "SP", "postcode": "17500001", "country_name": "Brasil", "country_code": "BRA", "latitude": "-23.5475000", "longitude": "-46.6361100" } ], "phone_number": "+52-XXX-XXX-XXXX", "phone_numbers": [ { "is_main": true, "type": "MOBILE", "additional_info": "This is their work mobile number.", "number": "29875132", "country_code": "351", "area_code": "21", "extension": "932" } ], "parties": [ { "person_type": "INDIVIDUAL", "type": "MEMBER", "display_name": "Jack Oswald White", "social_name": "O Piadista", "company_name": "Wayne Enterprises", "trade_name": "WayneCorp", "start_date": "2021-07-15", "percentage_type": 0.51, "document_type": "CPF", "document_number": "DL-7896829-7", "document_issue_date": "2019-01-01", "document_expiration_date": "2019-01-01", "document_country": "CAN", "document_additional_info": "Confirmed CPF with their driver's licence." } ], "financial_profile": { "economic_activities": [ { "is_main": true, "code": "8599604" } ], "informed_revenue": { "frequency": "MONTHLY", "frequency_additional_info": "Recently switched from weekly to monthly.", "amount": 45391.89, "currency": "BRL", "year": 2022 }, "patrimony": { "amount": 45391.89, "currency": "BRL", "date": "2022-12-12" } }, "financial_relation": { "start_date": "2021-05-21T08:30:00Z", "product_services": [ "CONTA_DEPOSITO_A_VISTA" ], "procurators": [ { "type": "LEGAL_REPRESENTATIVE", "civil_name": "Alfred Thaddeus Pennyworth", "social_name": "Alfred Pennyworth", "document_number": "73677831148" } ], "products": [ { "type": "SAVINGS_ACCOUNT", "subtype": "CONJUNTA_SIMPLES", "agency": "6272", "clearing_code": "001", "number": "24550245", "check_digit": "7" } ] } } }, "imss_example_paginated": { "summary": "IMSS Example", "description": "Example of a paginated IMSS response.", "value": { "count": 20, "next": "https://sandbox.belvo.com/api/employment-records/?page=2", "previous": null, "results": [ { "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04", "link": "27c1d5cf-e8fb-433a-a2f7-d246de199c01", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "report_date": "2023-01-19", "days_since_extraction": 42, "internal_identification": "BLPM951331IONVGR54", "personal_data": { "official_name": "Bruce Banner del Torro", "first_name": "Bruce", "last_name": "Banner del Torro", "email": "bruce.banner@avengers.com", "birth_date": "2022-02-09", "entitlements": { "entitled_to_health_insurance": true, "entitled_to_company_benefits": true, "valid_until": null, "status": "EMPLOYED" }, "document_ids": [ { "document_type": "NSS", "document_number": "10277663582" }, { "document_type": "CURP", "document_number": "BLPM951331IONVGR54" } ] }, "social_security_summary": { "weeks_redeemed": 0, "weeks_reinstated": 0, "weeks_contributed": 188 }, "employment_records": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "employer": "Batman Enterprises CDMX", "employer_id": "780-BAT-88769-CDMX", "start_date": "2019-10-10", "end_date": null, "weeks_employed": 12, "state": "DISTRITO FEDERAL", "most_recent_base_salary": 762.54, "monthly_salary": 23193.92, "currency": "MXN", "employment_status_updates": [ { "event": "HIRED", "base_salary": 500.09, "update_date": "2021-09-01" }, { "event": "SALARY_MODIFICATION", "base_salary": 678.09, "update_date": "2022-09-01" }, { "event": "SALARY_MODIFICATION", "base_salary": 762.54, "update_date": "2023-09-01" } ] } ], "employment_scores": [ { "score": 722, "period": 3, "version": "1.0.0" }, { "score": 612, "period": 6, "version": "1.0.0" }, { "score": 570, "period": 12, "version": "1.0.0" } ], "salary_estimation": { "employment_status_estimate": "EMPLOYED", "base_salary_estimate": 1000, "currency": "MXN" }, "files": [ { "type": "ReporteSemanasCotizadas_190123", "value": "=PDF_BINARY=" } ] } ] } }, "issste_example_paginated": { "summary": "ISSSTE Example", "description": "Example of a paginated ISSSTE response.", "value": { "count": 20, "next": "https://sandbox.belvo.com/api/employment-records/?page=2", "previous": null, "results": [ { "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04", "link": "27c1d5cf-e8fb-433a-a2f7-d246de199c01", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "report_date": "2023-01-19", "days_since_extraction": 42, "internal_identification": "BAOC850505HCCRPL00", "personal_data": { "official_name": "Clint Barton de Hacienda", "first_name": "Clint", "last_name": "Barton de Hacienda", "email": "clint.hacienda@avengers.com", "birth_date": "2022-02-09", "entitlements": { "entitled_to_health_insurance": true, "entitled_to_company_benefits": true, "valid_until": null, "status": "EMPLOYED" }, "document_ids": [ { "document_type": "NSS", "document_number": "21388774693" }, { "document_type": "CURP", "document_number": "BAOC850505HCCRPL00" }, { "document_type": "RFC", "document_number": "BAOC850505EB7" } ] }, "social_security_summary": null, "employment_records": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "employer": "Vengadores incorpora;Empresas Stark", "employer_id": null, "start_date": "2019-10-10", "end_date": null, "weeks_employed": 12, "state": null, "most_recent_base_salary": 762.54, "monthly_salary": 23193.92, "currency": "MXN", "employment_status_updates": [ { "event": "NORMAL", "base_salary": 1033.09, "update_date": "2021-09-01" } ] } ], "employment_scores": null, "salary_estimation": null, "files": [ { "type": "ReporteSemanasCotizadas_190123", "value": "=PDF_BINARY=" } ] } ] } }, "imss_example": { "summary": "IMSS Example", "description": "Example of an IMSS response.", "value": [ { "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04", "link": "27c1d5cf-e8fb-433a-a2f7-d246de199c01", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "report_date": "2023-01-19", "days_since_extraction": 42, "internal_identification": "BLPM951331IONVGR54", "personal_data": { "official_name": "Bruce Banner del Torro", "first_name": "Bruce", "last_name": "Banner del Torro", "email": "bruce.banner@avengers.com", "birth_date": "2022-02-09", "entitlements": { "entitled_to_health_insurance": true, "entitled_to_company_benefits": true, "valid_until": null, "status": "EMPLOYED" }, "document_ids": [ { "document_type": "NSS", "document_number": "10277663582" }, { "document_type": "CURP", "document_number": "BLPM951331IONVGR54" } ] }, "social_security_summary": { "weeks_redeemed": 0, "weeks_reinstated": 0, "weeks_contributed": 188 }, "employment_records": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "employer": "Batman Enterprises CDMX", "employer_id": "780-BAT-88769-CDMX", "start_date": "2019-10-10", "end_date": null, "weeks_employed": 12, "state": "DISTRITO FEDERAL", "most_recent_base_salary": 762.54, "monthly_salary": 23193.92, "currency": "MXN", "employment_status_updates": [ { "event": "HIRED", "base_salary": 500.09, "update_date": "2021-09-01" }, { "event": "SALARY_MODIFICATION", "base_salary": 678.09, "update_date": "2022-09-01" }, { "event": "SALARY_MODIFICATION", "base_salary": 762.54, "update_date": "2023-09-01" } ] } ], "employment_scores": [ { "score": 722, "period": 3, "version": "1.0.0" }, { "score": 612, "period": 6, "version": "1.0.0" }, { "score": 570, "period": 12, "version": "1.0.0" } ], "salary_estimation": { "employment_status_estimate": "EMPLOYED", "base_salary_estimate": 1000, "currency": "MXN" }, "files": [ { "type": "ReporteSemanasCotizadas_190123", "value": "=PDF_BINARY=" } ] } ] }, "issste_example": { "summary": "ISSSTE Example", "description": "Example of an ISSSTE response.", "value": [ { "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04", "link": "27c1d5cf-e8fb-433a-a2f7-d246de199c01", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "report_date": "2023-01-19", "days_since_extraction": 42, "internal_identification": "BAOC850505HCCRPL00", "personal_data": { "official_name": "Clint Barton de Hacienda", "first_name": "Clint", "last_name": "Barton de Hacienda", "email": "clint.hacienda@avengers.com", "birth_date": "2022-02-09", "entitlements": { "entitled_to_health_insurance": true, "entitled_to_company_benefits": true, "valid_until": null, "status": "EMPLOYED" }, "document_ids": [ { "document_type": "NSS", "document_number": "21388774693" }, { "document_type": "CURP", "document_number": "BAOC850505HCCRPL00" }, { "document_type": "RFC", "document_number": "BAOC850505EB7" } ] }, "social_security_summary": null, "employment_records": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "employer": "Vengadores incorpora;Empresas Stark", "employer_id": null, "start_date": "2019-10-10", "end_date": null, "weeks_employed": 12, "state": null, "most_recent_base_salary": 762.54, "monthly_salary": 23193.92, "currency": "MXN", "employment_status_updates": [ { "event": "NORMAL", "base_salary": 1033.09, "update_date": "2021-09-01" } ] } ], "employment_scores": null, "salary_estimation": null, "files": [ { "type": "ReporteSemanasCotizadas_190123", "value": "=PDF_BINARY=" } ] } ] }, "imss_example_detail": { "summary": "IMSS Example", "description": "Example of an IMSS response.", "value": { "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04", "link": "27c1d5cf-e8fb-433a-a2f7-d246de199c01", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "report_date": "2023-01-19", "days_since_extraction": 42, "internal_identification": "BLPM951331IONVGR54", "personal_data": { "official_name": "Bruce Banner del Torro", "first_name": "Bruce", "last_name": "Banner del Torro", "email": "bruce.banner@avengers.com", "birth_date": "2022-02-09", "entitlements": { "entitled_to_health_insurance": true, "entitled_to_company_benefits": true, "valid_until": null, "status": "EMPLOYED" }, "document_ids": [ { "document_type": "NSS", "document_number": "10277663582" }, { "document_type": "CURP", "document_number": "BLPM951331IONVGR54" } ] }, "social_security_summary": { "weeks_redeemed": 0, "weeks_reinstated": 0, "weeks_contributed": 188 }, "employment_records": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "employer": "Batman Enterprises CDMX", "employer_id": "780-BAT-88769-CDMX", "start_date": "2019-10-10", "end_date": null, "weeks_employed": 12, "state": "DISTRITO FEDERAL", "most_recent_base_salary": 762.54, "monthly_salary": 23193.92, "currency": "MXN", "employment_status_updates": [ { "event": "HIRED", "base_salary": 500.09, "update_date": "2021-09-01" }, { "event": "SALARY_MODIFICATION", "base_salary": 678.09, "update_date": "2022-09-01" }, { "event": "SALARY_MODIFICATION", "base_salary": 762.54, "update_date": "2023-09-01" } ] } ], "employment_scores": [ { "score": 722, "period": 3, "version": "1.0.0" }, { "score": 612, "period": 6, "version": "1.0.0" }, { "score": 570, "period": 12, "version": "1.0.0" } ], "salary_estimation": { "employment_status_estimate": "EMPLOYED", "base_salary_estimate": 1000, "currency": "MXN" }, "files": [ { "type": "ReporteSemanasCotizadas_190123", "value": "=PDF_BINARY=" } ] } }, "issste_example_detail": { "summary": "ISSSTE Example", "description": "Example of an ISSSTE response.", "value": { "id": "fef05fc8-7357-4a4a-9d29-55038ea31a04", "link": "27c1d5cf-e8fb-433a-a2f7-d246de199c01", "created_at": "2022-02-09T08:45:50.406032Z", "collected_at": "2022-02-09T08:45:50.406032Z", "report_date": "2023-01-19", "days_since_extraction": 42, "internal_identification": "BAOC850505HCCRPL00", "personal_data": { "official_name": "Clint Barton de Hacienda", "first_name": "Clint", "last_name": "Barton de Hacienda", "email": "clint.hacienda@avengers.com", "birth_date": "2022-02-09", "entitlements": { "entitled_to_health_insurance": true, "entitled_to_company_benefits": true, "valid_until": null, "status": "EMPLOYED" }, "document_ids": [ { "document_type": "NSS", "document_number": "21388774693" }, { "document_type": "CURP", "document_number": "BAOC850505HCCRPL00" }, { "document_type": "RFC", "document_number": "BAOC850505EB7" } ] }, "social_security_summary": null, "employment_records": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "employer": "Vengadores incorpora;Empresas Stark", "employer_id": null, "start_date": "2019-10-10", "end_date": null, "weeks_employed": 12, "state": null, "most_recent_base_salary": 762.54, "monthly_salary": 23193.92, "currency": "MXN", "employment_status_updates": [ { "event": "NORMAL", "base_salary": 1033.09, "update_date": "2021-09-01" } ] } ], "employment_scores": null, "salary_estimation": null, "files": [ { "type": "ReporteSemanasCotizadas_190123", "value": "=PDF_BINARY=" } ] } }, "InvoiceIngresoPaginated": { "summary": "Invoice Ingreso", "description": "Example of an *Igreso* type invoice.", "value": { "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Ingreso", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Servicios de mensajería.", "product_identification": "78102206", "quantity": 1, "unit_code": "E48", "unit_description": "Unidad de servicio", "unit_amount": 25, "pre_tax_amount": 25, "tax_percentage": 16, "tax_amount": 4, "total_amount": 29, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] } }, "InvoicePagoPaginated": { "summary": "Invoice Pago", "description": "Example of a *Pago* type invoice.", "value": { "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Pago", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": null, "payment_type_description": null, "payment_method": null, "usage": "P01", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Pago", "product_identification": "84111506", "quantity": 1, "unit_amount": 0, "unit_code": "ACT", "unit_description": null, "pre_tax_amount": 0, "tax_percentage": 0, "tax_amount": 0, "total_amount": 0, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 0, "exchange_rate": null, "tax_amount": 0, "discount_amount": 0, "total_amount": 0, "payments": [ { "date": "2020-03-17T12:00:00.000Z", "payment_type": "03", "currency": "BRL", "exchange_rate": "3.75", "amount": 8000.5, "operation_number": "831840", "beneficiary_rfc": "BNM840515VB1", "beneficiary_account_number": "12343453245633", "payer_rfc": "BKJM840515VB1", "payer_account_number": "13343663245699", "payer_bank_name": "CITI BANAMEX", "related_documents": [ { "invoice_identification": "7EE015F3-6311-11EA-B02A-00155D014007", "currency": "MXN", "payment_method": "PPD", "previous_balance": 18877.84, "amount_paid": 8000, "outstanding_balance": 10877.84 } ] } ], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] } }, "InvoiceNominaPaginated": { "summary": "Invoice Nomina", "description": "Example of a *Nomina* type invoice.", "value": { "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Nómina", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "ACNE SA DE CV", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "Roberto Martinez Diaz", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "99", "payment_type_description": null, "payment_method": "PUE", "usage": "P01", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Pago de nómina", "product_identification": "84111505", "quantity": 1, "unit_code": "ACT", "unit_description": null, "unit_amount": 20400.1, "total_amount": 20400.1, "pre_tax_amount": 20400.1, "tax_percentage": 0, "tax_amount": 0, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 20400.1, "exchange_rate": 1, "tax_amount": 0, "discount_amount": 5000, "total_amount": 15400.1, "payments": [], "payroll": { "days": 30, "type": "O", "amount": 20400.1, "date_to": "2020-12-31", "version": "1.2", "date_from": "2020-12-01", "collected_at": "2022-02-09T08:45:50.406032Z", "payment_date": "2020-12-24" }, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] } }, "InvoiceEgresoPaginated": { "summary": "Invoice Egreso", "description": "Example of an *Egreso* type invoice.", "value": { "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Egreso", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "product_identification": "78111500", "description": "Reembolso del servicio", "unit_code": "E48", "unit_description": "Unidad de servicio", "quantity": 1, "unit_amount": 25, "pre_tax_amount": 25, "tax_percentage": 16, "tax_amount": 4, "total_amount": 29, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] } }, "InvoiceTrasladoPaginated": { "summary": "Invoice Traslado", "description": "Example of a *Traslado* type invoice.", "value": { "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Traslado", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "ACNE SA DE CV", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "CARGOS S.A. DE C.V.", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": null, "payment_type_description": null, "payment_method": null, "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "FLETE", "product_identification": "78101802", "quantity": 1, "unit_code": "E48", "unit_description": "Unidad de servicio", "unit_amount": 21000, "pre_tax_amount": 21000, "tax_percentage": 16, "tax_amount": 0, "total_amount": 21000, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 0, "exchange_rate": 1, "tax_amount": 0, "discount_amount": 0, "total_amount": 0, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] } }, "InvoiceIngreso": { "summary": "Invoice Ingreso", "description": "Example of an *Igreso* type invoice.", "value": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Ingreso", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Servicios de mensajería.", "product_identification": "78102206", "quantity": 1, "unit_code": "E48", "unit_description": "Unidad de servicio", "unit_amount": 25, "pre_tax_amount": 25, "tax_percentage": 16, "tax_amount": 4, "total_amount": 29, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] }, "InvoicePago": { "summary": "Invoice Pago", "description": "Example of a *Pago* type invoice.", "value": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Pago", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": null, "payment_type_description": null, "payment_method": null, "usage": "P01", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Pago", "product_identification": "84111506", "quantity": 1, "unit_amount": 0, "unit_code": "ACT", "unit_description": null, "pre_tax_amount": 0, "tax_percentage": 0, "tax_amount": 0, "total_amount": 0, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 0, "exchange_rate": null, "tax_amount": 0, "discount_amount": 0, "total_amount": 0, "payments": [ { "date": "2020-03-17T12:00:00.000Z", "payment_type": "03", "currency": "BRL", "exchange_rate": "3.75", "amount": 8000.5, "operation_number": "831840", "beneficiary_rfc": "BNM840515VB1", "beneficiary_account_number": "12343453245633", "payer_rfc": "BKJM840515VB1", "payer_account_number": "13343663245699", "payer_bank_name": "CITI BANAMEX", "related_documents": [ { "invoice_identification": "7EE015F3-6311-11EA-B02A-00155D014007", "currency": "MXN", "payment_method": "PPD", "previous_balance": 18877.84, "amount_paid": 8000, "outstanding_balance": 10877.84 } ] } ], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] }, "InvoiceNomina": { "summary": "Invoice Nomina", "description": "Example of a *Nomina* type invoice.", "value": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Nómina", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "ACNE SA DE CV", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "Roberto Martinez Diaz", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "99", "payment_type_description": null, "payment_method": "PUE", "usage": "P01", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Pago de nómina", "product_identification": "84111505", "quantity": 1, "unit_code": "ACT", "unit_description": null, "unit_amount": 20400.1, "total_amount": 20400.1, "pre_tax_amount": 20400.1, "tax_percentage": 0, "tax_amount": 0, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 20400.1, "exchange_rate": 1, "tax_amount": 0, "discount_amount": 5000, "total_amount": 15400.1, "payments": [], "payroll": { "days": 30, "type": "O", "amount": 20400.1, "date_to": "2020-12-31", "version": "1.2", "date_from": "2020-12-01", "collected_at": "2022-02-09T08:45:50.406032Z", "payment_date": "2020-12-24", "periodicity": "MONTHLY", "earnings_breakdown": [ { "type": "SALARY", "taxable_amount": 20400.1, "vat_free_amount": 0 }, { "type": "BONUS", "taxable_amount": 1012.1, "vat_free_amount": 0 } ], "tax_deductions": [ { "type": "UNION_FEES", "amount": 1505 } ], "other_payments": [ { "type": "EMPLOYMENT_SUBSIDY", "amount": 1505 } ] }, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] }, "InvoiceEgreso": { "summary": "Invoice Egreso", "description": "Example of an *Egreso* type invoice.", "value": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Egreso", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "product_identification": "78111500", "description": "Reembolso del servicio", "unit_code": "E48", "unit_description": "Unidad de servicio", "quantity": 1, "unit_amount": 25, "pre_tax_amount": 25, "tax_percentage": 16, "tax_amount": 4, "total_amount": 29, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] }, "InvoiceTraslado": { "summary": "Invoice Traslado", "description": "Example of a *Traslado* type invoice.", "value": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Traslado", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "ACNE SA DE CV", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "CARGOS S.A. DE C.V.", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": null, "payment_type_description": null, "payment_method": null, "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "FLETE", "product_identification": "78101802", "quantity": 1, "unit_code": "E48", "unit_description": "Unidad de servicio", "unit_amount": 21000, "pre_tax_amount": 21000, "tax_percentage": 16, "tax_amount": 0, "total_amount": 21000, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 0, "exchange_rate": 1, "tax_amount": 0, "discount_amount": 0, "total_amount": 0, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } ] }, "InvoiceIngresoDetail": { "summary": "Invoice Ingreso", "description": "Example of an *Igreso* type invoice.", "value": { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Ingreso", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Servicios de mensajería.", "product_identification": "78102206", "quantity": 1, "unit_code": "E48", "unit_description": "Unidad de servicio", "unit_amount": 25, "pre_tax_amount": 25, "tax_percentage": 16, "tax_amount": 4, "total_amount": 29, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } }, "InvoicePagoDetail": { "summary": "Invoice Pago", "description": "Example of a *Pago* type invoice.", "value": { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Pago", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": null, "payment_type_description": null, "payment_method": null, "usage": "P01", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Pago", "product_identification": "84111506", "quantity": 1, "unit_amount": 0, "unit_code": "ACT", "unit_description": null, "pre_tax_amount": 0, "tax_percentage": 0, "tax_amount": 0, "total_amount": 0, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 0, "exchange_rate": null, "tax_amount": 0, "discount_amount": 0, "total_amount": 0, "payments": [ { "date": "2020-03-17T12:00:00.000Z", "payment_type": "03", "currency": "BRL", "exchange_rate": "3.75", "amount": 8000.5, "operation_number": "831840", "beneficiary_rfc": "BNM840515VB1", "beneficiary_account_number": "12343453245633", "payer_rfc": "BKJM840515VB1", "payer_account_number": "13343663245699", "payer_bank_name": "CITI BANAMEX", "related_documents": [ { "invoice_identification": "7EE015F3-6311-11EA-B02A-00155D014007", "currency": "MXN", "payment_method": "PPD", "previous_balance": 18877.84, "amount_paid": 8000, "outstanding_balance": 10877.84 } ] } ], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } }, "InvoiceNominaDetail": { "summary": "Invoice Nomina", "description": "Example of a *Nomina* type invoice.", "value": { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Nómina", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "ACNE SA DE CV", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "Roberto Martinez Diaz", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "99", "payment_type_description": null, "payment_method": "PUE", "usage": "P01", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "Pago de nómina", "product_identification": "84111505", "quantity": 1, "unit_code": "ACT", "unit_description": null, "unit_amount": 20400.1, "total_amount": 20400.1, "pre_tax_amount": 20400.1, "tax_percentage": 0, "tax_amount": 0, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 20400.1, "exchange_rate": 1, "tax_amount": 0, "discount_amount": 5000, "total_amount": 15400.1, "payments": [], "payroll": { "days": 30, "type": "O", "amount": 20400.1, "date_to": "2020-12-31", "version": "1.2", "date_from": "2020-12-01", "collected_at": "2022-02-09T08:45:50.406032Z", "payment_date": "2020-12-24", "periodicity": "MONTHLY", "earnings_breakdown": [ { "type": "SALARY", "taxable_amount": 20400.1, "vat_free_amount": 0 }, { "type": "BONUS", "taxable_amount": 1012.1, "vat_free_amount": 0 } ], "tax_deductions": [ { "type": "UNION_FEES", "amount": 1505 } ], "other_payments": [ { "type": "EMPLOYMENT_SUBSIDY", "amount": 1505 } ] }, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } }, "InvoiceEgresoDetail": { "summary": "Invoice Egreso", "description": "Example of an *Egreso* type invoice.", "value": { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Egreso", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "product_identification": "78111500", "description": "Reembolso del servicio", "unit_code": "E48", "unit_description": "Unidad de servicio", "quantity": 1, "unit_amount": 25, "pre_tax_amount": 25, "tax_percentage": 16, "tax_amount": 4, "total_amount": 29, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } }, "InvoiceTrasladoDetail": { "summary": "Invoice Traslado", "description": "Example of a *Traslado* type invoice.", "value": { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Traslado", "type": "INFLOW", "sender_id": "GHTF980303F7", "sender_name": "ACNE SA DE CV", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "CARGOS S.A. DE C.V.", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": null, "payment_type_description": null, "payment_method": null, "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ { "description": "FLETE", "product_identification": "78101802", "quantity": 1, "unit_code": "E48", "unit_description": "Unidad de servicio", "unit_amount": 21000, "pre_tax_amount": 21000, "tax_percentage": 16, "tax_amount": 0, "total_amount": 21000, "retained_taxes": [], "collected_at": "2022-02-09T08:45:50.406032Z" } ], "currency": "MXN", "subtotal_amount": 0, "exchange_rate": 1, "tax_amount": 0, "discount_amount": 0, "total_amount": 0, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { "code": "warning_code", "message": "warning message" } } }, "TaxReturnPersonalListPaginated": { "summary": "Tax Return Personal", "description": "Example of a list of personal tax returns", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "02589c41-ba22-4d44-8558-8111cc751318", "link": "19697249-01b8-443e-a451-76bfc5fbeebf", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "ejercicio": 2018, "fecha_hora_presentacion": "2020-01-07T17:28:00-05:00", "numero_operacion": "00000000001", "periodo_declaracion": "Del Ejercicio", "rfc": "ABCD111111A11", "tipo_declaracion": "Normal", "nombre": "JOHN DOE" }, "sueldos_salarios": { "retenedores": [ { "rfc_retenedor": "ABCD222222A22", "nombre_denominacion_razon_social": "ACME CORP", "ingresos_exentos": 118263, "ingreso_anual": 2265, "subsidio_empleo": 0 } ], "impuesto_retenido": 19497, "ingreso_anual": 118263, "ingresos_acumulables": 115998, "ingresos_exentos": 2265, "subsidio_empleo": 0 }, "servicios_profesionales": { "deducciones_autorizadas": { "deducciones_autorizadas": 11870, "otras_deducciones": null, "detalle_deducciones": [ { "tipo_deduccion": "GASTOS", "concepto": "GASOLINA Y MANTENIMIENTO DE TRANSPORTE", "monto_detallado": 9682 }, { "tipo_deduccion": "GASTOS", "concepto": "COMPRAS Y GASTOS GENERALES", "monto_detallado": 2188 } ], "total_deducciones_autorizadas": 11870 }, "ingresos": { "ingresos_acumulables": 46000, "ingresos_exentos": null, "otros_ingresos": null, "total_ingresos": 46000 }, "resultado_fiscal": { "utilidad_fiscal": 34130, "ptu_pagada_ejercicio": 0, "perdidas_fiscales_ejercicios_anteriores_aplicadas": 0, "utilidad_gravable": 34130 }, "pagos_provisionales": { "pagos_provisionales_efectuados_en_ejercicio": 0 }, "retenciones_isr": { "isr_retenido_personas_morales": 4600 } }, "deducciones_personales": { "honorarios_medicos_dentales_hospitalarios": [ { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A44", "monto_deducible": 1000 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A44", "monto_deducible": 502.34 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A55", "monto_deducible": 14183.1 }, { "rfc_emisor": "ABC444444A66", "monto_deducible": 1658 }, { "rfc_emisor": "ABC444444A77", "monto_deducible": 1600 }, { "rfc_emisor": "ABC444444A88", "monto_deducible": 1064 }, { "rfc_emisor": "ABC444444A99", "monto_deducible": 927.57 } ], "donativos": [ { "rfc_emisor": "ABC555555A99", "monto_deducible": 10.03 } ], "aportaciones_voluntarias_complementarias_al_sar": [ { "rfc_emisor": "ABC666666A99", "monto_deducible": 12.03 }, { "rfc_emisor": "ABC777777A99", "monto_deducible": 87.22 } ], "primas_por_seguros_de_gasto_medico": [ { "rfc_emisor": "ABC777777A99", "monto_deducible": 20.03 } ] }, "determinacion_impuesto": { "base_gravable": 126864, "deducciones_personales": 23264, "ingresos_acumulables": 150128, "isr_favorable": 10308, "isr_conforme_tarifa_final": 13789, "isr_retenido": 24097, "num_clabe": "000000000000000001", "nombre_banco": "BANCO SA", "pagos_provisionales": 0, "titular_clabe_permite_verificacion": "SÍ", "accion_saldo_a_favor": "DEVOLUCIÓN" }, "retenciones": { "sueldos_salarios": [ { "rfc_retenedor": "ABC444444A99", "monto_retenciones": 118263, "retenciones_isr": 19497 } ], "dividendos": [], "servicios_profesionales": [ { "rfc_retenedor": "ABC444444A00", "monto_retenciones": 46000, "retenciones_isr": 4600 } ] }, "dividendos": { "monto_acumulable_dividendos_utilidades": null, "monto_total_isr_pagado_sociedad": null }, "datos_informativos": { "credito_fiscal_autorizado_proyectos_investigacion_desarrollo": 0, "credito_fiscal_autorizado_proyectos_apoyo_deporte_alto_rendimiento": 0, "credito_fiscal_autorizado_proyectos_inversion_artes": 0, "credito_fiscal_autorizado_inversion_equipos_fijos": 0, "credito_fiscal_autorizado_produccion_distribucion_cinematografica": 0, "saldo_credito_fiscal_autorizado_anteriores_investigacion_desarrollo": 0, "saldo_credito_fiscal_anteriores_proyectos_inversion_artes": 0, "saldo_credito_fiscal_anteriores_produccion_distribucion_cinematografica": 0 }, "pdf": "=PDF-STRING=", "receipt_pdf": "=PDF-STRING=", "type": "yearly" } ] } }, "TaxReturnPersonalListMonthlyPaginatedPFAE": { "summary": "Tax Return Personal Monthly (PFAe)", "description": "Example of a list of PFAE-type monthly personal tax returns", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": null, "nombre": null, "tipo_declaracion": null, "ejercicio": null, "periodo_declaracion": null, "fecha_hora_presentacion": null, "numero_operacion": null }, "isr": { "tipo": "PFAE", "determinacion": { "ingresos_periodos_anteriores": 0, "ingresos_periodo": 0, "total_ingresos": 0, "compras_gastos_periodos_anteriores": 1596, "compra_gastos_periodo": 399, "total_compras_gastos": 1995, "base_gravable_pago_provisional": 0, "isr_causado": 0, "pagos_provisionales_efectuados_anterioridad": 0, "isr_retenido_periodos_anteriores": 0, "impuesto_retenido": 0, "isr_cargo": 0 }, "detalle_del_pago": { "a_cargo": 0, "parte_actualizada": 0, "recargos": 0, "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0 } }, "iva": { "determinacion": { "actividades_gravadas_tasa_16": 0, "actividades_gravadas_tasa_0": 0, "actividades_exentas": 0, "iva_cobrado_periodo_tasa_16": 0, "iva_acreditable_periodo": 0, "iva_retenido": 0, "saldo_a_favor": null, "impuesto_a_favor": null }, "detalle_del_pago": { "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0, "a_favor": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } ] } }, "TaxReturnPersonalListMonthlyPaginatedPFAI": { "summary": "Tax Return Personal Monthly (PFAI)", "description": "Example of a list of PFAI-type monthly personal tax returns", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": null, "nombre": null, "tipo_declaracion": null, "ejercicio": null, "periodo_declaracion": null, "fecha_hora_presentacion": null, "numero_operacion": null }, "isr": { "tipo": "PFAE", "determinacion": { "ingresos_periodos_anteriores": 0, "ingresos_periodo": 0, "total_ingresos": 0, "compras_gastos_periodos_anteriores": 1596, "compra_gastos_periodo": 399, "total_compras_gastos": 1995, "base_gravable_pago_provisional": 0, "isr_causado": 0, "pagos_provisionales_efectuados_anterioridad": 0, "isr_retenido_periodos_anteriores": 0, "impuesto_retenido": 0, "isr_cargo": 0, "tipo_de_deduccíon": "dedduccíon opicional", "optas_por_el_cálculo_acumulado": "NO", "deduccíon_opcional": 700, "impuesto_predial": 0, "total_deducciones_autorizadas": 700, "tienes_facilidades_administrativas_o_estímulos_deducibles": "NO" }, "detalle_del_pago": { "a_cargo": 0, "parte_actualizada": 0, "recargos": 0, "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0 } }, "iva": { "determinacion": { "actividades_gravadas_tasa_16": 0, "actividades_gravadas_tasa_0": 0, "actividades_exentas": 0, "iva_cobrado_periodo_tasa_16": 0, "iva_acreditable_periodo": 0, "iva_retenido": 0, "saldo_a_favor": null, "impuesto_a_favor": null, "impuesto_a_cargo": 54, "cantidad_a_cargo": 54 }, "detalle_del_pago": { "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0, "a_favor": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } ] } }, "TaxReturnBusinessListPaginated": { "summary": "Tax Return Business", "description": "Example of a list of business tax returns", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "02589c41-ba22-4d44-8558-8111cc751318", "link": "19697249-01b8-443e-a451-76bfc5fbeebf", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "ejercicio": 2018, "fecha_hora_presentacion": "2020-01-07T16:55:00-06:00", "numero_operacion": "000000000001", "periodo_declaracion": "Del Ejercicio", "rfc": "ABC1111111A1", "tipo_declaracion": "Normal", "tipo_complementaria": null, "denominacion_razon_social": "ACME CORP" }, "datos_adicionales": { "indica_si_optas_por_dictaminar_tus_estados_financieros": "NO", "estas_obligado_a_presentar_la_informacion_sobre_tu_situacion_fiscal": "NO", "estas_obligado_unicamente_por_supuesto_distinto_al_de_haber_realizado_operaciones_con_residentes_extranjero": "SIN SELECCIÓN", "estas_obligado_unicamente_por_supuesto_distinto_al_de_haber_realizado_operaciones_con_residentes_extranjero_inferiores_100mdp": "SIN SELECCIÓN", "optas_por_presentar_informacion_sobre_tu_situacion_fiscal": "SIN SELECCIÓN", "indica_si_te_dedicas_exclisivamente_a_generacion_energia_fuentes_renovables_o_cogeneracion_electricidad_eficiente": "NO" }, "estado_resultados": { "ventas_servicios_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": 911165, "total": 911165 }, "ventas_servicios_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "devoluciones_descuentos_bonificaciones_ventas_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "devoluciones_descuentos_bonificaciones_ventas_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "ingresos_netos": { "partes_relacionadas": null, "partes_no_relacionadas": 911165, "total": 911165 }, "inventario_inicial": null, "compras_netas_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "compras_netas_importacion": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "inventario_final": null, "costo_mercancias": null, "mano_de_obra": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "maquilas": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "gastos_indirectos_fabricacion": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "costo_ventas_servicios": null, "utilidad_bruta": 911165, "perdida_bruta": null, "gastos_operacion": { "partes_relacionadas": null, "partes_no_relacionadas": 499540, "total": 499540 }, "utilidad_operacion": 411625, "perdida_operacion": null, "intereses_devengados_a_favor_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_favor_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_favor_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_favor_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "ganancia_cambiaria": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_cargo_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_cargo_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_cargo_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_cargo_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "perdida_cambiaria": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "resultado_posicion_monetaria_favorable": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "resultado_posicion_monetaria_desfavorable": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras": null, "resultado_integral_financiamiento": null, "otros_gastos_nacionales": null, "otros_gastos_extranjero": null, "otros_gastos": null, "otros_productos_nacionales": null, "otros_productos_extranjero": null, "otros_productos": null, "ingresos_partidas_discontinuas_extraordinarias": null, "gastos_partidas_discontinuas_extraordinarias": null, "utilidad_antes_impuesto": 411625, "perdida_antes_impuesto": null, "isr": 113002, "ietu": null, "impac": null, "ptu": null, "utilidad_participacion_subsidiaria": null, "perdida_participacion_subsidiaria": null, "efectos_reexpresion_favorables_excepto_resultado_posicion_monetaria": null, "efectos_reexpresion_desfavorables_excepto_resultado_posicion_monetaria": null, "utilidad_neta": 298623, "perdida_neta": null }, "estado_posicion_financiera_balance": { "activo": { "efectivo_caja_depositos_instituciones_credito_nacionales": 726644, "efectivo_caja_depositos_instituciones_credito_extranjero": null, "inversiones_valores_instituciones_nacionales_excepto_acciones": null, "inversiones_valores_instituciones_extranjero_excepto_acciones": null, "cuentas_documentos_por_cobrar_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "cuentas_documentos_por_cobrar_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "contribuciones_a_favor": null, "inventarios": null, "otros_activos_circulantes": 13277, "inversiones_en_acciones_nacionales": null, "inversiones_en_acciones_extranjero": null, "inversiones_en_acciones_total": null, "terrenos": null, "construcciones": null, "construcciones_en_proceso": null, "maquinaria_y_equipo": null, "mobiliario_y_equipo_oficina": null, "equipo_de_computo": null, "equipo_de_transporte": null, "otros_activos_fijos": 12756, "depreciacion_acumulada": -106, "cargos_y_gastos_diferidos": 9319, "amortizacion_acumulada": null, "suma_activo": 761890 }, "pasivo": { "cuentas_documentos_por_pagar_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": 268227, "total": 268227 }, "cuentas_documentos_por_pagar_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "contribuciones_por_pagar": 223490, "anticipos_de_clientes": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "aportaciones_futuros_aumentos_de_capital": null, "otros_pasivos": null, "suma_pasivo": 491717 }, "capital_contable": { "capital_social_proveniente_aportaciones": 10000, "capital_social_proveniente_capitalizacion": null, "reservas": null, "otras_cuentas_capital": null, "aportaciones_futuros_aumentos_de_capital": null, "utilidades_acumuladas": null, "utilidad_del_ejercicio": 298623, "perdidas_acumuladas": -38450, "perdida_del_ejercicio": null, "exceso_en_actualizacion_capital": null, "insuficiencia_en_actualizacion_capital": null, "actualizacion_del_capital_contable": null, "suma_capital_contable": 270173, "suma_pasivo_mas_capital_contable": 761890 } }, "conciliacion_entre_resultado_contable_fiscal": { "utilidad_o_perdida_neta": 298623, "efectos_reexpresion": null, "resultado_posicion_monetaria": null, "utilidad_o_perdida_neta_historica": 298623, "ingresos_fiscales_no_contables": 95, "ajuste_anual_inflacion_acumulable": 95, "anticipos_de_clientes": null, "intereses_moratorios_efectivamente_cobrados": null, "ganancia_en_enajenacion_acciones_por_reembolso_capital": null, "ganancia_en_enajenacion_de_terrenos_y_activo_fijo": null, "inventario_acumulable_del_ejercicio": null, "otros_ingresos_fiscales_no_contables": null, "deducciones_contables_no_fiscales": 117415, "costo_de_ventas_contable": null, "depreciacion_y_amortizacion_contable": 106, "gastos_que_no_reunen_requisitos_fiscales": 4307, "isr_ietu_impac_ptu": 113002, "perdida_contable_enajenacion_de_acciones": null, "perdida_contable_enajenacion_de_activo_fijo": null, "perdida_en_participacion_subsidiaria": null, "intereses_devengados_que_exceden_valor_mercado_y_moratorios_pagados_o_no": 0, "otras_deducciones_contables_no_fiscales": 0, "deducciones_fiscales_no_contables": 0, "ajuste_anual_inflacion_deducible": null, "costo_vendido_fiscal": null, "deduccion_inversiones": null, "estimulo_fiscal_por_deduccion_inmediata_inversiones": null, "donacion_bienes_basicos_subsistencia_humana": 0, "estimulo_fiscal_contratacion_personas_discapacidad_yo_mayores": 0, "deduccion_impuesto_sobre_renta_retenido_personas_discapacidad_yo_mayores": 0, "perdida_fiscal_en_enajenacion_acciones": null, "perdida_fiscal_en_enajenacion_de_terrenos_y_activo_fijo": null, "intereses_moratorios_efectivamente_pagados": null, "otras_deducciones_fiscales_no_contables": null, "ingresos_contables_no_fiscales": null, "intereses_moratorios_devengados_a_favor_cobrados_o_no": null, "anticipos_de_clientes_ejercicios_anteriores": null, "saldos_a_favor_impuestos_y_su_actualizacion": null, "utilidad_contable_enajenacion_de_activo_fijo": null, "utilidad_contable_enajenacion_de_acciones": null, "utilidad_en_participacion_subsidiaria": null, "otros_ingresos_contables_no_fiscales": null, "utilidad_o_perdida_fiscal_antes_de_ptu": 416133 }, "deducciones_autorizadas": { "sueldos_salarios": null, "honorarios_pagados_a_personas_fisicas": null, "regalias_y_asistencia_tecnica": null, "donativos_otorgados": null, "uso_o_goce_temporal_de_bienes_pagados_a_personas_fisicas": null, "fletes_y_acarreos_pagados_a_parsonas_fisicas": null, "contribuciones_pagadas_excepto_isr_ietu_impac_iva_ieps": null, "seguros_fianzas": null, "perdida_por_creditos_incobrables": null, "viaticos_y_gastos_viaje": 59527, "combustible_y_lubricantes": null, "credito_al_salario_no_disminuido_de_contribuciones": null, "aportaciones_sar_infonavit_y_jubilaciones_vejez": null, "aportaciones_para_fondos_de_pensiones_y_jubilaciones": null, "cuotas_imss": null, "consumos_en_restaurantes": 11254, "perdida_por_operaciones_financieras_derivadas": null, "deduccion_por_concepto_de_ayuda_alimentaria_para_trabajadores": null, "monto_total_pagos_que_sean_ingresos_exentos_para_trabajador": null, "monto_deducible_al_47_pagos_son_ingresos_exentos_para_trabajador": null, "monto_deducible_al_53_pagos_son_ingresos_exentos_para_trabajador": null, "uso_o_goce_temporal_de_automoviles_baterias_electricas_o_electricos_con_motor_combustion_o_hidrogeno": null, "otras_deducciones_autorizadas": 424346, "total_deducciones_autorizadas": 495127 }, "cifras_cierre_ejercicio": { "perdidas_fiscales_de_ejercicios_anteriores_pendientes_de_amortizar_actualiazadas": null, "saldo_promedio_anual_de_creditos": 142795, "saldo_promedio_anual_de_deudas": 144765, "coeficiente_de_utilidad_por_aplicar_en_ejercicio_siguiente": 0.4567, "porcentaje_de_participacion_consolidable": null, "isr_causado_en_exceso_del_impac_en_los_3_ejercicios_anteriores_pendientes_aplicar": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_neta_2013_y_anteriores": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_neta_a_partir_2014_y_anteriores": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_reinvertida": null, "saldo_actualizado_de_cuenta_de_capital_de_aportacion": null, "saldo_de_cuenta_de_utilidad_fiscal_neta_por_inversion_en_renovables": null }, "determinacion_del_impuesto_sobre_la_renta": { "determinacion_del_impuesto_sobre_la_renta": { "total_ingresos_acumulables": 911260, "total_deducciones_autorizadas_y_deduccion_inmediata_inversiones": 495126, "deduccion_adicional_por_pago_servicios_personales_en_operacion_maquila": null, "utilidad_o_perdida_fiscal_antes_de_ptu": 416134, "ptu_pagada_en_el_ejercicio": null, "utilidad_fiscal_del_ejercicio": 416134, "perdidas_fiscales_de_ejercicios_anteriores_que_se_aplican_en_ejercicio": 39462, "resultado_fiscal": 376672, "impuesto_causado_en_ejercicio": 113002, "tienes_estimulos_fiscales_a_acreditar": "SIN SELECCIÓN", "impuesto_sobre_la_renta_del_ejercicio": 113002, "pagos_provisionales_efectuados_enterados_a_federacion": null, "impuesto_retenido_al_contribuyente": null, "impuesto_acreditable_pagado_en_extranjero": null, "impuesto_acreditable_por_dividendos_o_utilidades_distribuidos": null, "otras_cantidades_a_cargo": null, "otras_cantidades_a_favor": null, "diferencia_a_cargo": 113002, "isr_a_cargo_del_ejercicio": 113002, "isr_a_favor_del_ejercicio": null }, "impuesto_sobre_ingresos_sujetos_a_regimenes_fiscales_preferentes": null, "datos_informativos_ejercicio": { "monto_aplicado_del_estimulo_fiscal_de_chatarrizacion": 0, "monto_deducible_de_pagos_efectuados_por_uso_o_goce_temporal_automoviles": 0, "impac_recuperado_en_ejercicio_derivado_de_deconsolidacion": 0, "ingresos_obtenidos_por_apoyos_gubernamentales": 0, "gastos_realidados_en_ejercicio_por_proyectos_en_investigacion_desarrollo_tecnologico": 0, "credito_fiscal_autorizado_en_ejercicio_por_proyectos_en_investigacion_desarrollo_tecnologico_pendiente_aplicar": 0, "credito_fiscal_autorizado_en_ejercicio_por_proyectos_de_inversion_en_artes_pendiente_aplicar": 0, "credito_fiscal_autorizado_en_ejercicio_por_inversion_en_proyectos_programas_para_deporte_de_alto_rendimiento_pendiente_aplicar": 0, "saldo_pendiente_aplicar_por_inversion_en_equipos_de_alimentacion_vehiculos_electricos": 0, "credito_fiscal_autorizado_en_ejercicio_a_produccion_distribucion_cinematografica_nacional_pendiente_aplicar": 0 }, "datos_informativos_ejercicios_anteriores_aplicados_en_ejercicio": { "total_estimulo_produccion_y_distribucion_cinematografica_nacional_ejercicios_anteriores_aplicado_en_ejercicio": null, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_inversion_en_proyectos_programas_para_deporte_alto_rendimiento_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_proyectos_investigacion_desarrollo_tecnologico_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_proyectos_inversion_artes_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_a_produccion_distribucion_nacional_pendiente_aplicar": 0 } }, "dividendos_o_utilidades_distribuidos": { "provenientes_de_cuenta_de_utilidad_fisica_neta_cufin_generada_en_2013_y_anteriores": null, "provenientes_de_cuenta_de_utilidad_fisica_neta_cufin_generada_a_partir_de_2014": null, "provenientes_de_cuenta_de_utilidad_fisica_neta_reinvertida_cufinre": null, "no_provenientes_de_cufin_ni_cufinre_en_efectivo": null, "no_provenientes_de_cufin_ni_cufinre_en_acciones": null, "monto_del_impuesto_pagado_no_proveniente_de_cufin_ni_cufinre": null, "monto_del_impuesto_pagado_de_utilidades_provenientes_de_cufinre": null, "provenientes_de_cuenta_de_utilidad_fiscal_neta_por_inversion_en_energia_de_fuentes_renovables_o_sistemas_cogeneracion_electricidad_eficiente": null }, "detalle_pago_r1_isr_personas_morales": { "a_cargo": 113002, "parte_actualizada": null, "recargos": null, "multa_por_correccion": null, "total_contribuciones": 113002, "desea_aplicar_alguna_compensacion_o_estimulo": "NO", "cantidad_a_cargo": 113002, "opta_por_pagar_parcialidades": "SIN SELECCIÓN", "importe_de_primera_parcialidad": null, "importe_sin_primera_parcialidad": null, "cantidad_a_favor": null, "cantidad_a_pagar": 113002 }, "pdf": "=PDF-STRING=", "receipt_pdf": "=PDF-STRING=", "type": "yearly" } ] } }, "TaxReturnBusinessListMonthlyPaginated": { "summary": "Tax Return Business Monthly", "description": "Example of a list of monthly business tax returns", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": "DPA950805RR2", "denominacion_razon_social": "Aloha Mahalo SC", "tipo_declaracion": "Normal", "ejercicio": 2020, "periodo_declaracion": "Diciembre", "fecha_hora_presentacion": "2021-01-18T19:24:00-06:00", "numero_operacion": "400475119", "tipo_complementaria": null }, "determinacion_isr": { "personas_morales_regimen_general": { "suma_ingresos_nominales_meses_anteriores_ejercicio": 69848414, "estimulos_acreditables": null, "ingresos_nominales_mes_que_declara": 6482479, "reducciones": null, "total_ingresos_nominales": 76330893, "impuestos_del_periodo": 284098, "coeficiente_utilidad": 0.2318, "pagos_provisionales_efectuados_anterioridad": 303039, "utilidad_fiscal_pago_provisional": 17693501, "impuesto_retenido": 29925, "ptu": null, "otras_cantidades_a_cargo_contribuyente": null, "iventario_acumulable": null, "otras_cantidades_a_favor_contribuyente": null, "anticipos_rendimientos_distribuidos_periodo": 16746509, "diferencia_a_cargo": 0, "perdidas_fiscales_ejercicios_anteriores_pendientes": null, "estimulo_fiscal_deduccion_inmediata": null, "impuesto_correspondiente_participacion_consolidable": null, "deduccion_adicional_fomento_primer_empleo": null, "porcentaje_participacion_consolidable": null, "base_gravable_pago_provisional": 946992, "impuesto_a_cargo": 0, "isr_causado": 284098, "ieps_alcohol": null } }, "detalle_pago_isr": { "r1_isr_personas_morales": { "a_cargo": 0, "acreditamiento_sorteo_buen_fin": null, "parte_actualizada": null, "diesel_marino": null, "recargos": null, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 0, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 0, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "uso_infraestructura_carretera_cuota": null, "cantidad_a_pagar": 0, "otros_estimulos": null, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r12_isr_retenciones_por_salarios": { "a_cargo": 415945, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 379, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 415945, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": 379, "cantidad_a_cargo": 415566, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 415566, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r13_isr_retenciones_por_asimilados_a_salarios": { "a_cargo": 254588, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 254588, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 254588, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 254588, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r14_isr_retenciones_por_servicios_profesionales": { "a_cargo": 104482, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 104482, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 104482, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 104482, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null } }, "determinacion_iva": { "montos_actos_actividades_pagados": { "total_actos_actividades_pagados_tasa_16": 2094706, "total_actos_actividades_pagados_importacion_bienes_tasa_11": null, "total_actos_actividades_sujetos_estimulo_rfn": 0, "total_actos_actividades_pagados_tasa_0": 0, "total_actos_actividades_pagados_importacion_bienes_tasa_16": null, "total_actos_actividades_pagados_no_paga_iva": 0 }, "detalle_total_actos_actividades_pagados_tasa_16": { "intereses_pagados_tasa_16": null, "otros_actos_pagados_tasa_16": 2094706, "regalias_pagadas_tasa_16": null, "total_actos_pagados_tasa_16": 2094706 }, "determinacion_iva_acreditable": { "total_iva_actos_actividades_pagados_tasa_16": 335153, "iva_trasladado_o_pagado_adquisicion_bienes_distintos_inversiones_actos_no_obligados_pago_impuesto": null, "iva_pagado_sujeto_estimulo_rfn": null, "iva_trasladado_o_pagado_importacion_inversiones_actos_no_obligados_pago_impuesto": null, "total_actos_actividades_pagados_importacion_bienes_tasa_16": 0, "iva_bienes_utilizados_indistintamente_actos_gravados_o_actos_no_obligados_pago_impuesto": 0, "proporcion_utilizada_conforme_art_5": null, "total_iva_trasladado_contribuyente": 335153, "proporcion_utilizada_conforme_art_5_b": null, "iva_trasladado_adquisicion_bienes_distintos_inversiones_actos_gravados": 335153, "iva_pagado_importacion_adquisicion_bienes_distintos_inversiones_actos_gravados": null, "iva_acreditable": 335153, "monto_acreditable_actualizado_a_incrementar_derivado_ajuste": null, "iva_pagado_importacion_inversiones_actos_gravados": null, "total_iva_acreditable_periodo": 335153, "total_iva_actos_actividades_gravados": 335153, "total_actos_actividades_pagados_importacion_bienes_tasa_11": null, "iva_trasladado_adquisicion_inversiones_actos_gravados": null, "iva_acreditable_bienes_utilizados_indistintamente_actos_gravados_o_actos_no_obligados_pago_impuesto": null }, "determinacion_iva": { "valor_actos_actividades_gravados_tasa_16": 6457950, "otras_cantidades_a_favor_contribuyente": null, "valor_actos_actividades_gravados_tasa_11": null, "cantidad_a_cargo": 312421, "valor_actos_actividades_gravados_tasa_0_exportacion": null, "saldo_a_favor": null, "valor_actos_actividades_gravados_tasa_9_otros": null, "devolucion_inmediata_obtenida": null, "suma_actos_actividades_gravados": 6457950, "saldo_a_favor_periodo": 0, "valor_actos_actividades_no_se_deba_pagar_impuesto_exentos": null, "acreditamiento_saldo_favor_periodos_anteriores": null, "impuesto_causado": 1033272, "diferencia_a_cargo": 312421, "cantidad_actualizada_a_reintegrarse_derivada_de_ajuste": null, "ieps_acreditable_alcohol": null, "iva_retenido_al_contribuyente": 385698, "impuesto_a_cargo": 312421, "total_iva_acreditable": 335153, "remanente_saldo_favor_ieps_alcohol": null, "otras_cantidades_a_cargo_contribuyente": null }, "detalle_valor_actos_actividades_gravados_tasa_16": { "intereses_cobrados_tasa_16": null, "otros_actos_actividades_gravados_tasa_16": 6457950, "regalias_entre_partes_relacionadas_tasa_16": null, "total_actos_actividades_gravados_tasa_16": 6457950 } }, "detalle_pago_iva": { "r21_iva": { "a_cargo": 312421, "cretificados_tesofe": null, "a_favor": null, "diesel_marino": null, "parte_actualizada": 0, "total_aplicaciones": 0, "recargos": 0, "fecha_pago_realizado_anterioridad": null, "multa_por_correccion": null, "monto_pagado_anterioridad": null, "total_de_contribuciones": 312421, "importe_pagado_ultimas_48_hrs": null, "credito_al_salario": null, "cantidad_a_cargo": 312421, "subsidio_empleo": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "diesel_automotriz_transporte": null, "uso_infraestructura_carretera_cuota": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 312421, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r21_iva_retenciones": { "a_cargo": 111448, "diesel_marino": null, "parte_actualizada": 0, "total_aplicaciones": 0, "recargos": 0, "fecha_pago_realizado_anterioridad": null, "multa_por_correccion": null, "monto_pagado_anterioridad": null, "total_de_contribuciones": 111448, "importe_pagado_ultimas_48_hrs": null, "credito_al_salario": null, "cantidad_a_cargo": 111448, "subsidio_empleo": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "otros_estimulos": null, "cantidad_a_favor": null, "cretificados_tesofe": null, "cantidad_a_pagar": 111448, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } ] } }, "TaxReturnPersonalList": { "summary": "Personal Yearly", "description": "Example of a list of personal tax returns", "value": [ { "id": "02589c41-ba22-4d44-8558-8111cc751318", "link": "19697249-01b8-443e-a451-76bfc5fbeebf", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "ejercicio": 2018, "fecha_hora_presentacion": "2020-01-07T17:28:00-05:00", "numero_operacion": "00000000001", "periodo_declaracion": "Del Ejercicio", "rfc": "ABCD111111A11", "tipo_declaracion": "Normal", "nombre": "JOHN DOE" }, "sueldos_salarios": { "retenedores": [ { "rfc_retenedor": "ABCD222222A22", "nombre_denominacion_razon_social": "ACME CORP", "ingresos_exentos": 118263, "ingreso_anual": 2265, "subsidio_empleo": 0 } ], "impuesto_retenido": 19497, "ingreso_anual": 118263, "ingresos_acumulables": 115998, "ingresos_exentos": 2265, "subsidio_empleo": 0 }, "servicios_profesionales": { "deducciones_autorizadas": { "deducciones_autorizadas": 11870, "otras_deducciones": null, "detalle_deducciones": [ { "tipo_deduccion": "GASTOS", "concepto": "GASOLINA Y MANTENIMIENTO DE TRANSPORTE", "monto_detallado": 9682 }, { "tipo_deduccion": "GASTOS", "concepto": "COMPRAS Y GASTOS GENERALES", "monto_detallado": 2188 } ], "total_deducciones_autorizadas": 11870 }, "ingresos": { "ingresos_acumulables": 46000, "ingresos_exentos": null, "otros_ingresos": null, "total_ingresos": 46000 }, "resultado_fiscal": { "utilidad_fiscal": 34130, "ptu_pagada_ejercicio": 0, "perdidas_fiscales_ejercicios_anteriores_aplicadas": 0, "utilidad_gravable": 34130 }, "pagos_provisionales": { "pagos_provisionales_efectuados_en_ejercicio": 0 }, "retenciones_isr": { "isr_retenido_personas_morales": 4600 } }, "deducciones_personales": { "honorarios_medicos_dentales_hospitalarios": [ { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A44", "monto_deducible": 1000 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A44", "monto_deducible": 502.34 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A55", "monto_deducible": 14183.1 }, { "rfc_emisor": "ABC444444A66", "monto_deducible": 1658 }, { "rfc_emisor": "ABC444444A77", "monto_deducible": 1600 }, { "rfc_emisor": "ABC444444A88", "monto_deducible": 1064 }, { "rfc_emisor": "ABC444444A99", "monto_deducible": 927.57 } ], "donativos": [ { "rfc_emisor": "ABC555555A99", "monto_deducible": 10.03 } ], "aportaciones_voluntarias_complementarias_al_sar": [ { "rfc_emisor": "ABC666666A99", "monto_deducible": 12.03 }, { "rfc_emisor": "ABC777777A99", "monto_deducible": 87.22 } ], "primas_por_seguros_de_gasto_medico": [ { "rfc_emisor": "ABC777777A99", "monto_deducible": 20.03 } ] }, "determinacion_impuesto": { "base_gravable": 126864, "deducciones_personales": 23264, "ingresos_acumulables": 150128, "isr_favorable": 10308, "isr_conforme_tarifa_final": 13789, "isr_retenido": 24097, "num_clabe": "000000000000000001", "nombre_banco": "BANCO SA", "pagos_provisionales": 0, "titular_clabe_permite_verificacion": "SÍ", "accion_saldo_a_favor": "DEVOLUCIÓN" }, "retenciones": { "sueldos_salarios": [ { "rfc_retenedor": "ABC444444A99", "monto_retenciones": 118263, "retenciones_isr": 19497 } ], "dividendos": [], "servicios_profesionales": [ { "rfc_retenedor": "ABC444444A00", "monto_retenciones": 46000, "retenciones_isr": 4600 } ] }, "dividendos": { "monto_acumulable_dividendos_utilidades": null, "monto_total_isr_pagado_sociedad": null }, "datos_informativos": { "credito_fiscal_autorizado_proyectos_investigacion_desarrollo": 0, "credito_fiscal_autorizado_proyectos_apoyo_deporte_alto_rendimiento": 0, "credito_fiscal_autorizado_proyectos_inversion_artes": 0, "credito_fiscal_autorizado_inversion_equipos_fijos": 0, "credito_fiscal_autorizado_produccion_distribucion_cinematografica": 0, "saldo_credito_fiscal_autorizado_anteriores_investigacion_desarrollo": 0, "saldo_credito_fiscal_anteriores_proyectos_inversion_artes": 0, "saldo_credito_fiscal_anteriores_produccion_distribucion_cinematografica": 0 }, "pdf": "=PDF-STRING=", "receipt_pdf": "=PDF-STRING=" } ] }, "TaxReturnPersonalListMonthlyPFAE": { "summary": "Personal Monthly (PFAE)", "description": "Example of a PFAE-type monthly personal tax return", "value": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": null, "nombre": null, "tipo_declaracion": null, "ejercicio": null, "periodo_declaracion": null, "fecha_hora_presentacion": null, "numero_operacion": null }, "isr": { "tipo": "PFAE", "determinacion": { "ingresos_periodos_anteriores": 0, "ingresos_periodo": 0, "total_ingresos": 0, "compras_gastos_periodos_anteriores": 1596, "compra_gastos_periodo": 399, "total_compras_gastos": 1995, "base_gravable_pago_provisional": 0, "isr_causado": 0, "pagos_provisionales_efectuados_anterioridad": 0, "isr_retenido_periodos_anteriores": 0, "impuesto_retenido": 0, "isr_cargo": 0 }, "detalle_del_pago": { "a_cargo": 0, "parte_actualizada": 0, "recargos": 0, "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0 } }, "iva": { "determinacion": { "actividades_gravadas_tasa_16": 0, "actividades_gravadas_tasa_0": 0, "actividades_exentas": 0, "iva_cobrado_periodo_tasa_16": 0, "iva_acreditable_periodo": 0, "iva_retenido": 0, "saldo_a_favor": null, "impuesto_a_favor": null }, "detalle_del_pago": { "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0, "a_favor": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } ] }, "TaxReturnPersonalListMonthlyPFAI": { "summary": "Personal Monthly (PFAI)", "description": "Example of a PFAI-type monthly personal tax return", "value": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": null, "nombre": null, "tipo_declaracion": null, "ejercicio": null, "periodo_declaracion": null, "fecha_hora_presentacion": null, "numero_operacion": null }, "isr": { "tipo": "PFAE", "determinacion": { "ingresos_periodos_anteriores": 0, "ingresos_periodo": 0, "total_ingresos": 0, "compras_gastos_periodos_anteriores": 1596, "compra_gastos_periodo": 399, "total_compras_gastos": 1995, "base_gravable_pago_provisional": 0, "isr_causado": 0, "pagos_provisionales_efectuados_anterioridad": 0, "isr_retenido_periodos_anteriores": 0, "impuesto_retenido": 0, "isr_cargo": 0, "tipo_de_deduccíon": "dedduccíon opicional", "optas_por_el_cálculo_acumulado": "NO", "deduccíon_opcional": 700, "impuesto_predial": 0, "total_deducciones_autorizadas": 700, "tienes_facilidades_administrativas_o_estímulos_deducibles": "NO" }, "detalle_del_pago": { "a_cargo": 0, "parte_actualizada": 0, "recargos": 0, "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0 } }, "iva": { "determinacion": { "actividades_gravadas_tasa_16": 0, "actividades_gravadas_tasa_0": 0, "actividades_exentas": 0, "iva_cobrado_periodo_tasa_16": 0, "iva_acreditable_periodo": 0, "iva_retenido": 0, "saldo_a_favor": null, "impuesto_a_favor": null, "impuesto_a_cargo": 54, "cantidad_a_cargo": 54 }, "detalle_del_pago": { "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0, "a_favor": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } ] }, "TaxReturnBusinessList": { "summary": "Business Yearly", "description": "Example of a list of business tax returns", "value": [ { "id": "02589c41-ba22-4d44-8558-8111cc751318", "link": "19697249-01b8-443e-a451-76bfc5fbeebf", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "ejercicio": 2018, "fecha_hora_presentacion": "2020-01-07T16:55:00-06:00", "numero_operacion": "000000000001", "periodo_declaracion": "Del Ejercicio", "rfc": "ABC1111111A1", "tipo_declaracion": "Normal", "tipo_complementaria": null, "denominacion_razon_social": "ACME CORP" }, "datos_adicionales": { "indica_si_optas_por_dictaminar_tus_estados_financieros": "NO", "estas_obligado_a_presentar_la_informacion_sobre_tu_situacion_fiscal": "NO", "estas_obligado_unicamente_por_supuesto_distinto_al_de_haber_realizado_operaciones_con_residentes_extranjero": "SIN SELECCIÓN", "estas_obligado_unicamente_por_supuesto_distinto_al_de_haber_realizado_operaciones_con_residentes_extranjero_inferiores_100mdp": "SIN SELECCIÓN", "optas_por_presentar_informacion_sobre_tu_situacion_fiscal": "SIN SELECCIÓN", "indica_si_te_dedicas_exclisivamente_a_generacion_energia_fuentes_renovables_o_cogeneracion_electricidad_eficiente": "NO" }, "estado_resultados": { "ventas_servicios_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": 911165, "total": 911165 }, "ventas_servicios_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "devoluciones_descuentos_bonificaciones_ventas_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "devoluciones_descuentos_bonificaciones_ventas_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "ingresos_netos": { "partes_relacionadas": null, "partes_no_relacionadas": 911165, "total": 911165 }, "inventario_inicial": null, "compras_netas_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "compras_netas_importacion": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "inventario_final": null, "costo_mercancias": null, "mano_de_obra": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "maquilas": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "gastos_indirectos_fabricacion": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "costo_ventas_servicios": null, "utilidad_bruta": 911165, "perdida_bruta": null, "gastos_operacion": { "partes_relacionadas": null, "partes_no_relacionadas": 499540, "total": 499540 }, "utilidad_operacion": 411625, "perdida_operacion": null, "intereses_devengados_a_favor_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_favor_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_favor_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_favor_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "ganancia_cambiaria": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_cargo_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_cargo_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_cargo_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_cargo_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "perdida_cambiaria": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "resultado_posicion_monetaria_favorable": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "resultado_posicion_monetaria_desfavorable": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras": null, "resultado_integral_financiamiento": null, "otros_gastos_nacionales": null, "otros_gastos_extranjero": null, "otros_gastos": null, "otros_productos_nacionales": null, "otros_productos_extranjero": null, "otros_productos": null, "ingresos_partidas_discontinuas_extraordinarias": null, "gastos_partidas_discontinuas_extraordinarias": null, "utilidad_antes_impuesto": 411625, "perdida_antes_impuesto": null, "isr": 113002, "ietu": null, "impac": null, "ptu": null, "utilidad_participacion_subsidiaria": null, "perdida_participacion_subsidiaria": null, "efectos_reexpresion_favorables_excepto_resultado_posicion_monetaria": null, "efectos_reexpresion_desfavorables_excepto_resultado_posicion_monetaria": null, "utilidad_neta": 298623, "perdida_neta": null }, "estado_posicion_financiera_balance": { "activo": { "efectivo_caja_depositos_instituciones_credito_nacionales": 726644, "efectivo_caja_depositos_instituciones_credito_extranjero": null, "inversiones_valores_instituciones_nacionales_excepto_acciones": null, "inversiones_valores_instituciones_extranjero_excepto_acciones": null, "cuentas_documentos_por_cobrar_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "cuentas_documentos_por_cobrar_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "contribuciones_a_favor": null, "inventarios": null, "otros_activos_circulantes": 13277, "inversiones_en_acciones_nacionales": null, "inversiones_en_acciones_extranjero": null, "inversiones_en_acciones_total": null, "terrenos": null, "construcciones": null, "construcciones_en_proceso": null, "maquinaria_y_equipo": null, "mobiliario_y_equipo_oficina": null, "equipo_de_computo": null, "equipo_de_transporte": null, "otros_activos_fijos": 12756, "depreciacion_acumulada": -106, "cargos_y_gastos_diferidos": 9319, "amortizacion_acumulada": null, "suma_activo": 761890 }, "pasivo": { "cuentas_documentos_por_pagar_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": 268227, "total": 268227 }, "cuentas_documentos_por_pagar_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "contribuciones_por_pagar": 223490, "anticipos_de_clientes": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "aportaciones_futuros_aumentos_de_capital": null, "otros_pasivos": null, "suma_pasivo": 491717 }, "capital_contable": { "capital_social_proveniente_aportaciones": 10000, "capital_social_proveniente_capitalizacion": null, "reservas": null, "otras_cuentas_capital": null, "aportaciones_futuros_aumentos_de_capital": null, "utilidades_acumuladas": null, "utilidad_del_ejercicio": 298623, "perdidas_acumuladas": -38450, "perdida_del_ejercicio": null, "exceso_en_actualizacion_capital": null, "insuficiencia_en_actualizacion_capital": null, "actualizacion_del_capital_contable": null, "suma_capital_contable": 270173, "suma_pasivo_mas_capital_contable": 761890 } }, "conciliacion_entre_resultado_contable_fiscal": { "utilidad_o_perdida_neta": 298623, "efectos_reexpresion": null, "resultado_posicion_monetaria": null, "utilidad_o_perdida_neta_historica": 298623, "ingresos_fiscales_no_contables": 95, "ajuste_anual_inflacion_acumulable": 95, "anticipos_de_clientes": null, "intereses_moratorios_efectivamente_cobrados": null, "ganancia_en_enajenacion_acciones_por_reembolso_capital": null, "ganancia_en_enajenacion_de_terrenos_y_activo_fijo": null, "inventario_acumulable_del_ejercicio": null, "otros_ingresos_fiscales_no_contables": null, "deducciones_contables_no_fiscales": 117415, "costo_de_ventas_contable": null, "depreciacion_y_amortizacion_contable": 106, "gastos_que_no_reunen_requisitos_fiscales": 4307, "isr_ietu_impac_ptu": 113002, "perdida_contable_enajenacion_de_acciones": null, "perdida_contable_enajenacion_de_activo_fijo": null, "perdida_en_participacion_subsidiaria": null, "intereses_devengados_que_exceden_valor_mercado_y_moratorios_pagados_o_no": 0, "otras_deducciones_contables_no_fiscales": 0, "deducciones_fiscales_no_contables": 0, "ajuste_anual_inflacion_deducible": null, "costo_vendido_fiscal": null, "deduccion_inversiones": null, "estimulo_fiscal_por_deduccion_inmediata_inversiones": null, "donacion_bienes_basicos_subsistencia_humana": 0, "estimulo_fiscal_contratacion_personas_discapacidad_yo_mayores": 0, "deduccion_impuesto_sobre_renta_retenido_personas_discapacidad_yo_mayores": 0, "perdida_fiscal_en_enajenacion_acciones": null, "perdida_fiscal_en_enajenacion_de_terrenos_y_activo_fijo": null, "intereses_moratorios_efectivamente_pagados": null, "otras_deducciones_fiscales_no_contables": null, "ingresos_contables_no_fiscales": null, "intereses_moratorios_devengados_a_favor_cobrados_o_no": null, "anticipos_de_clientes_ejercicios_anteriores": null, "saldos_a_favor_impuestos_y_su_actualizacion": null, "utilidad_contable_enajenacion_de_activo_fijo": null, "utilidad_contable_enajenacion_de_acciones": null, "utilidad_en_participacion_subsidiaria": null, "otros_ingresos_contables_no_fiscales": null, "utilidad_o_perdida_fiscal_antes_de_ptu": 416133 }, "deducciones_autorizadas": { "sueldos_salarios": null, "honorarios_pagados_a_personas_fisicas": null, "regalias_y_asistencia_tecnica": null, "donativos_otorgados": null, "uso_o_goce_temporal_de_bienes_pagados_a_personas_fisicas": null, "fletes_y_acarreos_pagados_a_parsonas_fisicas": null, "contribuciones_pagadas_excepto_isr_ietu_impac_iva_ieps": null, "seguros_fianzas": null, "perdida_por_creditos_incobrables": null, "viaticos_y_gastos_viaje": 59527, "combustible_y_lubricantes": null, "credito_al_salario_no_disminuido_de_contribuciones": null, "aportaciones_sar_infonavit_y_jubilaciones_vejez": null, "aportaciones_para_fondos_de_pensiones_y_jubilaciones": null, "cuotas_imss": null, "consumos_en_restaurantes": 11254, "perdida_por_operaciones_financieras_derivadas": null, "deduccion_por_concepto_de_ayuda_alimentaria_para_trabajadores": null, "monto_total_pagos_que_sean_ingresos_exentos_para_trabajador": null, "monto_deducible_al_47_pagos_son_ingresos_exentos_para_trabajador": null, "monto_deducible_al_53_pagos_son_ingresos_exentos_para_trabajador": null, "uso_o_goce_temporal_de_automoviles_baterias_electricas_o_electricos_con_motor_combustion_o_hidrogeno": null, "otras_deducciones_autorizadas": 424346, "total_deducciones_autorizadas": 495127 }, "cifras_cierre_ejercicio": { "perdidas_fiscales_de_ejercicios_anteriores_pendientes_de_amortizar_actualiazadas": null, "saldo_promedio_anual_de_creditos": 142795, "saldo_promedio_anual_de_deudas": 144765, "coeficiente_de_utilidad_por_aplicar_en_ejercicio_siguiente": 0.4567, "porcentaje_de_participacion_consolidable": null, "isr_causado_en_exceso_del_impac_en_los_3_ejercicios_anteriores_pendientes_aplicar": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_neta_2013_y_anteriores": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_neta_a_partir_2014_y_anteriores": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_reinvertida": null, "saldo_actualizado_de_cuenta_de_capital_de_aportacion": null, "saldo_de_cuenta_de_utilidad_fiscal_neta_por_inversion_en_renovables": null }, "determinacion_del_impuesto_sobre_la_renta": { "determinacion_del_impuesto_sobre_la_renta": { "total_ingresos_acumulables": 911260, "total_deducciones_autorizadas_y_deduccion_inmediata_inversiones": 495126, "deduccion_adicional_por_pago_servicios_personales_en_operacion_maquila": null, "utilidad_o_perdida_fiscal_antes_de_ptu": 416134, "ptu_pagada_en_el_ejercicio": null, "utilidad_fiscal_del_ejercicio": 416134, "perdidas_fiscales_de_ejercicios_anteriores_que_se_aplican_en_ejercicio": 39462, "resultado_fiscal": 376672, "impuesto_causado_en_ejercicio": 113002, "tienes_estimulos_fiscales_a_acreditar": "SIN SELECCIÓN", "impuesto_sobre_la_renta_del_ejercicio": 113002, "pagos_provisionales_efectuados_enterados_a_federacion": null, "impuesto_retenido_al_contribuyente": null, "impuesto_acreditable_pagado_en_extranjero": null, "impuesto_acreditable_por_dividendos_o_utilidades_distribuidos": null, "otras_cantidades_a_cargo": null, "otras_cantidades_a_favor": null, "diferencia_a_cargo": 113002, "isr_a_cargo_del_ejercicio": 113002, "isr_a_favor_del_ejercicio": null }, "impuesto_sobre_ingresos_sujetos_a_regimenes_fiscales_preferentes": null, "datos_informativos_ejercicio": { "monto_aplicado_del_estimulo_fiscal_de_chatarrizacion": 0, "monto_deducible_de_pagos_efectuados_por_uso_o_goce_temporal_automoviles": 0, "impac_recuperado_en_ejercicio_derivado_de_deconsolidacion": 0, "ingresos_obtenidos_por_apoyos_gubernamentales": 0, "gastos_realidados_en_ejercicio_por_proyectos_en_investigacion_desarrollo_tecnologico": 0, "credito_fiscal_autorizado_en_ejercicio_por_proyectos_en_investigacion_desarrollo_tecnologico_pendiente_aplicar": 0, "credito_fiscal_autorizado_en_ejercicio_por_proyectos_de_inversion_en_artes_pendiente_aplicar": 0, "credito_fiscal_autorizado_en_ejercicio_por_inversion_en_proyectos_programas_para_deporte_de_alto_rendimiento_pendiente_aplicar": 0, "saldo_pendiente_aplicar_por_inversion_en_equipos_de_alimentacion_vehiculos_electricos": 0, "credito_fiscal_autorizado_en_ejercicio_a_produccion_distribucion_cinematografica_nacional_pendiente_aplicar": 0 }, "datos_informativos_ejercicios_anteriores_aplicados_en_ejercicio": { "total_estimulo_produccion_y_distribucion_cinematografica_nacional_ejercicios_anteriores_aplicado_en_ejercicio": null, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_inversion_en_proyectos_programas_para_deporte_alto_rendimiento_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_proyectos_investigacion_desarrollo_tecnologico_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_proyectos_inversion_artes_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_a_produccion_distribucion_nacional_pendiente_aplicar": 0 } }, "dividendos_o_utilidades_distribuidos": { "provenientes_de_cuenta_de_utilidad_fisica_neta_cufin_generada_en_2013_y_anteriores": null, "provenientes_de_cuenta_de_utilidad_fisica_neta_cufin_generada_a_partir_de_2014": null, "provenientes_de_cuenta_de_utilidad_fisica_neta_reinvertida_cufinre": null, "no_provenientes_de_cufin_ni_cufinre_en_efectivo": null, "no_provenientes_de_cufin_ni_cufinre_en_acciones": null, "monto_del_impuesto_pagado_no_proveniente_de_cufin_ni_cufinre": null, "monto_del_impuesto_pagado_de_utilidades_provenientes_de_cufinre": null, "provenientes_de_cuenta_de_utilidad_fiscal_neta_por_inversion_en_energia_de_fuentes_renovables_o_sistemas_cogeneracion_electricidad_eficiente": null }, "detalle_pago_r1_isr_personas_morales": { "a_cargo": 113002, "parte_actualizada": null, "recargos": null, "multa_por_correccion": null, "total_contribuciones": 113002, "desea_aplicar_alguna_compensacion_o_estimulo": "NO", "cantidad_a_cargo": 113002, "opta_por_pagar_parcialidades": "SIN SELECCIÓN", "importe_de_primera_parcialidad": null, "importe_sin_primera_parcialidad": null, "cantidad_a_favor": null, "cantidad_a_pagar": 113002 }, "pdf": "=PDF-STRING=", "receipt_pdf": "=PDF-STRING=" } ] }, "TaxReturnBusinessListMonthly": { "summary": "Business Monthly", "description": "Example of a monthly business tax return", "value": [ { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": "DPA950805RR2", "denominacion_razon_social": "Aloha Mahalo SC", "tipo_declaracion": "Normal", "ejercicio": 2020, "periodo_declaracion": "Diciembre", "fecha_hora_presentacion": "2021-01-18T19:24:00-06:00", "numero_operacion": "400475119", "tipo_complementaria": null }, "determinacion_isr": { "personas_morales_regimen_general": { "suma_ingresos_nominales_meses_anteriores_ejercicio": 69848414, "estimulos_acreditables": null, "ingresos_nominales_mes_que_declara": 6482479, "reducciones": null, "total_ingresos_nominales": 76330893, "impuestos_del_periodo": 284098, "coeficiente_utilidad": 0.2318, "pagos_provisionales_efectuados_anterioridad": 303039, "utilidad_fiscal_pago_provisional": 17693501, "impuesto_retenido": 29925, "ptu": null, "otras_cantidades_a_cargo_contribuyente": null, "iventario_acumulable": null, "otras_cantidades_a_favor_contribuyente": null, "anticipos_rendimientos_distribuidos_periodo": 16746509, "diferencia_a_cargo": 0, "perdidas_fiscales_ejercicios_anteriores_pendientes": null, "estimulo_fiscal_deduccion_inmediata": null, "impuesto_correspondiente_participacion_consolidable": null, "deduccion_adicional_fomento_primer_empleo": null, "porcentaje_participacion_consolidable": null, "base_gravable_pago_provisional": 946992, "impuesto_a_cargo": 0, "isr_causado": 284098, "ieps_alcohol": null } }, "detalle_pago_isr": { "r1_isr_personas_morales": { "a_cargo": 0, "acreditamiento_sorteo_buen_fin": null, "parte_actualizada": null, "diesel_marino": null, "recargos": null, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 0, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 0, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "uso_infraestructura_carretera_cuota": null, "cantidad_a_pagar": 0, "otros_estimulos": null, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r12_isr_retenciones_por_salarios": { "a_cargo": 415945, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 379, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 415945, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": 379, "cantidad_a_cargo": 415566, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 415566, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r13_isr_retenciones_por_asimilados_a_salarios": { "a_cargo": 254588, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 254588, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 254588, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 254588, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r14_isr_retenciones_por_servicios_profesionales": { "a_cargo": 104482, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 104482, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 104482, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 104482, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null } }, "determinacion_iva": { "montos_actos_actividades_pagados": { "total_actos_actividades_pagados_tasa_16": 2094706, "total_actos_actividades_pagados_importacion_bienes_tasa_11": null, "total_actos_actividades_sujetos_estimulo_rfn": 0, "total_actos_actividades_pagados_tasa_0": 0, "total_actos_actividades_pagados_importacion_bienes_tasa_16": null, "total_actos_actividades_pagados_no_paga_iva": 0 }, "detalle_total_actos_actividades_pagados_tasa_16": { "intereses_pagados_tasa_16": null, "otros_actos_pagados_tasa_16": 2094706, "regalias_pagadas_tasa_16": null, "total_actos_pagados_tasa_16": 2094706 }, "determinacion_iva_acreditable": { "total_iva_actos_actividades_pagados_tasa_16": 335153, "iva_trasladado_o_pagado_adquisicion_bienes_distintos_inversiones_actos_no_obligados_pago_impuesto": null, "iva_pagado_sujeto_estimulo_rfn": null, "iva_trasladado_o_pagado_importacion_inversiones_actos_no_obligados_pago_impuesto": null, "total_actos_actividades_pagados_importacion_bienes_tasa_16": 0, "iva_bienes_utilizados_indistintamente_actos_gravados_o_actos_no_obligados_pago_impuesto": 0, "proporcion_utilizada_conforme_art_5": null, "total_iva_trasladado_contribuyente": 335153, "proporcion_utilizada_conforme_art_5_b": null, "iva_trasladado_adquisicion_bienes_distintos_inversiones_actos_gravados": 335153, "iva_pagado_importacion_adquisicion_bienes_distintos_inversiones_actos_gravados": null, "iva_acreditable": 335153, "monto_acreditable_actualizado_a_incrementar_derivado_ajuste": null, "iva_pagado_importacion_inversiones_actos_gravados": null, "total_iva_acreditable_periodo": 335153, "total_iva_actos_actividades_gravados": 335153, "total_actos_actividades_pagados_importacion_bienes_tasa_11": null, "iva_trasladado_adquisicion_inversiones_actos_gravados": null, "iva_acreditable_bienes_utilizados_indistintamente_actos_gravados_o_actos_no_obligados_pago_impuesto": null }, "determinacion_iva": { "valor_actos_actividades_gravados_tasa_16": 6457950, "otras_cantidades_a_favor_contribuyente": null, "valor_actos_actividades_gravados_tasa_11": null, "cantidad_a_cargo": 312421, "valor_actos_actividades_gravados_tasa_0_exportacion": null, "saldo_a_favor": null, "valor_actos_actividades_gravados_tasa_9_otros": null, "devolucion_inmediata_obtenida": null, "suma_actos_actividades_gravados": 6457950, "saldo_a_favor_periodo": 0, "valor_actos_actividades_no_se_deba_pagar_impuesto_exentos": null, "acreditamiento_saldo_favor_periodos_anteriores": null, "impuesto_causado": 1033272, "diferencia_a_cargo": 312421, "cantidad_actualizada_a_reintegrarse_derivada_de_ajuste": null, "ieps_acreditable_alcohol": null, "iva_retenido_al_contribuyente": 385698, "impuesto_a_cargo": 312421, "total_iva_acreditable": 335153, "remanente_saldo_favor_ieps_alcohol": null, "otras_cantidades_a_cargo_contribuyente": null }, "detalle_valor_actos_actividades_gravados_tasa_16": { "intereses_cobrados_tasa_16": null, "otros_actos_actividades_gravados_tasa_16": 6457950, "regalias_entre_partes_relacionadas_tasa_16": null, "total_actos_actividades_gravados_tasa_16": 6457950 } }, "detalle_pago_iva": { "r21_iva": { "a_cargo": 312421, "cretificados_tesofe": null, "a_favor": null, "diesel_marino": null, "parte_actualizada": 0, "total_aplicaciones": 0, "recargos": 0, "fecha_pago_realizado_anterioridad": null, "multa_por_correccion": null, "monto_pagado_anterioridad": null, "total_de_contribuciones": 312421, "importe_pagado_ultimas_48_hrs": null, "credito_al_salario": null, "cantidad_a_cargo": 312421, "subsidio_empleo": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "diesel_automotriz_transporte": null, "uso_infraestructura_carretera_cuota": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 312421, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r21_iva_retenciones": { "a_cargo": 111448, "diesel_marino": null, "parte_actualizada": 0, "total_aplicaciones": 0, "recargos": 0, "fecha_pago_realizado_anterioridad": null, "multa_por_correccion": null, "monto_pagado_anterioridad": null, "total_de_contribuciones": 111448, "importe_pagado_ultimas_48_hrs": null, "credito_al_salario": null, "cantidad_a_cargo": 111448, "subsidio_empleo": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "otros_estimulos": null, "cantidad_a_favor": null, "cretificados_tesofe": null, "cantidad_a_pagar": 111448, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } ] }, "TaxReturnPersonalListDetail": { "summary": "Tax Return Personal", "description": "Example of a list of personal tax returns", "value": { "id": "02589c41-ba22-4d44-8558-8111cc751318", "link": "19697249-01b8-443e-a451-76bfc5fbeebf", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "ejercicio": 2018, "fecha_hora_presentacion": "2020-01-07T17:28:00-05:00", "numero_operacion": "00000000001", "periodo_declaracion": "Del Ejercicio", "rfc": "ABCD111111A11", "tipo_declaracion": "Normal", "nombre": "JOHN DOE" }, "sueldos_salarios": { "retenedores": [ { "rfc_retenedor": "ABCD222222A22", "nombre_denominacion_razon_social": "ACME CORP", "ingresos_exentos": 118263, "ingreso_anual": 2265, "subsidio_empleo": 0 } ], "impuesto_retenido": 19497, "ingreso_anual": 118263, "ingresos_acumulables": 115998, "ingresos_exentos": 2265, "subsidio_empleo": 0 }, "servicios_profesionales": { "deducciones_autorizadas": { "deducciones_autorizadas": 11870, "otras_deducciones": null, "detalle_deducciones": [ { "tipo_deduccion": "GASTOS", "concepto": "GASOLINA Y MANTENIMIENTO DE TRANSPORTE", "monto_detallado": 9682 }, { "tipo_deduccion": "GASTOS", "concepto": "COMPRAS Y GASTOS GENERALES", "monto_detallado": 2188 } ], "total_deducciones_autorizadas": 11870 }, "ingresos": { "ingresos_acumulables": 46000, "ingresos_exentos": null, "otros_ingresos": null, "total_ingresos": 46000 }, "resultado_fiscal": { "utilidad_fiscal": 34130, "ptu_pagada_ejercicio": 0, "perdidas_fiscales_ejercicios_anteriores_aplicadas": 0, "utilidad_gravable": 34130 }, "pagos_provisionales": { "pagos_provisionales_efectuados_en_ejercicio": 0 }, "retenciones_isr": { "isr_retenido_personas_morales": 4600 } }, "deducciones_personales": { "honorarios_medicos_dentales_hospitalarios": [ { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A44", "monto_deducible": 1000 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A44", "monto_deducible": 502.34 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC333333A33", "monto_deducible": 258.83 }, { "rfc_emisor": "ABC444444A55", "monto_deducible": 14183.1 }, { "rfc_emisor": "ABC444444A66", "monto_deducible": 1658 }, { "rfc_emisor": "ABC444444A77", "monto_deducible": 1600 }, { "rfc_emisor": "ABC444444A88", "monto_deducible": 1064 }, { "rfc_emisor": "ABC444444A99", "monto_deducible": 927.57 } ], "donativos": [ { "rfc_emisor": "ABC555555A99", "monto_deducible": 10.03 } ], "aportaciones_voluntarias_complementarias_al_sar": [ { "rfc_emisor": "ABC666666A99", "monto_deducible": 12.03 }, { "rfc_emisor": "ABC777777A99", "monto_deducible": 87.22 } ], "primas_por_seguros_de_gasto_medico": [ { "rfc_emisor": "ABC777777A99", "monto_deducible": 20.03 } ] }, "determinacion_impuesto": { "base_gravable": 126864, "deducciones_personales": 23264, "ingresos_acumulables": 150128, "isr_favorable": 10308, "isr_conforme_tarifa_final": 13789, "isr_retenido": 24097, "num_clabe": "000000000000000001", "nombre_banco": "BANCO SA", "pagos_provisionales": 0, "titular_clabe_permite_verificacion": "SÍ", "accion_saldo_a_favor": "DEVOLUCIÓN" }, "retenciones": { "sueldos_salarios": [ { "rfc_retenedor": "ABC444444A99", "monto_retenciones": 118263, "retenciones_isr": 19497 } ], "dividendos": [], "servicios_profesionales": [ { "rfc_retenedor": "ABC444444A00", "monto_retenciones": 46000, "retenciones_isr": 4600 } ] }, "dividendos": { "monto_acumulable_dividendos_utilidades": null, "monto_total_isr_pagado_sociedad": null }, "datos_informativos": { "credito_fiscal_autorizado_proyectos_investigacion_desarrollo": 0, "credito_fiscal_autorizado_proyectos_apoyo_deporte_alto_rendimiento": 0, "credito_fiscal_autorizado_proyectos_inversion_artes": 0, "credito_fiscal_autorizado_inversion_equipos_fijos": 0, "credito_fiscal_autorizado_produccion_distribucion_cinematografica": 0, "saldo_credito_fiscal_autorizado_anteriores_investigacion_desarrollo": 0, "saldo_credito_fiscal_anteriores_proyectos_inversion_artes": 0, "saldo_credito_fiscal_anteriores_produccion_distribucion_cinematografica": 0 }, "pdf": "=PDF-STRING=", "receipt_pdf": "=PDF-STRING=" } }, "TaxReturnPersonalListMonthlyPFAEDetail": { "summary": "Tax Return Personal Monthly (PFAE)", "description": "Example of a PFAE-type monthly personal tax return", "value": { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": null, "nombre": null, "tipo_declaracion": null, "ejercicio": null, "periodo_declaracion": null, "fecha_hora_presentacion": null, "numero_operacion": null }, "isr": { "tipo": "PFAE", "determinacion": { "ingresos_periodos_anteriores": 0, "ingresos_periodo": 0, "total_ingresos": 0, "compras_gastos_periodos_anteriores": 1596, "compra_gastos_periodo": 399, "total_compras_gastos": 1995, "base_gravable_pago_provisional": 0, "isr_causado": 0, "pagos_provisionales_efectuados_anterioridad": 0, "isr_retenido_periodos_anteriores": 0, "impuesto_retenido": 0, "isr_cargo": 0 }, "detalle_del_pago": { "a_cargo": 0, "parte_actualizada": 0, "recargos": 0, "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0 } }, "iva": { "determinacion": { "actividades_gravadas_tasa_16": 0, "actividades_gravadas_tasa_0": 0, "actividades_exentas": 0, "iva_cobrado_periodo_tasa_16": 0, "iva_acreditable_periodo": 0, "iva_retenido": 0, "saldo_a_favor": null, "impuesto_a_favor": null }, "detalle_del_pago": { "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0, "a_favor": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } }, "TaxReturnPersonalListMonthlyPFAIDetail": { "summary": "Tax Return Personal Monthly (PFAI)", "description": "Example of a PFAI-type monthly personal tax return", "value": { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": null, "nombre": null, "tipo_declaracion": null, "ejercicio": null, "periodo_declaracion": null, "fecha_hora_presentacion": null, "numero_operacion": null }, "isr": { "tipo": "PFAE", "determinacion": { "ingresos_periodos_anteriores": 0, "ingresos_periodo": 0, "total_ingresos": 0, "compras_gastos_periodos_anteriores": 1596, "compra_gastos_periodo": 399, "total_compras_gastos": 1995, "base_gravable_pago_provisional": 0, "isr_causado": 0, "pagos_provisionales_efectuados_anterioridad": 0, "isr_retenido_periodos_anteriores": 0, "impuesto_retenido": 0, "isr_cargo": 0, "tipo_de_deduccíon": "dedduccíon opicional", "optas_por_el_cálculo_acumulado": "NO", "deduccíon_opcional": 700, "impuesto_predial": 0, "total_deducciones_autorizadas": 700, "tienes_facilidades_administrativas_o_estímulos_deducibles": "NO" }, "detalle_del_pago": { "a_cargo": 0, "parte_actualizada": 0, "recargos": 0, "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0 } }, "iva": { "determinacion": { "actividades_gravadas_tasa_16": 0, "actividades_gravadas_tasa_0": 0, "actividades_exentas": 0, "iva_cobrado_periodo_tasa_16": 0, "iva_acreditable_periodo": 0, "iva_retenido": 0, "saldo_a_favor": null, "impuesto_a_favor": null, "impuesto_a_cargo": 54, "cantidad_a_cargo": 54 }, "detalle_del_pago": { "total_contribuciones": 0, "total_aplicaciones": 0, "cantidad_a_cargo": 0, "cantidad_a_pagar": 0, "a_favor": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } }, "TaxReturnBusinessListDetail": { "summary": "Tax Return Business", "description": "Example of a list of business tax returns", "value": { "id": "02589c41-ba22-4d44-8558-8111cc751318", "link": "19697249-01b8-443e-a451-76bfc5fbeebf", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "ejercicio": 2018, "fecha_hora_presentacion": "2020-01-07T16:55:00-06:00", "numero_operacion": "000000000001", "periodo_declaracion": "Del Ejercicio", "rfc": "ABC1111111A1", "tipo_declaracion": "Normal", "tipo_complementaria": null, "denominacion_razon_social": "ACME CORP" }, "datos_adicionales": { "indica_si_optas_por_dictaminar_tus_estados_financieros": "NO", "estas_obligado_a_presentar_la_informacion_sobre_tu_situacion_fiscal": "NO", "estas_obligado_unicamente_por_supuesto_distinto_al_de_haber_realizado_operaciones_con_residentes_extranjero": "SIN SELECCIÓN", "estas_obligado_unicamente_por_supuesto_distinto_al_de_haber_realizado_operaciones_con_residentes_extranjero_inferiores_100mdp": "SIN SELECCIÓN", "optas_por_presentar_informacion_sobre_tu_situacion_fiscal": "SIN SELECCIÓN", "indica_si_te_dedicas_exclisivamente_a_generacion_energia_fuentes_renovables_o_cogeneracion_electricidad_eficiente": "NO" }, "estado_resultados": { "ventas_servicios_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": 911165, "total": 911165 }, "ventas_servicios_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "devoluciones_descuentos_bonificaciones_ventas_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "devoluciones_descuentos_bonificaciones_ventas_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "ingresos_netos": { "partes_relacionadas": null, "partes_no_relacionadas": 911165, "total": 911165 }, "inventario_inicial": null, "compras_netas_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "compras_netas_importacion": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "inventario_final": null, "costo_mercancias": null, "mano_de_obra": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "maquilas": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "gastos_indirectos_fabricacion": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "costo_ventas_servicios": null, "utilidad_bruta": 911165, "perdida_bruta": null, "gastos_operacion": { "partes_relacionadas": null, "partes_no_relacionadas": 499540, "total": 499540 }, "utilidad_operacion": 411625, "perdida_operacion": null, "intereses_devengados_a_favor_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_favor_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_favor_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_favor_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "ganancia_cambiaria": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_cargo_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_devengados_a_cargo_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_cargo_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "intereses_moratorios_a_cargo_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "perdida_cambiaria": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "resultado_posicion_monetaria_favorable": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "resultado_posicion_monetaria_desfavorable": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "otras_operaciones_financieras": null, "resultado_integral_financiamiento": null, "otros_gastos_nacionales": null, "otros_gastos_extranjero": null, "otros_gastos": null, "otros_productos_nacionales": null, "otros_productos_extranjero": null, "otros_productos": null, "ingresos_partidas_discontinuas_extraordinarias": null, "gastos_partidas_discontinuas_extraordinarias": null, "utilidad_antes_impuesto": 411625, "perdida_antes_impuesto": null, "isr": 113002, "ietu": null, "impac": null, "ptu": null, "utilidad_participacion_subsidiaria": null, "perdida_participacion_subsidiaria": null, "efectos_reexpresion_favorables_excepto_resultado_posicion_monetaria": null, "efectos_reexpresion_desfavorables_excepto_resultado_posicion_monetaria": null, "utilidad_neta": 298623, "perdida_neta": null }, "estado_posicion_financiera_balance": { "activo": { "efectivo_caja_depositos_instituciones_credito_nacionales": 726644, "efectivo_caja_depositos_instituciones_credito_extranjero": null, "inversiones_valores_instituciones_nacionales_excepto_acciones": null, "inversiones_valores_instituciones_extranjero_excepto_acciones": null, "cuentas_documentos_por_cobrar_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "cuentas_documentos_por_cobrar_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "contribuciones_a_favor": null, "inventarios": null, "otros_activos_circulantes": 13277, "inversiones_en_acciones_nacionales": null, "inversiones_en_acciones_extranjero": null, "inversiones_en_acciones_total": null, "terrenos": null, "construcciones": null, "construcciones_en_proceso": null, "maquinaria_y_equipo": null, "mobiliario_y_equipo_oficina": null, "equipo_de_computo": null, "equipo_de_transporte": null, "otros_activos_fijos": 12756, "depreciacion_acumulada": -106, "cargos_y_gastos_diferidos": 9319, "amortizacion_acumulada": null, "suma_activo": 761890 }, "pasivo": { "cuentas_documentos_por_pagar_nacionales": { "partes_relacionadas": null, "partes_no_relacionadas": 268227, "total": 268227 }, "cuentas_documentos_por_pagar_extranjero": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "contribuciones_por_pagar": 223490, "anticipos_de_clientes": { "partes_relacionadas": null, "partes_no_relacionadas": null, "total": null }, "aportaciones_futuros_aumentos_de_capital": null, "otros_pasivos": null, "suma_pasivo": 491717 }, "capital_contable": { "capital_social_proveniente_aportaciones": 10000, "capital_social_proveniente_capitalizacion": null, "reservas": null, "otras_cuentas_capital": null, "aportaciones_futuros_aumentos_de_capital": null, "utilidades_acumuladas": null, "utilidad_del_ejercicio": 298623, "perdidas_acumuladas": -38450, "perdida_del_ejercicio": null, "exceso_en_actualizacion_capital": null, "insuficiencia_en_actualizacion_capital": null, "actualizacion_del_capital_contable": null, "suma_capital_contable": 270173, "suma_pasivo_mas_capital_contable": 761890 } }, "conciliacion_entre_resultado_contable_fiscal": { "utilidad_o_perdida_neta": 298623, "efectos_reexpresion": null, "resultado_posicion_monetaria": null, "utilidad_o_perdida_neta_historica": 298623, "ingresos_fiscales_no_contables": 95, "ajuste_anual_inflacion_acumulable": 95, "anticipos_de_clientes": null, "intereses_moratorios_efectivamente_cobrados": null, "ganancia_en_enajenacion_acciones_por_reembolso_capital": null, "ganancia_en_enajenacion_de_terrenos_y_activo_fijo": null, "inventario_acumulable_del_ejercicio": null, "otros_ingresos_fiscales_no_contables": null, "deducciones_contables_no_fiscales": 117415, "costo_de_ventas_contable": null, "depreciacion_y_amortizacion_contable": 106, "gastos_que_no_reunen_requisitos_fiscales": 4307, "isr_ietu_impac_ptu": 113002, "perdida_contable_enajenacion_de_acciones": null, "perdida_contable_enajenacion_de_activo_fijo": null, "perdida_en_participacion_subsidiaria": null, "intereses_devengados_que_exceden_valor_mercado_y_moratorios_pagados_o_no": 0, "otras_deducciones_contables_no_fiscales": 0, "deducciones_fiscales_no_contables": 0, "ajuste_anual_inflacion_deducible": null, "costo_vendido_fiscal": null, "deduccion_inversiones": null, "estimulo_fiscal_por_deduccion_inmediata_inversiones": null, "donacion_bienes_basicos_subsistencia_humana": 0, "estimulo_fiscal_contratacion_personas_discapacidad_yo_mayores": 0, "deduccion_impuesto_sobre_renta_retenido_personas_discapacidad_yo_mayores": 0, "perdida_fiscal_en_enajenacion_acciones": null, "perdida_fiscal_en_enajenacion_de_terrenos_y_activo_fijo": null, "intereses_moratorios_efectivamente_pagados": null, "otras_deducciones_fiscales_no_contables": null, "ingresos_contables_no_fiscales": null, "intereses_moratorios_devengados_a_favor_cobrados_o_no": null, "anticipos_de_clientes_ejercicios_anteriores": null, "saldos_a_favor_impuestos_y_su_actualizacion": null, "utilidad_contable_enajenacion_de_activo_fijo": null, "utilidad_contable_enajenacion_de_acciones": null, "utilidad_en_participacion_subsidiaria": null, "otros_ingresos_contables_no_fiscales": null, "utilidad_o_perdida_fiscal_antes_de_ptu": 416133 }, "deducciones_autorizadas": { "sueldos_salarios": null, "honorarios_pagados_a_personas_fisicas": null, "regalias_y_asistencia_tecnica": null, "donativos_otorgados": null, "uso_o_goce_temporal_de_bienes_pagados_a_personas_fisicas": null, "fletes_y_acarreos_pagados_a_parsonas_fisicas": null, "contribuciones_pagadas_excepto_isr_ietu_impac_iva_ieps": null, "seguros_fianzas": null, "perdida_por_creditos_incobrables": null, "viaticos_y_gastos_viaje": 59527, "combustible_y_lubricantes": null, "credito_al_salario_no_disminuido_de_contribuciones": null, "aportaciones_sar_infonavit_y_jubilaciones_vejez": null, "aportaciones_para_fondos_de_pensiones_y_jubilaciones": null, "cuotas_imss": null, "consumos_en_restaurantes": 11254, "perdida_por_operaciones_financieras_derivadas": null, "deduccion_por_concepto_de_ayuda_alimentaria_para_trabajadores": null, "monto_total_pagos_que_sean_ingresos_exentos_para_trabajador": null, "monto_deducible_al_47_pagos_son_ingresos_exentos_para_trabajador": null, "monto_deducible_al_53_pagos_son_ingresos_exentos_para_trabajador": null, "uso_o_goce_temporal_de_automoviles_baterias_electricas_o_electricos_con_motor_combustion_o_hidrogeno": null, "otras_deducciones_autorizadas": 424346, "total_deducciones_autorizadas": 495127 }, "cifras_cierre_ejercicio": { "perdidas_fiscales_de_ejercicios_anteriores_pendientes_de_amortizar_actualiazadas": null, "saldo_promedio_anual_de_creditos": 142795, "saldo_promedio_anual_de_deudas": 144765, "coeficiente_de_utilidad_por_aplicar_en_ejercicio_siguiente": 0.4567, "porcentaje_de_participacion_consolidable": null, "isr_causado_en_exceso_del_impac_en_los_3_ejercicios_anteriores_pendientes_aplicar": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_neta_2013_y_anteriores": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_neta_a_partir_2014_y_anteriores": null, "saldo_actualizado_de_cuenta_de_utilidad_fiscal_reinvertida": null, "saldo_actualizado_de_cuenta_de_capital_de_aportacion": null, "saldo_de_cuenta_de_utilidad_fiscal_neta_por_inversion_en_renovables": null }, "determinacion_del_impuesto_sobre_la_renta": { "determinacion_del_impuesto_sobre_la_renta": { "total_ingresos_acumulables": 911260, "total_deducciones_autorizadas_y_deduccion_inmediata_inversiones": 495126, "deduccion_adicional_por_pago_servicios_personales_en_operacion_maquila": null, "utilidad_o_perdida_fiscal_antes_de_ptu": 416134, "ptu_pagada_en_el_ejercicio": null, "utilidad_fiscal_del_ejercicio": 416134, "perdidas_fiscales_de_ejercicios_anteriores_que_se_aplican_en_ejercicio": 39462, "resultado_fiscal": 376672, "impuesto_causado_en_ejercicio": 113002, "tienes_estimulos_fiscales_a_acreditar": "SIN SELECCIÓN", "impuesto_sobre_la_renta_del_ejercicio": 113002, "pagos_provisionales_efectuados_enterados_a_federacion": null, "impuesto_retenido_al_contribuyente": null, "impuesto_acreditable_pagado_en_extranjero": null, "impuesto_acreditable_por_dividendos_o_utilidades_distribuidos": null, "otras_cantidades_a_cargo": null, "otras_cantidades_a_favor": null, "diferencia_a_cargo": 113002, "isr_a_cargo_del_ejercicio": 113002, "isr_a_favor_del_ejercicio": null }, "impuesto_sobre_ingresos_sujetos_a_regimenes_fiscales_preferentes": null, "datos_informativos_ejercicio": { "monto_aplicado_del_estimulo_fiscal_de_chatarrizacion": 0, "monto_deducible_de_pagos_efectuados_por_uso_o_goce_temporal_automoviles": 0, "impac_recuperado_en_ejercicio_derivado_de_deconsolidacion": 0, "ingresos_obtenidos_por_apoyos_gubernamentales": 0, "gastos_realidados_en_ejercicio_por_proyectos_en_investigacion_desarrollo_tecnologico": 0, "credito_fiscal_autorizado_en_ejercicio_por_proyectos_en_investigacion_desarrollo_tecnologico_pendiente_aplicar": 0, "credito_fiscal_autorizado_en_ejercicio_por_proyectos_de_inversion_en_artes_pendiente_aplicar": 0, "credito_fiscal_autorizado_en_ejercicio_por_inversion_en_proyectos_programas_para_deporte_de_alto_rendimiento_pendiente_aplicar": 0, "saldo_pendiente_aplicar_por_inversion_en_equipos_de_alimentacion_vehiculos_electricos": 0, "credito_fiscal_autorizado_en_ejercicio_a_produccion_distribucion_cinematografica_nacional_pendiente_aplicar": 0 }, "datos_informativos_ejercicios_anteriores_aplicados_en_ejercicio": { "total_estimulo_produccion_y_distribucion_cinematografica_nacional_ejercicios_anteriores_aplicado_en_ejercicio": null, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_inversion_en_proyectos_programas_para_deporte_alto_rendimiento_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_proyectos_investigacion_desarrollo_tecnologico_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_por_proyectos_inversion_artes_pendiente_aplicar": 0, "saldo_credito_fiscal_autorizado_ejercicios_anteriores_a_produccion_distribucion_nacional_pendiente_aplicar": 0 } }, "dividendos_o_utilidades_distribuidos": { "provenientes_de_cuenta_de_utilidad_fisica_neta_cufin_generada_en_2013_y_anteriores": null, "provenientes_de_cuenta_de_utilidad_fisica_neta_cufin_generada_a_partir_de_2014": null, "provenientes_de_cuenta_de_utilidad_fisica_neta_reinvertida_cufinre": null, "no_provenientes_de_cufin_ni_cufinre_en_efectivo": null, "no_provenientes_de_cufin_ni_cufinre_en_acciones": null, "monto_del_impuesto_pagado_no_proveniente_de_cufin_ni_cufinre": null, "monto_del_impuesto_pagado_de_utilidades_provenientes_de_cufinre": null, "provenientes_de_cuenta_de_utilidad_fiscal_neta_por_inversion_en_energia_de_fuentes_renovables_o_sistemas_cogeneracion_electricidad_eficiente": null }, "detalle_pago_r1_isr_personas_morales": { "a_cargo": 113002, "parte_actualizada": null, "recargos": null, "multa_por_correccion": null, "total_contribuciones": 113002, "desea_aplicar_alguna_compensacion_o_estimulo": "NO", "cantidad_a_cargo": 113002, "opta_por_pagar_parcialidades": "SIN SELECCIÓN", "importe_de_primera_parcialidad": null, "importe_sin_primera_parcialidad": null, "cantidad_a_favor": null, "cantidad_a_pagar": 113002 }, "pdf": "=PDF-STRING=", "receipt_pdf": "=PDF-STRING=" } }, "TaxReturnBusinessListMonthlyDetail": { "summary": "Tax Return Business Monthly", "description": "Example of a monthly business tax return", "value": { "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "informacion_general": { "rfc": "DPA950805RR2", "denominacion_razon_social": "Aloha Mahalo SC", "tipo_declaracion": "Normal", "ejercicio": 2020, "periodo_declaracion": "Diciembre", "fecha_hora_presentacion": "2021-01-18T19:24:00-06:00", "numero_operacion": "400475119", "tipo_complementaria": null }, "determinacion_isr": { "personas_morales_regimen_general": { "suma_ingresos_nominales_meses_anteriores_ejercicio": 69848414, "estimulos_acreditables": null, "ingresos_nominales_mes_que_declara": 6482479, "reducciones": null, "total_ingresos_nominales": 76330893, "impuestos_del_periodo": 284098, "coeficiente_utilidad": 0.2318, "pagos_provisionales_efectuados_anterioridad": 303039, "utilidad_fiscal_pago_provisional": 17693501, "impuesto_retenido": 29925, "ptu": null, "otras_cantidades_a_cargo_contribuyente": null, "iventario_acumulable": null, "otras_cantidades_a_favor_contribuyente": null, "anticipos_rendimientos_distribuidos_periodo": 16746509, "diferencia_a_cargo": 0, "perdidas_fiscales_ejercicios_anteriores_pendientes": null, "estimulo_fiscal_deduccion_inmediata": null, "impuesto_correspondiente_participacion_consolidable": null, "deduccion_adicional_fomento_primer_empleo": null, "porcentaje_participacion_consolidable": null, "base_gravable_pago_provisional": 946992, "impuesto_a_cargo": 0, "isr_causado": 284098, "ieps_alcohol": null } }, "detalle_pago_isr": { "r1_isr_personas_morales": { "a_cargo": 0, "acreditamiento_sorteo_buen_fin": null, "parte_actualizada": null, "diesel_marino": null, "recargos": null, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 0, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 0, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "uso_infraestructura_carretera_cuota": null, "cantidad_a_pagar": 0, "otros_estimulos": null, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r12_isr_retenciones_por_salarios": { "a_cargo": 415945, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 379, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 415945, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": 379, "cantidad_a_cargo": 415566, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 415566, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r13_isr_retenciones_por_asimilados_a_salarios": { "a_cargo": 254588, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 254588, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 254588, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 254588, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r14_isr_retenciones_por_servicios_profesionales": { "a_cargo": 104482, "acreditamiento_sorteos": null, "parte_actualizada": 0, "diesel_marino": null, "recargos": 0, "total_aplicaciones": 0, "multa_por_correccion": null, "fecha_pago_realizado_anterioridad": null, "total_de_contribuciones": 104482, "monto_pagado_anterioridad": null, "credito_al_salario": null, "importe_pagado_ultimas_48_hrs": null, "subsidio_empleo": null, "cantidad_a_cargo": 104482, "impuesto_a_depositos_efectivo_acreditable": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "diesel_automotriz_transporte": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 104482, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null } }, "determinacion_iva": { "montos_actos_actividades_pagados": { "total_actos_actividades_pagados_tasa_16": 2094706, "total_actos_actividades_pagados_importacion_bienes_tasa_11": null, "total_actos_actividades_sujetos_estimulo_rfn": 0, "total_actos_actividades_pagados_tasa_0": 0, "total_actos_actividades_pagados_importacion_bienes_tasa_16": null, "total_actos_actividades_pagados_no_paga_iva": 0 }, "detalle_total_actos_actividades_pagados_tasa_16": { "intereses_pagados_tasa_16": null, "otros_actos_pagados_tasa_16": 2094706, "regalias_pagadas_tasa_16": null, "total_actos_pagados_tasa_16": 2094706 }, "determinacion_iva_acreditable": { "total_iva_actos_actividades_pagados_tasa_16": 335153, "iva_trasladado_o_pagado_adquisicion_bienes_distintos_inversiones_actos_no_obligados_pago_impuesto": null, "iva_pagado_sujeto_estimulo_rfn": null, "iva_trasladado_o_pagado_importacion_inversiones_actos_no_obligados_pago_impuesto": null, "total_actos_actividades_pagados_importacion_bienes_tasa_16": 0, "iva_bienes_utilizados_indistintamente_actos_gravados_o_actos_no_obligados_pago_impuesto": 0, "proporcion_utilizada_conforme_art_5": null, "total_iva_trasladado_contribuyente": 335153, "proporcion_utilizada_conforme_art_5_b": null, "iva_trasladado_adquisicion_bienes_distintos_inversiones_actos_gravados": 335153, "iva_pagado_importacion_adquisicion_bienes_distintos_inversiones_actos_gravados": null, "iva_acreditable": 335153, "monto_acreditable_actualizado_a_incrementar_derivado_ajuste": null, "iva_pagado_importacion_inversiones_actos_gravados": null, "total_iva_acreditable_periodo": 335153, "total_iva_actos_actividades_gravados": 335153, "total_actos_actividades_pagados_importacion_bienes_tasa_11": null, "iva_trasladado_adquisicion_inversiones_actos_gravados": null, "iva_acreditable_bienes_utilizados_indistintamente_actos_gravados_o_actos_no_obligados_pago_impuesto": null }, "determinacion_iva": { "valor_actos_actividades_gravados_tasa_16": 6457950, "otras_cantidades_a_favor_contribuyente": null, "valor_actos_actividades_gravados_tasa_11": null, "cantidad_a_cargo": 312421, "valor_actos_actividades_gravados_tasa_0_exportacion": null, "saldo_a_favor": null, "valor_actos_actividades_gravados_tasa_9_otros": null, "devolucion_inmediata_obtenida": null, "suma_actos_actividades_gravados": 6457950, "saldo_a_favor_periodo": 0, "valor_actos_actividades_no_se_deba_pagar_impuesto_exentos": null, "acreditamiento_saldo_favor_periodos_anteriores": null, "impuesto_causado": 1033272, "diferencia_a_cargo": 312421, "cantidad_actualizada_a_reintegrarse_derivada_de_ajuste": null, "ieps_acreditable_alcohol": null, "iva_retenido_al_contribuyente": 385698, "impuesto_a_cargo": 312421, "total_iva_acreditable": 335153, "remanente_saldo_favor_ieps_alcohol": null, "otras_cantidades_a_cargo_contribuyente": null }, "detalle_valor_actos_actividades_gravados_tasa_16": { "intereses_cobrados_tasa_16": null, "otros_actos_actividades_gravados_tasa_16": 6457950, "regalias_entre_partes_relacionadas_tasa_16": null, "total_actos_actividades_gravados_tasa_16": 6457950 } }, "detalle_pago_iva": { "r21_iva": { "a_cargo": 312421, "cretificados_tesofe": null, "a_favor": null, "diesel_marino": null, "parte_actualizada": 0, "total_aplicaciones": 0, "recargos": 0, "fecha_pago_realizado_anterioridad": null, "multa_por_correccion": null, "monto_pagado_anterioridad": null, "total_de_contribuciones": 312421, "importe_pagado_ultimas_48_hrs": null, "credito_al_salario": null, "cantidad_a_cargo": 312421, "subsidio_empleo": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "diesel_automotriz_transporte": null, "uso_infraestructura_carretera_cuota": null, "cantidad_a_favor": null, "otros_estimulos": null, "cantidad_a_pagar": 312421, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null }, "r21_iva_retenciones": { "a_cargo": 111448, "diesel_marino": null, "parte_actualizada": 0, "total_aplicaciones": 0, "recargos": 0, "fecha_pago_realizado_anterioridad": null, "multa_por_correccion": null, "monto_pagado_anterioridad": null, "total_de_contribuciones": 111448, "importe_pagado_ultimas_48_hrs": null, "credito_al_salario": null, "cantidad_a_cargo": 111448, "subsidio_empleo": null, "aplica_primera_parcialidad": "NO", "compensaciones": null, "credito_ieps_diesel": null, "otros_estimulos": null, "cantidad_a_favor": null, "cretificados_tesofe": null, "cantidad_a_pagar": 111448, "importe_1ra_parcialidad": null, "importe_sin_1ra_parcialidad": null } }, "pdf": "===PDF_BINARY====", "receipt_pdf": "===PDF_BINARY====", "type": "monthly" } }, "TaxStatusPersonalListPaginated": { "summary": "Personal Tax Status", "description": "Example of a list of personal tax status", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "e88d29d1-3dc6-407f-825c-a9b50453e349", "link": "401d5a8e-79e2-472e-a1ca-8f4646f5cb24", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "place_and_date_of_issuance": "BUENAVENTURA, CIUDAD DE MEXICO A 22 DE FEBRERO DE 2021", "official_name": "Alfredo Gonzalo Robin", "id_cif": "2274235873432", "tax_payer_information": { "rfc": "GGTF770303G7", "curp": "BEMP930403HDFLLT00", "name": "Alfredo", "first_last_name": "Gonzalo", "second_last_name": "Robin", "start_operations_date": "2000-06-01", "status_padron": "ACTIVO", "last_status_change_date": "2000-06-01", "commercial_name": "Alfredo Gonzalo Robin", "social_name": null, "email": "alfredo@robin.com", "phone": "667507132" }, "address": { "postal_code": "21255", "street_type": "BOULEVARD (BLVD.)", "street": "GENERAL GIMENO", "exterior_number": "4360", "interior_number": "PLANTA BAJA", "suburb": "BUENAVENTURA", "locality": null, "municipality": "ALTOS DE MIRAMAR", "state": "CIUDAD DE MEXICO", "between_street": [ { "street_one": "CALLE PRINCIPE", "street_two": "CALLE NUEVA ROMA" } ] }, "economic_activity": [ { "order": "1", "economic_activity": "Asalariado", "percentage": "100", "initial_date": "2014-11-05", "end_date": null } ], "regimes": [ { "regimen": "Régimen de Sueldos y Salarios e Ingresos Asimilados a Salarios", "initial_date": "2003-01-01", "end_date": null } ], "obligations": [ { "obligation": "Declaración informativa de IVA con la anual de ISR", "expiration": "Conjuntamente con la declaración anual del ejercicio.", "initial_date": "2004-03-31", "end_date": null }, { "obligation": "Pago definitivo mensual de IVA.", "expiration": "A más tardar el día 17 del mes inmediato posterior al periodo que corresponda.", "initial_date": "2004-03-31", "end_date": null } ], "digital_stamp": "||2020/09/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN FISCAL|2044441088666600000034||", "digital_stamp_chain": "ExpsnSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjel=", "pdf": "=PDF-STRING=" } ] } }, "TaxStatusBusinessListPaginated": { "summary": "Business Tax Status", "description": "Example of a list of business tax status", "value": { "count": 101, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "6de34cb3-bf0d-445d-b832-7ec7781e2c6f", "link": "0b2edc42-7214-4c68-b22e-ae6885bf7c07", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "place_and_date_of_issuance": "BUENAVENTURA, CIUDAD DE MEXICO A 22 DE FEBRERO DE 2021", "official_name": "ACNE SA DE CV", "id_cif": "2274235873432", "tax_payer_information": { "rfc": "GHTF980303F7", "curp": null, "name": null, "first_last_name": null, "second_last_name": null, "start_operations_date": "1995-08-01", "status_padron": "ACTIVO", "last_status_change_date": "1995-08-01", "commercial_name": null, "social_name": "ACNE SA DE CV", "email": "contact@acne.com", "phone": "555507122" }, "address": { "postal_code": "21255", "street_type": "BOULEVARD (BLVD.)", "street": "GENERAL GIMENO", "exterior_number": "4360", "interior_number": "PLANTA BAJA", "suburb": "BUENAVENTURA", "locality": null, "municipality": "ALTOS DE MIRAMAR", "state": "CIUDAD DE MEXICO", "between_street": [ { "street_one": "CALLE PRINCIPE", "street_two": "CALLE NUEVA ROMA" } ] }, "economic_activity": [ { "order": "1", "economic_activity": "Otros servicios profesionales, científicos y técnicos", "percentage": "100", "initial_date": "2014-11-05", "end_date": null } ], "regimes": [ { "regimen": "Régimen General de Ley Personas Morales", "initial_date": "2003-01-01", "end_date": null } ], "obligations": [ { "obligation": "Declaración informativa de IVA con la anual de ISR", "expiration": "Conjuntamente con la declaración anual del ejercicio.", "initial_date": "2004-03-31", "end_date": null }, { "obligation": "Pago definitivo mensual de IVA.", "expiration": "A más tardar el día 17 del mes inmediato posterior al periodo que corresponda.", "initial_date": "2004-03-31", "end_date": null } ], "digital_stamp": "||2020/04/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN FISCAL|2044441088666600000034||", "digital_stamp_chain": "EtenSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjow=", "pdf": "=PDF-STRING=" } ] } }, "TaxStatusPersonalList": { "summary": "Personal Tax Status", "description": "Example of a list of personal tax status", "value": { "id": "6de34cb3-bf0d-445d-b832-7ec7781e2c6f", "link": "401d5a8e-79e2-472e-a1ca-8f4646f5cb24", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "place_and_date_of_issuance": "BUENAVENTURA, CIUDAD DE MEXICO A 22 DE FEBRERO DE 2021", "official_name": "Alfredo Gonzalo Robin", "id_cif": "2274235873432", "tax_payer_information": { "rfc": "GGTF770303G7", "curp": "BEMP930403HDFLLT00", "name": "Alfredo", "first_last_name": "Gonzalo", "second_last_name": "Robin", "start_operations_date": "2000-06-01", "status_padron": "ACTIVO", "last_status_change_date": "2000-06-01", "commercial_name": "Alfredo Gonzalo Robin", "social_name": null, "email": "alfredo@robin.com", "phone": "667507132" }, "address": { "postal_code": "21255", "street_type": "BOULEVARD (BLVD.)", "street": "GENERAL GIMENO", "exterior_number": "4360", "interior_number": "PLANTA BAJA", "suburb": "BUENAVENTURA", "locality": null, "municipality": "ALTOS DE MIRAMAR", "state": "CIUDAD DE MEXICO", "between_street": [ { "street_one": "CALLE PRINCIPE", "street_two": "CALLE NUEVA ROMA" } ] }, "economic_activity": [ { "order": "1", "economic_activity": "Asalariado", "percentage": "100", "initial_date": "2014-11-05", "end_date": null } ], "regimes": [ { "regimen": "Régimen de Sueldos y Salarios e Ingresos Asimilados a Salarios", "initial_date": "2003-01-01", "end_date": null } ], "obligations": [ { "obligation": "Declaración informativa de IVA con la anual de ISR", "expiration": "Conjuntamente con la declaración anual del ejercicio.", "initial_date": "2004-03-31", "end_date": null }, { "obligation": "Pago definitivo mensual de IVA.", "expiration": "A más tardar el día 17 del mes inmediato posterior al periodo que corresponda.", "initial_date": "2004-03-31", "end_date": null } ], "digital_stamp": "||2020/09/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN FISCAL|2044441088666600000034||", "digital_stamp_chain": "ExpsnSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjel=", "pdf": "=PDF-STRING=" } }, "TaxStatusBusinessList": { "summary": "Business Tax Status", "description": "Example of a list of business tax status", "value": { "id": "6de34cb3-bf0d-445d-b832-7ec7781e2c6f", "link": "0b2edc42-7214-4c68-b22e-ae6885bf7c07", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "place_and_date_of_issuance": "BUENAVENTURA, CIUDAD DE MEXICO A 22 DE FEBRERO DE 2021", "official_name": "ACNE SA DE CV", "id_cif": "2274235873432", "tax_payer_information": { "rfc": "GHTF980303F7", "curp": null, "name": null, "first_last_name": null, "second_last_name": null, "start_operations_date": "1995-08-01", "status_padron": "ACTIVO", "last_status_change_date": "1995-08-01", "commercial_name": null, "social_name": "ACNE SA DE CV", "email": "contact@acne.com", "phone": "555507122" }, "address": { "postal_code": "21255", "street_type": "BOULEVARD (BLVD.)", "street": "GENERAL GIMENO", "exterior_number": "4360", "interior_number": "PLANTA BAJA", "suburb": "BUENAVENTURA", "locality": null, "municipality": "ALTOS DE MIRAMAR", "state": "CIUDAD DE MEXICO", "between_street": [ { "street_one": "CALLE PRINCIPE", "street_two": "CALLE NUEVA ROMA" } ] }, "economic_activity": [ { "order": "1", "economic_activity": "Otros servicios profesionales, científicos y técnicos", "percentage": "100", "initial_date": "2014-11-05", "end_date": null } ], "regimes": [ { "regimen": "Régimen General de Ley Personas Morales", "initial_date": "2003-01-01", "end_date": null } ], "obligations": [ { "obligation": "Declaración informativa de IVA con la anual de ISR", "expiration": "Conjuntamente con la declaración anual del ejercicio.", "initial_date": "2004-03-31", "end_date": null }, { "obligation": "Pago definitivo mensual de IVA.", "expiration": "A más tardar el día 17 del mes inmediato posterior al periodo que corresponda.", "initial_date": "2004-03-31", "end_date": null } ], "digital_stamp": "||2020/04/26|GHTF980303F7|CONSTANCIA DE SITUACIÓN FISCAL|2044441088666600000034||", "digital_stamp_chain": "EtenSA9t1adG7bn+Jj23kj43JK+XbMPxdOppwabhXD+pXseSqYowWWDna0mpUk3264lkj2345j23faNZB852dCDt9KAjow=", "pdf": null } }, "ChileInvoicesAll": { "summary": "List of invoices", "description": "Example of a list of all possible invoices.", "value": { "count": 10, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { "id": "bfafa41d-48aa-4de0-9220-f2ca432cc51d", "link": "1f10cf48-4814-4cac-ae32-6c4ed5460a80", "created_at": "2025-02-10T20:26:06.643919Z", "collected_at": "2025-02-10T20:25:49.468130Z", "additional_data": null, "invoice_identification": "e503b879d1645a2c38f9701b546d1a8327c490fe", "total_amount": 95866, "net_amount": 80560, "vat_amount": 0, "currency": "CLP", "issue_date": "2024-03-06", "received_at": "2024-03-06T11:25:40", "acknowledged_at": null, "claim_date": null, "status": "REGISTERED", "document_code": 61, "category": "Del Giro", "folio": "57419308", "sender_id": "11111111-2", "sender_name": "INGENIERIA E BAILES LTDA", "receiver_id": "22222222-1", "receiver_name": "MONITORES SPA", "type": "OUTFLOW", "sale_invoice_details": null, "purchase_invoice_details": { "vat_refundable_amount": 15306, "vat_non_refundable_amount": 0, "vat_non_refundable_code": 0, "net_amount_fixed_assets": 0, "vat_fixed_assets": 0, "vat_common_use": 0, "tax_non_credit_amount": 0, "vat_non_withheld": 0, "tax_cigar_amount": 0, "tax_cigarettes_amount": 0, "tax_processed_tobacco_amount": 0, "tax_exempt_amount": 0, "credit_or_debit_note_on_purchase": 0, "additional_tax_code": null, "additional_tax_rate": null, "additional_tax_amount": 0 }, "summary_invoice_details": null }, { "id": "0acb61a6-cd12-4ed9-b727-33fa717af526", "link": "10ccdce9-aa90-42bd-99ef-47a8a02e7b52", "created_at": "2025-02-10T22:49:47.003071Z", "collected_at": "2025-02-10T22:49:39.234391Z", "additional_data": null, "invoice_identification": "3c9e15a76b8d204f57a1639082d4c9f80e67b213", "total_amount": 0, "net_amount": 2488000, "vat_amount": 472720, "currency": "CLP", "issue_date": "2024-09-26", "received_at": "2024-09-26T13:37:40", "acknowledged_at": "2024-09-27T11:27:47", "claim_date": null, "status": "REGISTERED", "document_code": 33, "category": "Del Giro", "folio": "23", "sender_id": "11111111-2", "sender_name": "INGENIERIA E BAILES LTDA", "receiver_id": "22222222-1", "receiver_name": "MONITORES SPA", "type": "INFLOW", "sale_invoice_details": { "vat_amount": 472720, "vat_total_withheld": 0, "vat_partially_withheld": 0, "vat_non_withheld": 0, "vat_sales": 0, "vat_third_party": 0, "invoice_settlement_sender_id": null, "invoice_settlement_net_commission": 0, "invoice_settlement_exempt_commission": 0, "invoice_settlement_vat_commission": 0, "vat_past_due": 0, "reference_document_type": "0", "reference_document_folio": null, "foreign_recipient_id": null, "foreign_recipient_nationality": null, "construction_sector_tax_credit": "0", "tax_free_trade_zone_amount": null, "container_deposit_guarantee": 0, "is_free_of_charge": false, "periodic_billing_type": 0, "non_billable_amount": 0, "total_amount_for_period": 0, "domestic_transportation_amount": null, "international_transportation_amount": null, "branch_code": 76129014, "tax_exempt_amount": 0, "credit_or_debit_note_on_purchase": null, "additional_tax_code": null, "additional_tax_rate": null, "additional_tax_amount": 0 }, "purchase_invoice_details": null, "summary_invoice_details": null }, { "id": "17de57b4-5c7d-424d-b623-680680f9cdf8", "link": "09915956-7031-4403-9382-5193bdfb6909", "created_at": "2025-02-10T20:29:42.785011Z", "collected_at": "2025-02-10T20:29:27.111746Z", "additional_data": null, "invoice_identification": "8a2f9b1d4e0c735619d834a526f1e07b9c35d641", "total_amount": 45000, "net_amount": 0, "vat_amount": 0, "currency": "CLP", "issue_date": "2024-01-01", "received_at": null, "acknowledged_at": null, "claim_date": null, "status": "REGISTERED", "document_code": 48, "category": "COMPROBANTE_PAGO", "folio": null, "sender_id": "11111111-2", "sender_name": null, "receiver_id": null, "receiver_name": null, "type": "INFLOW", "sale_invoice_details": null, "purchase_invoice_details": null, "summary_invoice_details": { "updated_at": "2024-01-12T02:49:38-03:00", "tax_exempt_amount": 0, "total_documents": 3, "month": "2024-01" } } ] } }, "PurchaseInvoiceArray": { "summary": "Purchase Invoice", "description": "Example of a Purchase invoice.", "value": [ { "id": "bfafa41d-48aa-4de0-9220-f2ca432cc51d", "link": "1f10cf48-4814-4cac-ae32-6c4ed5460a80", "created_at": "2025-02-10T20:26:06.643919Z", "collected_at": "2025-02-10T20:25:49.468130Z", "additional_data": null, "invoice_identification": "e503b879d1645a2c38f9701b546d1a8327c490fe", "total_amount": 95866, "net_amount": 80560, "vat_amount": 0, "currency": "CLP", "issue_date": "2024-03-06", "received_at": "2024-03-06T11:25:40", "acknowledged_at": null, "claim_date": null, "status": "REGISTERED", "document_code": 61, "category": "Del Giro", "folio": "57419308", "sender_id": "11111111-2", "sender_name": "INGENIERIA E BAILES LTDA", "receiver_id": "22222222-1", "receiver_name": "MONITORES SPA", "type": "OUTFLOW", "sale_invoice_details": null, "purchase_invoice_details": { "vat_refundable_amount": 15306, "vat_non_refundable_amount": 0, "vat_non_refundable_code": 0, "net_amount_fixed_assets": 0, "vat_fixed_assets": 0, "vat_common_use": 0, "tax_non_credit_amount": 0, "vat_non_withheld": 0, "tax_cigar_amount": 0, "tax_cigarettes_amount": 0, "tax_processed_tobacco_amount": 0, "tax_exempt_amount": 0, "credit_or_debit_note_on_purchase": 0, "additional_tax_code": null, "additional_tax_rate": null, "additional_tax_amount": 0 }, "summary_invoice_details": null } ] }, "SummaryInvoiceArray": { "summary": "Summary Invoice Details", "description": "Example of an *Summary Invoice Details* type of invoice.", "value": [ { "id": "17de57b4-5c7d-424d-b623-680680f9cdf8", "link": "09915956-7031-4403-9382-5193bdfb6909", "created_at": "2025-02-10T20:29:42.785011Z", "collected_at": "2025-02-10T20:29:27.111746Z", "additional_data": null, "invoice_identification": "8a2f9b1d4e0c735619d834a526f1e07b9c35d641", "total_amount": 45000, "net_amount": 0, "vat_amount": 0, "currency": "CLP", "issue_date": "2024-01-01", "received_at": null, "acknowledged_at": null, "claim_date": null, "status": "REGISTERED", "document_code": 48, "category": "COMPROBANTE_PAGO", "folio": null, "sender_id": "11111111-2", "sender_name": null, "receiver_id": null, "receiver_name": null, "type": "INFLOW", "sale_invoice_details": null, "purchase_invoice_details": null, "summary_invoice_details": { "updated_at": "2024-01-12T02:49:38-03:00", "tax_exempt_amount": 0, "total_documents": 3, "month": "2024-01" } } ] }, "SaleInvoiceArray": { "summary": "Sale Invoice", "description": "Example of a Sale invoice.", "value": [ { "id": "0acb61a6-cd12-4ed9-b727-33fa717af526", "link": "10ccdce9-aa90-42bd-99ef-47a8a02e7b52", "created_at": "2025-02-10T22:49:47.003071Z", "collected_at": "2025-02-10T22:49:39.234391Z", "additional_data": null, "invoice_identification": "3c9e15a76b8d204f57a1639082d4c9f80e67b213", "total_amount": 0, "net_amount": 2488000, "vat_amount": 472720, "currency": "CLP", "issue_date": "2024-09-26", "received_at": "2024-09-26T13:37:40", "acknowledged_at": "2024-09-27T11:27:47", "claim_date": null, "status": "REGISTERED", "document_code": 33, "category": "Del Giro", "folio": "23", "sender_id": "11111111-2", "sender_name": "INGENIERIA E BAILES LTDA", "receiver_id": "22222222-1", "receiver_name": "MONITORES SPA", "type": "INFLOW", "sale_invoice_details": { "vat_amount": 472720, "vat_total_withheld": 0, "vat_partially_withheld": 0, "vat_non_withheld": 0, "vat_sales": 0, "vat_third_party": 0, "invoice_settlement_sender_id": null, "invoice_settlement_net_commission": 0, "invoice_settlement_exempt_commission": 0, "invoice_settlement_vat_commission": 0, "vat_past_due": 0, "reference_document_type": "0", "reference_document_folio": null, "foreign_recipient_id": null, "foreign_recipient_nationality": null, "construction_sector_tax_credit": "0", "tax_free_trade_zone_amount": null, "container_deposit_guarantee": 0, "is_free_of_charge": false, "periodic_billing_type": 0, "non_billable_amount": 0, "total_amount_for_period": 0, "domestic_transportation_amount": null, "international_transportation_amount": null, "branch_code": 76129014, "tax_exempt_amount": 0, "credit_or_debit_note_on_purchase": null, "additional_tax_code": null, "additional_tax_rate": null, "additional_tax_amount": 0 }, "purchase_invoice_details": null, "summary_invoice_details": null } ] }, "PurchaseInvoiceDetails": { "summary": "Purchase Invoice", "description": "Example of a Purchase invoice.", "value": { "id": "bfafa41d-48aa-4de0-9220-f2ca432cc51d", "link": "1f10cf48-4814-4cac-ae32-6c4ed5460a80", "created_at": "2025-02-10T20:26:06.643919Z", "collected_at": "2025-02-10T20:25:49.468130Z", "additional_data": null, "invoice_identification": "e503b879d1645a2c38f9701b546d1a8327c490fe", "total_amount": 95866, "net_amount": 80560, "vat_amount": 0, "currency": "CLP", "issue_date": "2024-03-06", "received_at": "2024-03-06T11:25:40", "acknowledged_at": null, "claim_date": null, "status": "REGISTERED", "document_code": 61, "category": "Del Giro", "folio": "57419308", "sender_id": "11111111-2", "sender_name": "INGENIERIA E BAILES LTDA", "receiver_id": "22222222-1", "receiver_name": "MONITORES SPA", "type": "OUTFLOW", "sale_invoice_details": null, "purchase_invoice_details": { "vat_refundable_amount": 15306, "vat_non_refundable_amount": 0, "vat_non_refundable_code": 0, "net_amount_fixed_assets": 0, "vat_fixed_assets": 0, "vat_common_use": 0, "tax_non_credit_amount": 0, "vat_non_withheld": 0, "tax_cigar_amount": 0, "tax_cigarettes_amount": 0, "tax_processed_tobacco_amount": 0, "tax_exempt_amount": 0, "credit_or_debit_note_on_purchase": 0, "additional_tax_code": null, "additional_tax_rate": null, "additional_tax_amount": 0 }, "summary_invoice_details": null } }, "SummaryInvoiceDetails": { "summary": "Summary Invoice Details", "description": "Example of an *Summary Invoice Details* type of invoice.", "value": { "id": "17de57b4-5c7d-424d-b623-680680f9cdf8", "link": "09915956-7031-4403-9382-5193bdfb6909", "created_at": "2025-02-10T20:29:42.785011Z", "collected_at": "2025-02-10T20:29:27.111746Z", "additional_data": null, "invoice_identification": "8a2f9b1d4e0c735619d834a526f1e07b9c35d641", "total_amount": 45000, "net_amount": 0, "vat_amount": 0, "currency": "CLP", "issue_date": "2024-01-01", "received_at": null, "acknowledged_at": null, "claim_date": null, "status": "REGISTERED", "document_code": 48, "category": "COMPROBANTE_PAGO", "folio": null, "sender_id": "11111111-2", "sender_name": null, "receiver_id": null, "receiver_name": null, "type": "INFLOW", "sale_invoice_details": null, "purchase_invoice_details": null, "summary_invoice_details": { "updated_at": "2024-01-12T02:49:38-03:00", "tax_exempt_amount": 0, "total_documents": 3, "month": "2024-01" } } }, "SaleInvoiceDetails": { "summary": "Sale Invoice", "description": "Example of a Sale invoice.", "value": { "id": "0acb61a6-cd12-4ed9-b727-33fa717af526", "link": "10ccdce9-aa90-42bd-99ef-47a8a02e7b52", "created_at": "2025-02-10T22:49:47.003071Z", "collected_at": "2025-02-10T22:49:39.234391Z", "additional_data": null, "invoice_identification": "3c9e15a76b8d204f57a1639082d4c9f80e67b213", "total_amount": 0, "net_amount": 2488000, "vat_amount": 472720, "currency": "CLP", "issue_date": "2024-09-26", "received_at": "2024-09-26T13:37:40", "acknowledged_at": "2024-09-27T11:27:47", "claim_date": null, "status": "REGISTERED", "document_code": 33, "category": "Del Giro", "folio": "23", "sender_id": "11111111-2", "sender_name": "INGENIERIA E BAILES LTDA", "receiver_id": "22222222-1", "receiver_name": "MONITORES SPA", "type": "INFLOW", "sale_invoice_details": { "vat_amount": 472720, "vat_total_withheld": 0, "vat_partially_withheld": 0, "vat_non_withheld": 0, "vat_sales": 0, "vat_third_party": 0, "invoice_settlement_sender_id": null, "invoice_settlement_net_commission": 0, "invoice_settlement_exempt_commission": 0, "invoice_settlement_vat_commission": 0, "vat_past_due": 0, "reference_document_type": "0", "reference_document_folio": null, "foreign_recipient_id": null, "foreign_recipient_nationality": null, "construction_sector_tax_credit": "0", "tax_free_trade_zone_amount": null, "container_deposit_guarantee": 0, "is_free_of_charge": false, "periodic_billing_type": 0, "non_billable_amount": 0, "total_amount_for_period": 0, "domestic_transportation_amount": null, "international_transportation_amount": null, "branch_code": 76129014, "tax_exempt_amount": 0, "credit_or_debit_note_on_purchase": null, "additional_tax_code": null, "additional_tax_rate": null, "additional_tax_amount": 0 }, "purchase_invoice_details": null, "summary_invoice_details": null } }, "ResponseBankAccountBusinessPixInfoPaginated": { "summary": "Business bank account (OFPI)", "value": { "count": 110, "next": "https://api.belvo.com/payments/{endpoint}/?page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "created_at": "2023-02-15T07:52:31.998761Z", "created_by": "417514fe-50f6-42e9-a3eb-c71da00f014c", "institution": "f512d996-583a-4a91-8b5b-eba2e103b068", "customer": null, "holder": { "type": "BUSINESS", "information": { "name": "Music Production Brazil", "identifier_type": "CNPJ", "identifier": "00000000000191" } }, "details": { "country": "BRA", "account_type": "CHECKINGS", "agency": "0444", "number": "45722-0" } } ] } }, "ResponseBankAccountIndividualPixInfoPaginated": { "summary": "Individual bank account (OFPI)", "value": { "count": 110, "next": "https://api.belvo.com/payments/{endpoint}/?page=2", "previous": null, "results": [ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "created_at": "2023-02-15T07:52:31.998761Z", "created_by": "417514fe-50f6-42e9-a3eb-c71da00f014c", "institution": "f512d996-583a-4a91-8b5b-eba2e103b068", "customer": "49f244ef-06cd-49cf-ad0c-f43796e370ad", "holder": { "type": "INDIVIDUAL", "information": { "first_name": "Gustavo", "last_name": "Veloso", "identifier_type": "CPF", "identifier": "23******00" } }, "details": { "country": "BRA", "account_type": "CHECKINGS", "agency": "0444", "number": "45722-0" } } ] } }, "PaymentIntentResponsePixKeyInitial": { "summary": "Pix Key", "description": "Pix Key Payment Intent", "value": { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "customer": "1c83ead8-6665-429c-a17a-ddc76cb3a95e", "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73", "created_at": "2022-02-09T08:45:50.406032Z", "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09", "updated_at": "2022-02-09T08:45:50.406032Z", "status": "REQUIRES_ACTION", "amount": "1234.12", "currency": "BRL", "description": "Training shoes", "statement_description": "Super Shoe Store - Brown Sneakers", "selected_payment_method_type": "open_finance", "allowed_payment_method_types": [ "open_finance" ], "payment_method_details": { "open_finance": { "pix_key": "53497b80-81a2-4ea8-9296-83a909c05bdf", "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0", "callback_url": "https://www.acmecorp.com/checkout/3487321", "cpf": "23******00", "schedule": { "single": { "date": "2024-10-22" } } } }, "payment_method_information": { "open_finance": { "pix_key_details": { "identifier": "23******00", "name": "João da Silva" } } }, "failure_code": null, "failure_message": null, "metadata": { "internal_reference_id": "GGq73487w2" }, "charges": [], "provider": "belvo", "last_error": { "error_code": "payment_error", "error_message": "Unexpected error to confirm the payment" }, "next_step": null } }, "PaymentIntentResponseOfpiBankAccount": { "summary": "Bank Account", "description": "Bank Account (Confirmed)", "value": { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "customer": "1c83ead8-6665-429c-a17a-ddc76cb3a95e", "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73", "created_at": "2022-02-09T08:45:50.406032Z", "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09", "updated_at": "2022-02-09T08:45:50.406032Z", "status": "REQUIRES_ACTION", "amount": "1234.12", "currency": "BRL", "description": "Training shoes", "statement_description": "Super Shoe Store - Brown Sneakers", "selected_payment_method_type": "open_finance", "allowed_payment_method_types": [ "open_finance" ], "payment_method_details": { "open_finance": { "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc", "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0", "schedule": { "single": { "date": "2024-10-22" } }, "callback_url": "https://www.acmecorp.com/checkout/3487321", "cpf": "23******00" } }, "payment_method_information": { "open_finance": { "provider_request_id": "978c0c97ea847e78e8849634473c1f1", "redirect_url": "https://wakandanational.com/", "end_to_end_id": "F203262942022211117487a213b1d140", "settlement_date": "2024-10-22" } }, "failure_code": null, "failure_message": null, "metadata": { "internal_reference_id": "GGq73487w2" }, "charges": [ { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "created_at": "2022-02-09T08:45:50.406032Z", "updated_at": "2022-02-09T08:45:50.406032Z", "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09", "customer": "531aa631-70a0-4eeb-ab97-51dea3e90c89", "payment_intent": "50c04229-7b1d-4a53-951c-8ad53e10c6ca", "status": "PENDING", "amount": "100.12", "currency": "BRL", "description": "Training shoes", "statement_description": "Super Shoe Store - Brown Sneakers", "beneficiary": "58524ccc-89ac-4ab6-b62b-c3da3f19a722", "provider": "belvo", "payment_method_type": "open_finance", "payment_method_details": { "open_finance": { "schedule": { "single": { "date": "2024-10-22" } }, "payer_institution": "db201c6a-e0ee-4caa-92d6-72b480d6d86f", "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc" } }, "payment_method_information": { "open_finance": { "provider_request_id": "978c0c97ea847e78e8849634473c1f1", "redirect_url": "https://wakandanational.com/", "end_to_end_id": "F203262942022211117487a213b1d140", "settlement_date": "2024-10-22" } }, "payer_information": { "bank_account": { "code": "123345", "type": "CHECKINGS", "agency": "1234", "number": "123456789" } }, "transactions": [ { "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "created_at": "2022-02-09T08:45:50.406032Z", "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09", "amount": "1020.00", "currency": "BRL", "description": "Training shoes", "transaction_type": "INFLOW", "beneficiary": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc", "payer": null, "payment_intent": "004a28bb-fac2-4172-884b-5b6ea15314ad", "customer": "9eebd63b-3339-44a9-8a5a-72bb6cb2f310" } ], "failure_code": null, "failure_message": null, "metadata": { "internal_reference_id": "GGq73487w2" } } ], "provider": "belvo", "last_error": { "error_code": "payment_error", "error_message": "Unexpected error to confirm the payment" }, "next_step": null } } }, "headers": { "header_idempotency_key_response": { "description": "The idempotency key that was used in the request. This key helps prevent duplicate operations by allowing the server to recognize repeated requests with the same key and return the original response instead of processing the request again.\n\n{% admonition type=\"warning\" name=\"In Beta\" %}\n This feature is currently in Beta and only available for selected customers. If you encounter any issues or are interested in using this feature, please contact your Belvo representative.\n{% /admonition %}\n", "schema": { "type": "string", "format": "uuid", "example": "82737f32-7730-4832-a985-dd86df70301c" } }, "header_idempotency_key_status_response": { "description": "The status of the idempotent request associated with the `Belvo-Idempotency-Key` header.\n\nCan be one of the following values:\n- `AVAILABLE`: The original request has been processed successfully, and the response is available.\n- `PROCESSING`: The original request is still being processed.\n- `REPLAYED`: The original request has already been processed, and the response has been returned.\n\n{% admonition type=\"warning\" name=\"In Beta\" %}\n This feature is currently in Beta and only available for selected customers. If you encounter any issues or are interested in using this feature, please contact your Belvo representative.\n{% /admonition %}\n", "schema": { "type": "string", "enum": [ "AVAILABLE", "PROCESSING", "REPLAYED" ], "example": "AVAILABLE" } } } }, "x-tagGroups": [ { "name": "Core Resources", "tags": [ "Institutions", "Links", "Widget Access Token", "Consents" ] }, { "name": "Open Finance Data Aggregation (Brazil)", "tags": [ "Owners", "Accounts", "Balances", "Exchanges", "Transactions", "Bills", "Investments Brazil", "Investment Transactions Brazil" ] }, { "name": "Employments Brazil", "tags": [ "Employments Brazil" ] }, { "name": "Employment Records Mexico", "tags": [ "Employment Records Mexico", "Current Employments Mexico" ] }, { "name": "Fiscal Mexico", "tags": [ "Invoices", "Tax compliance status", "Tax returns", "Tax retentions", "Tax status", "Financial Statements" ] }, { "name": "Fiscal Chile", "tags": [ "Invoices Chile", "Tax Status Chile", "Debt Reports Chile" ] }, { "name": "Enrichment API", "tags": [ "Incomes", "Recurring Expenses", "Risk Insights", "Employment Metrics" ] }, { "name": "Payment Initiation (Brazil)", "tags": [ "Payment Initiation introduction (Brazil)", "Payment Institutions (Brazil)", "Customers (Brazil)", "Bank Accounts (Brazil)", "Payment Authorizations (Brazil)", "Charges (Brazil)", "Payment Intents (Brazil)", "Biometric Pix Widget Access Token (Brazil)", "Enrollments (Brazil)", "Payment Transactions (Brazil)" ] } ] }