Belvo Payments (Brazil / Pix) API
Initiate account-to-account payments in Brazil over Pix and the Open Finance network using payment intents, customers, payment institutions, and payment transactions.
OpenAPI Specification
openapi: 3.0.1
info:
title: Belvo API
description: >-
The Belvo API is a RESTful open-finance API for Latin America. It lets you
connect to bank, fiscal, and employment institutions across Mexico, Brazil,
and Colombia through Links, then retrieve accounts, balances, transactions,
owners, incomes, and recurring expenses. The Payments (Brazil) surface
initiates account-to-account payments over Pix and the Open Finance network.
All requests use HTTP Basic authentication with your Secret Key ID as the
username and Secret Key Password as the password.
termsOfService: https://belvo.com/terms-and-conditions/
contact:
name: Belvo Support
email: support@belvo.com
url: https://developers.belvo.com
version: '1.0'
servers:
- url: https://api.belvo.com
description: Production
- url: https://sandbox.belvo.com
description: Sandbox
security:
- basicAuth: []
tags:
- name: Links
description: Manage the credential connections to institutions.
- name: Accounts
description: Bank accounts held inside a Link.
- name: Transactions
description: Detailed transaction history for accounts in a Link.
- name: Balances
description: Point-in-time balances for checking and savings accounts.
- name: Owners
description: Identity of the Link owner.
- name: Incomes
description: Income insights derived from account activity.
- name: Recurring Expenses
description: Regular subscription and utility payments.
- name: Institutions
description: Institutions Belvo can connect to.
- name: Payments (Brazil)
description: Pix / Open Finance payment initiation in Brazil.
- name: Webhooks
description: Asynchronous event notifications.
paths:
/api/links/:
get:
operationId: listLinks
tags:
- Links
summary: List all Links
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of Links.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedLinks'
post:
operationId: registerLink
tags:
- Links
summary: Register a new Link
description: >-
Register a Link by providing the institution and the end-user
credentials. Use access_mode single for a one-time pull or recurrent
to keep data refreshed.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinkRequest'
responses:
'201':
description: The Link was created.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
$ref: '#/components/responses/Error'
/api/links/{id}/:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: detailLink
tags:
- Links
summary: Get a Link's details
responses:
'200':
description: The requested Link.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
patch:
operationId: patchLink
tags:
- Links
summary: Complete or update a Link request
description: Send a token or OTP to complete a multi-factor Link request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinkPatchRequest'
responses:
'200':
description: The updated Link.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
delete:
operationId: deleteLink
tags:
- Links
summary: Delete a Link
responses:
'204':
description: The Link was deleted.
/api/accounts/:
get:
operationId: listAccounts
tags:
- Accounts
summary: List all accounts
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of accounts.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAccounts'
post:
operationId: retrieveAccounts
tags:
- Accounts
summary: Retrieve accounts for a Link
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveRequest'
responses:
'200':
description: The accounts found for the Link.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Account'
'201':
description: The accounts were retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Account'
/api/accounts/{id}/:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: detailAccount
tags:
- Accounts
summary: Get an account's details
responses:
'200':
description: The requested account.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
delete:
operationId: deleteAccount
tags:
- Accounts
summary: Delete an account
responses:
'204':
description: The account was deleted.
/api/transactions/:
get:
operationId: listTransactions
tags:
- Transactions
summary: List all transactions
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
- name: link
in: query
schema:
type: string
format: uuid
- name: account
in: query
schema:
type: string
- name: value_date__gte
in: query
schema:
type: string
format: date
- name: value_date__lte
in: query
schema:
type: string
format: date
responses:
'200':
description: A paginated list of transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTransactions'
post:
operationId: retrieveTransactions
tags:
- Transactions
summary: Retrieve transactions for a Link
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveTransactionsRequest'
responses:
'200':
description: The transactions found for the Link.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Transaction'
'201':
description: The transactions were retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Transaction'
/api/transactions/{id}/:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: detailTransaction
tags:
- Transactions
summary: Get a transaction's details
responses:
'200':
description: The requested transaction.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
/api/balances/:
get:
operationId: listBalances
tags:
- Balances
summary: List all balances
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of balances.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedBalances'
post:
operationId: retrieveBalances
tags:
- Balances
summary: Retrieve balances for a Link
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveBalancesRequest'
responses:
'200':
description: The balances found for the Link.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Balance'
'201':
description: The balances were retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Balance'
/api/owners/:
get:
operationId: listOwners
tags:
- Owners
summary: List all owners
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of owners.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedOwners'
post:
operationId: retrieveOwners
tags:
- Owners
summary: Retrieve owners for a Link
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveRequest'
responses:
'200':
description: The owners found for the Link.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Owner'
'201':
description: The owners were retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Owner'
/api/incomes/:
get:
operationId: listIncomes
tags:
- Incomes
summary: List all incomes
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of income records.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedIncomes'
post:
operationId: retrieveIncomes
tags:
- Incomes
summary: Retrieve incomes for a Link
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveRequest'
responses:
'200':
description: The income insights found for the Link.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Income'
'201':
description: The income insights were retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Income'
/api/recurring-expenses/:
get:
operationId: listRecurringExpenses
tags:
- Recurring Expenses
summary: List all recurring expenses
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of recurring expense records.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedRecurringExpenses'
post:
operationId: retrieveRecurringExpenses
tags:
- Recurring Expenses
summary: Retrieve recurring expenses for a Link
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveRequest'
responses:
'200':
description: The recurring expenses found for the Link.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecurringExpense'
'201':
description: The recurring expenses were retrieved.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecurringExpense'
/api/institutions/:
get:
operationId: listInstitutions
tags:
- Institutions
summary: List all institutions
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: A paginated list of institutions.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedInstitutions'
/api/institutions/{id}/:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: detailInstitution
tags:
- Institutions
summary: Get an institution's details
responses:
'200':
description: The requested institution.
content:
application/json:
schema:
$ref: '#/components/schemas/Institution'
/api/webhooks/:
get:
operationId: listWebhooks
tags:
- Webhooks
summary: List all webhooks
responses:
'200':
description: A list of registered webhook endpoints.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Webhook'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Create a webhook
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookRequest'
responses:
'201':
description: The webhook was created.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
/api/webhooks/{id}/:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: detailWebhook
tags:
- Webhooks
summary: Get a webhook's details
responses:
'200':
description: The requested webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook
responses:
'204':
description: The webhook was deleted.
/payments/br/payment-intents/:
get:
operationId: listPaymentIntents
tags:
- Payments (Brazil)
summary: List all payment intents
responses:
'200':
description: A paginated list of payment intents.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedPaymentIntents'
post:
operationId: createPaymentIntent
tags:
- Payments (Brazil)
summary: Create a payment intent
description: >-
Create a payment intent capturing the amount, description, provider,
and beneficiary required to process a Pix payment over the Open Finance
Network.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntentRequest'
responses:
'201':
description: The payment intent was created.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntent'
/payments/br/payment-intents/{id}/:
parameters:
- $ref: '#/components/parameters/ResourceId'
get:
operationId: detailPaymentIntent
tags:
- Payments (Brazil)
summary: Get a payment intent's details
responses:
'200':
description: The requested payment intent.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntent'
/payments/br/customers/:
get:
operationId: listCustomers
tags:
- Payments (Brazil)
summary: List all customers
responses:
'200':
description: A paginated list of customers.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCustomers'
post:
operationId: createCustomer
tags:
- Payments (Brazil)
summary: Create a customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
responses:
'201':
description: The customer was created.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/payments/br/payment-institutions/:
get:
operationId: listPaymentInstitutions
tags:
- Payments (Brazil)
summary: List all payment institutions
responses:
'200':
description: A list of institutions available for payments.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PaymentInstitution'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication using your Secret Key ID as the username and
your Secret Key Password as the password.
parameters:
ResourceId:
name: id
in: path
required: true
description: The unique identifier of the resource.
schema:
type: string
format: uuid
PageSize:
name: page_size
in: query
description: Number of items per page (max 1000).
schema:
type: integer
default: 100
maximum: 1000
Page:
name: page
in: query
description: The page number of results to return.
schema:
type: integer
default: 1
responses:
Error:
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Pagination:
type: object
properties:
count:
type: integer
next:
type: string
nullable: true
previous:
type: string
nullable: true
RetrieveRequest:
type: object
required:
- link
properties:
link:
type: string
format: uuid
description: The Link UUID to retrieve data for.
save_data:
type: boolean
default: true
RetrieveTransactionsRequest:
allOf:
- $ref: '#/components/schemas/RetrieveRequest'
- type: object
required:
- date_from
properties:
date_from:
type: string
format: date
date_to:
type: string
format: date
account:
type: string
RetrieveBalancesRequest:
allOf:
- $ref: '#/components/schemas/RetrieveRequest'
- type: object
required:
- date_from
properties:
date_from:
type: string
format: date
date_to:
type: string
format: date
LinkRequest:
type: object
required:
- institution
- username
- password
properties:
institution:
type: string
example: erebor_mx_retail
username:
type: string
password:
type: string
access_mode:
type: string
enum:
- single
- recurrent
default: single
external_id:
type: string
username_type:
type: string
LinkPatchRequest:
type: object
required:
- id
- token
properties:
id:
type: string
format: uuid
token:
type: string
link:
type: string
format: uuid
Link:
type: object
properties:
id:
type: string
format: uuid
institution:
type: string
access_mode:
type: string
enum:
- single
- recurrent
status:
type: string
enum:
- valid
- invalid
- unconfirmed
- token_required
created_at:
type: string
format: date-time
external_id:
type: string
nullable: true
institution_user_id:
type: string
nullable: true
last_accessed_at:
type: string
format: date-time
nullable: true
Account:
type: object
properties:
id:
type: string
format: uuid
link:
type: string
format: uuid
institution:
type: object
properties:
name:
type: string
type:
type: string
category:
type: string
example: CHECKING_ACCOUNT
type:
type: string
name:
type: string
number:
type: string
currency:
type: string
example: MXN
balance:
type: object
properties:
current:
type: number
available:
type: number
created_at:
type: string
format: date-time
Transaction:
type: object
properties:
id:
type: string
format: uuid
account:
$ref: '#/components/schemas/Account'
amount:
type: number
currency:
type: string
description:
type: string
value_date:
type: string
format: date
accounting_date:
type: string
format: date
type:
type: string
enum:
- INFLOW
- OUTFLOW
status:
type: string
enum:
- PROCESSED
- PENDING
- UNCATEGORIZED
category:
type: string
nullable: true
merchant:
type: object
nullable: true
properties:
name:
type: string
logo:
type: string
created_at:
type: string
format: date-time
Balance:
type: object
properties:
id:
type: string
format: uuid
account:
$ref: '#/components/schemas/Account'
value_date:
type: string
format: date
current_balance:
type: number
currency:
type: string
collected_at:
type: string
format: date-time
Owner:
type: object
properties:
id:
type: string
format: uuid
link:
type: string
format: uuid
display_name:
type: string
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
email:
type: string
nullable: true
phone_number:
type: string
nullable: true
address:
type: string
nullable: true
document_id:
type: object
nullable: true
properties:
document_type:
type: string
document_number:
type: string
collected_at:
type: string
format: date-time
Income:
type: object
properties:
id:
type: string
format: uuid
account:
$ref: '#/components/schemas/Account'
currency:
type: string
income_summary:
type: object
properties:
monthly_average:
type: number
number_of_income_streams:
type: integer
number_of_income_transactions:
type: integer
regular_income:
type: boolean
collected_at:
type: string
format: date-time
RecurringExpense:
type: object
properties:
id:
type: string
format: uuid
account:
$ref: '#/components/schemas/Account'
name:
type: string
category:
type: string
frequency:
type: string
enum:
- WEEKLY
- BIMONTHLY
- MONTHLY
- BIWEEKLY
- QUARTERLY
- SEMESTRALLY
- YEARLY
average_transaction_amount:
type: number
currency:
type: string
transactions:
type: array
items:
type: object
properties:
id:
type: string
amount:
type: number
value_date:
type: string
format: date
collected_at:
type: string
format: date-time
Institution:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
enum:
- bank
- fiscal
- employment
website:
type: string
nullable: true
display_name:
type: string
country_codes:
type: array
items:
type: string
primary_color:
type: string
logo:
type: string
nullable: true
resources:
type: array
items:
type: string
Webhook:
type: object
properties:
id:
type: string
format: uuid
url:
type: string
authorization_header:
type: string
nullable: true
enabled:
type: boolean
created_at:
type: string
format: date-time
WebhookRequest:
type: object
required:
- url
properties:
url:
type: string
authorization_header:
type: string
PaymentIntentRequest:
type: object
required:
- amount
- description
- provider
properties:
amount:
type: string
example: '100.00'
description:
type: string
provider:
type: string
example: pix
customer:
type: string
format: uuid
beneficiary:
type: object
properties:
name:
type: string
account:
type: object
properties:
institution:
type: string
number:
type: string
type:
type: string
allowed_payment_method_types:
type: array
items:
type: string
PaymentIntent:
type: object
properties:
id:
type: string
format: uuid
amount:
type: string
currency:
type: string
example: BRL
description:
type: string
status:
type: string
enum:
- REQUIRES_ACTION
- PROCESSING
- SUCCEEDED
- CANCELLED
- FAILED
provider:
type: string
next_action:
type: object
nullable: true
properties:
type:
type: string
redirect_url:
type: string
created_at:
type: string
format: date-time
Customer:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
nullable: true
identifier:
type: object
properties:
type:
type: string
example: CPF
number:
type: string
created_at:
type: string
format: date-time
CustomerRequest:
type: object
required:
- name
- identifier
properties:
name:
type: string
email:
type: string
identifier:
type: object
required:
- type
- number
properties:
type:
type: string
example: CPF
number:
type: string
PaymentInstitution:
type: object
properties:
id:
type: string
name:
type: string
display_name:
type: string
status:
type: string
logo:
type: string
nullable: true
Error:
type: array
items:
type: object
properties:
request_id:
type: string
message:
type: string
code:
type: string
PaginatedLinks:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Link'
PaginatedAccounts:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Account'
PaginatedTransactions:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Transaction'
PaginatedBalances:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Balance'
PaginatedOwners:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Owner'
PaginatedIncomes:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Income'
PaginatedRecurringExpenses:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/RecurringExpense'
PaginatedInstitutions:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
results:
type: array
items:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/belvo/refs/heads/main/openapi/belvo-openapi.yml