v1

latestOpenAPI 3.0.22026-08-061464031.4 MB

Transactions

Complete a transactions request

Used to resume a Transaction retrieve session that was paused because an MFA token was required by the institution.

patch/api/transactions/

Query parameters

omitstring

Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

fieldsstring

Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

Request body

sessionstring required

The session you want to resume. You need to use the session value that is provided in the 428 Token Required response that you receive after you make your POST request.

tokenstring

The MFA token generated by the institution which is required to continue a session.

linkstring uuid required

The link.id you want to resume. Must be the same link.id as the one you receive in the 428 Token Required response that contains the session ID.

save_databoolean

Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

When set to false, the data won't be persisted and we return a 200 OK response.

Example request

{
  "session": "6e7b283c6efa449c9c028a16b5c249fa",
  "token": "1234ab",
  "link": "683005d6-f45c-4adb-b289-f1a12f50f80c",
  "save_data": true
}

Response

Ok (when save_data=false)

idstring uuid required

Belvo's unique identifier for the current item.

internal_identificationstring required

The institution's internal identification for the transaction.

Non-nullable: A value must be returned by Brazil's open finance network.

collected_atstring date-time required

The ISO-8601 timestamp when the data point was collected.

created_atstring date-time required

The ISO-8601 timestamp of when the data point was created in Belvo's database.

value_datestring date required

The date when the transaction occurred, in YYYY-MM-DD format, in YYYY-MM-DD format.

Non-nullable: A value must be returned by Brazil's open finance network.

transacted_atstring date-time

The ISO-8601 timestamp of when the transaction occurred (in the UTC timezone).

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).

Institutions not abiding by this format: Some institutions may not provide the exact time of the transaction. In this case, the timestamp will be set to 00:00:00.000Z. Belvo has identified the following institutions as not abiding by the regulation and have raised the issue with regulators: Bradesco, Itau, and Sicoob.

Non-nullable: A value must be returned by Brazil's open finance network for credit card and checking account transactions.

accounting_datestring nullable required

The date when the transaction was processed and accounted for by the institution, in YYYY-MM-DD format.

Non-nullable: A value must be returned by Brazil's open finance network for credit card transactions.

inferred_accounting_datestring date

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.

amountnumber float required

The transaction amount. ℹ️ The amount displayed is always positive as we indicate the direction of the transaction in the type parameter.

Non-nullable: A value must be returned by Brazil's open finance network.

local_currency_amountnumber float nullable required

The value of the transaction in the local currency.

Non-nullable: A value must be returned by Brazil's open finance network for credit card transactions.

balancenumber float nullable required

Note: This field is not applicable for OF Brazil and will return null.

currencystring nullable required

The three-letter currency code (ISO-4217).

descriptionstring nullable required

The description of transaction provided by the institution. Usually this is the text that the end user sees in the online platform.

Non-nullable: A value must be returned by Brazil's open finance network.

observationsstring nullable required

Note: This field is not applicable for OF Brazil and will return null.

The name of the transaction category.

Get transaction categorization With <a href="https://developers.belvo.com/docs/banking#categorizing-transactions" target="_blank">Transaction categorization</a>, we clean and categorize transactions for you, turning raw data into actionable insights. To enable this feature, just <a href="https://belvo.com/contact/?utm_source=documentation" target="_blank">reach out</a> to us, and we'll get right to it.

We return one of the following enum values:

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

* For clients not using our Transaction Categorization product, we return null instead.

The transaction subcategory.

Get transaction categorization For clients not using our <a href="https://developers.belvo.com/docs/banking#categorizing-transactions" target="_blank">Transaction categorization</a>, we return null instead. To enable this feature, just <a href="https://belvo.com/contact/?utm_source=documentation" target="_blank">reach out</a> to us, and we'll get right to it.

We return one of the following enum values:

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

referencestring nullable required

Note: This field is not applicable for OF Brazil and will return null.

type'OUTFLOW' | 'INFLOW' | 'null' nullable required

The direction of the transaction:

INFLOW indicates money coming into the account.
OUTFLOW indicates money going out of the account.
null when no information was present regarding the direction of the transaction.

status'PENDING' | 'PROCESSED' | 'UNCATEGORIZED' | 'null' nullable required

The status of the transaction. We return one of the following values:

PROCESSED (The transaction has been processed by the institution.)
PENDING (The institution clearly states that the transaction has not yet been processed.)
UNCATEGORIZED (deprecated)
null (deprecated)

payment_type'FULL' | 'INSTALLMENT' | 'null' nullable required

The transaction payment type. We return one of the following values:

FULL
INSTALLMENT
null

operation_typestring required

The type of transaction. For example, a PIX payment or a deposit.

Non-nullable: A value must be returned by Brazil's open finance network for non-loan account transactions.

operation_type_additional_infostring nullable required

Additional information regarding the operation_type, if applicable.

mccinteger nullable required

The four-digit (ISO-18245 compliant) Merchant Category Code (MCC) for the transaction. This field is only applicable for credit card transactions.

Example response

[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "internal_identification": "TXpRMU9UQTROMWhZV2xSU1FUazJSMDl",
    "account": {
      "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
      "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
      "institution": {
        "name": "erebor_mx_retail"
      },
      "collected_at": "2022-02-09T08:45:50.406032Z",
      "created_at": "2022-02-09T08:45:50.406032Z",
      "last_accessed_at": "2021-03-09T10:28:40.000Z",
      "category": "CHECKING_ACCOUNT",
      "balance_type": "ASSET",
      "overdraft": {
        "arranged": 5000.5,
        "used": 1000.5,
        "unarranged": 300.1
      },
      "type": "STANDARD_NACIONAL",
      "subtype": "FINANCIAMENTO_HABITACIONAL_SFH",
      "name": "Cuenta Perfiles- M.N. - MXN-666",
      "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": "AGENCY/ACCOUNT",
      "public_identification_value": "0444/45722-0",
      "internal_identification": "92792126019929279212650822221989319252576",
      "credit_data": {
        "collected_at": "2022-02-09T08:45:50.406032Z",
        "credit_limit": 192000.9,
        "limits": [
          {
            "identification_number": "4453",
            "credit_limit": 1000.04,
            "used_amount": 400.04,
            "available_amount": 600,
            "type": "TOTAL_LIMIT",
            "consolidation_type": "INDIVIDUAL",
            "line_name": "CREDITO_A_VISTA",
            "line_name_additional_info": "Informações adicionais e complementares"
          }
        ],
        "cutting_date": "2019-12-11",
        "minimum_payment": 2400.3,
        "network": "MASTERCARD",
        "network_additional_info": "It's an orange card.",
        "cards": [
          {
            "identification_number": "4453"
          }
        ]
      },
      "loan_data": {
        "collected_at": "2022-02-09T08:45:50.406032Z",
        "loan_code": "92792126019929279212650822221989319252576",
        "contract_amount": 202000,
        "total_effective_cost": 209000,
        "loan_type": "HOME_EQUITY",
        "outstanding_balance": 182000,
        "interest_rates": [
          {
            "name": "NOMINAL",
            "type": "MONTHLY",
            "value": 7.85,
            "interest_rate_data": {
              "tax_type": "NOMINAL",
              "rate_type": "SIMPLE",
              "type": "MONTHLY",
              "calculation_base": "30/360",
              "reference_index_type": "FLOATING",
              "reference_index_subtype": "TR_TBF",
              "reference_index_info": "Additional information",
              "pre_fixed_rate": 0.062,
              "post_fixed_rate": 0.062,
              "additional_info": "Additional information"
            }
          }
        ],
        "fees": [
          {
            "value": 5.6,
            "name": "Renovação de cadastro",
            "code": "CADASTRO",
            "fee_charge_type": "SINGLE",
            "fee_charge": "FIXED",
            "rate": 0.062
          }
        ],
        "contracted_charges": [
          {
            "type": "LATE_PAYMENT_INTEREST_FEE",
            "info": "Late fee",
            "rate": 0.062
          }
        ],
        "collaterals": [
          {
            "type": "OPERACOES_GARANTIDAS_PELO_GOVERNO",
            "subtype": "CCR_CONVENIO_CREDITOS_RECIPROCOS",
            "currency": "BRL",
            "amount": 45391.89
          }
        ],
        "balloon_payments": [
          {
            "due_date": "2021-09-06",
            "currency": "BRL",
            "amount": 45391.89
          }
        ],
        "installments_contract_term_frequency": "MONTH",
        "installment_frequency": "MONTHLY",
        "installment_frequency_info": "Both the term and requency are the same.",
        "first_installment_due_date": "2020-03-01",
        "number_of_installments_total": 60,
        "number_of_installments_outstanding": 48,
        "number_of_installments_paid": 32,
        "number_of_installments_past_due": 2,
        "disbursement_dates": [
          "2021-09-23"
        ],
        "settlement_date": "2021-09-23",
        "contract_start_date": "2020-03-01",
        "contract_end_date": "2027-10-01",
        "contract_remaining_frequency": "MONTH",
        "contract_remaining_total": 20,
        "amortization_schedule": "SEM_SISTEMA_AMORTIZACAO",
        "amortization_schedule_info": "No need for a schedule.",
        "consignee_id": "60500998000135",
        "contract_number": "1324926521496"
      }
    },
    "collected_at": "2022-02-09T08:45:50.406032Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "value_date": "2019-10-23",
    "transacted_at": "2024-02-20T12:29:03.374Z",
    "accounting_date": "2019-10-23",
    "inferred_accounting_date": "2019-10-23",
    "amount": 2145.45,
    "local_currency_amount": 7623.64,
    "currency": "BRL",
    "description": "SEVEN BUDDHAS RFC:XXXXXXXXXX",
    "merchant": {
      "logo": "https://logo.clearbit.com/asesor-contable.es",
      "website": "https://merchants-r-us.com",
      "merchant_name": "Merchants R Us Global"
    },
    "category": "Income & Payments",
    "subcategory": "Freelance",
    "type": "INFLOW",
    "status": "PROCESSED",
    "credit_card_data": {
      "collected_at": "2022-02-09T08:45:50.406032Z",
      "bill_name": "apr-2020",
      "bill_due_date": "2023-06-17",
      "bill_internal_identification": "927921260199292792126508222219893192525A6",
      "bill_amount": 300,
      "card_number": "4453",
      "fee_type": "NATIONAL_WITHDRAWAL",
      "fee_type_additional_info": "ATM withdrawal in Curitiba.",
      "credits_type": "BILL_INSTALLMENT_PAYMENT",
      "credits_type_additional_info": "Some additional information.",
      "installment_identifier": "PARCELA_896",
      "number_of_installments": 4,
      "credit_card_bill": {
        "id": "8e9d13c2-af41-4a49-b43e-2da012bd1d11",
        "internal_identification": "92792126019929279212650822221989319252576"
      }
    },
    "counterparty": {
      "type": "INDIVIDUAL",
      "document_number": "73677831148",
      "clearing_code": "001",
      "agency": "6272",
      "check_digit": "7",
      "number": "24550245"
    },
    "loan_data": {
      "is_detached": true,
      "installment_id": "WGx0aExYcEJMVm93TFRsZFcyRXRla0V0V2pBdE9Wd3RYWH",
      "fees": [
        {
          "name": "Reavaliação periódica do bem",
          "code": "aval_bem",
          "amount": 8903.77
        }
      ],
      "charges": [
        {
          "type": "MULTA_ATRASO_PAGAMENTO",
          "info": "Late payment charge.",
          "amount": 8903.77
        }
      ]
    },
    "payment_type": "FULL",
    "operation_type": "TRANSFERENCIA_MESMA_INSTITUICAO",
    "operation_type_additional_info": "Internal transfer.",
    "mcc": 5137
  }
]