# Get your account movements

Get a statement of the movements that have occurred within your account.

Endpoint: GET /account_movements
Version: 1.0.0
Security: ApiKeyAuth, ApiKeySecret

## Query parameters:

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `limit` (integer)
    Indicates how many results to return per page. By default we return 20 results
per page.


ℹ️ The minimum number of results returned per page is 1 and the maximum is 100.
If you enter a value greater than 100, our API will default to the maximum
value (100).
    Example: 15

  - `from_created_date` (string)
    Filter movements created on or after this date, in YYYY-MM-DD format.

  - `until_created_date` (string)
    Filter movements created on or before this date, in YYYY-MM-DD format.

  - `type` (string)
    Filter movements by on of these types (credit or debit).
    Enum: "credit", "debit"

  - `withdrawal_id` (string)
    Filter movements by this withdrawal ID.

  - `reason` (array)
    Filter movements by one or more of the following reasons:
- withdrawal
- payments_service_charge
- payments_service_fee
- payments_service_fee_tax
- payments_service_chargeback
- penny_validation_fee
- penny_validation_fee_tax
- adjustment
    Enum: "withdrawal", "payments_service_charge", "payments_service_fee", "payments_service_fee_tax", "payments_service_chargeback", "penny_validation_fee", "penny_validation_fee_tax", "adjustment"

## Response 200 fields (application/json):

  - `items` (array)
    An array of movement objects.

  - `items.id` (string)
    The unique identifier created by Belvo used to reference the movement.
    Example: "38848ec1-79bb-4827-87b1-819f186ad273"

  - `items.createdDate` (string)
    The ISO-8601 timestamp when the movement was created in Belvo's database.
    Example: "2025-05-14T16:20:00Z"

  - `items.lastUpdatedDate` (string)
    The ISO-8601 timestamp when information regarding the movement was last updated.
    Example: "2025-05-14T16:25:00Z"

  - `items.chargebackDate` (string,null)
    The ISO-8601 timestamp when Belvo marked the related payment request as chargeback (only applicable if the movement was caused by a chargeback (reason = payments_service_chargeback)). Chargebacks recorded before bankChargebackDate was introduced hold the date reported by the banking institution here instead.

  - `items.bankChargebackDate` (string,null)
    The date the banking institution reported for the chargeback, in YYYY-MM-DD format, to reconcile against its statements (only applicable if the movement was caused by a chargeback (reason = payments_service_chargeback)). null for chargebacks recorded before this field was introduced.

  - `items.type` (string)
    The type of movement. Can be either: 
  - credit (money deposited into your account)
  - debit (money withdrawn from your account)
    Enum: "credit", "debit"

  - `items.reason` (string)
    The reason for the movement. Can be either:

  - withdrawal: The balance was transferred to the merchant’s account.
  - payments_service_charge: A successful charge occurred.
  - payments_service_fee : Belvo’s fee for a successful or failed charge.
  - payments_service_fee_tax: The tax on the payments_service_fee.
  - payments_service_chargeback: A chargeback occurred.
  - penny_validation_fee: Belvo’s fee for a penny validation.
  - penny_validation_fee_tax: The tax on the penny_validation_fee.
  - adjustment: Used in the case of any other movement required to adjust the merchant's balance.
    Enum: "withdrawal", "payments_service_charge", "payments_service_fee", "payments_service_fee_tax", "payments_service_chargeback", "penny_validation_fee", "penny_validation_fee_tax", "adjustment"

  - `items.amount` (number)
    The amount of the movement.
    Example: 125.5

  - `items.currency` (string)
    The three-letter currency code (ISO-4217).
    Example: "MXN"

  - `items.paymentRequest` (string)
    The ID of the associated payment request.
    Example: "136771f0-13d7-4725-ae0b-e25e9055716d"

  - `items.paymentRequestReference` (string,null)
    A reference for the payment request.
    Example: "INV-2025-001"

  - `items.paymentRequestDisplayReference` (string,null)
    A reference description displayed in your customer's bank statement.
    Example: "Payment to ACME Corp"

  - `items.customerName` (string)
    The movement's associated customer's name.
    Example: "Juan Pérez"

  - `items.customerDocumentType` (string)
    The document type of the customer. For 🇲🇽 Mexico, can be one of the following:
  - mx_rfc: Tax Identification Number (Registro Federal de Contribuyentes)
  - mx_curp: Unique Population Registry Code (Clave Única de Registro de Población)
    Enum: "mx_rfc", "mx_curp"

  - `items.customerDocumentNumber` (string)
    The document number of the customer.
    Example: "HEGJ850506SX1"

  - `items.paymentMethodType` (string)
    The type of payment method. For Mexico, this value is set to bank_account.
    Enum: "bank_account"

  - `items.accountNumber` (string)
    The account number of your customer.
    Example: "012345678901234567"

  - `items.withdrawalId` (string,null)
    Belvo's Internal ID for movements where the reason is withdrawal.
    Example: "9e637645-efe8-4fb7-a442-fa2eeb5ad606"

  - `items.withdrawalCreatedDate` (string,null)
    The ISO-8601 timestamp for movements where the reason is withdrawal.
    Example: "2025-05-10T14:30:00Z"

  - `items.withdrawalExtra` (object,null)
    A customizable object containing additional key-value pairs that you requested Belvo include for movements where the reason is withdrawal.
    Example: {"reference_id":"ABC123","withdrawal_method":"bank_transfer"}

  - `metadata` (object)
    Additional metadata regarding the paginated result set.

  - `metadata.totalItems` (integer)
    The total number of items in the paginated result set.
    Example: 100

  - `metadata.itemCount` (integer)
    The number of items in the current page.
    Example: 10

  - `metadata.itemsPerPage` (integer)
    The number of items requested per page.
    Example: 10

  - `metadata.totalPages` (integer)
    The total number of pages in the paginated result set.
    Example: 10

  - `metadata.currentPage` (integer)
    The current page number.
    Example: 1

  - `links` (object)
    Links to navigate the paginated result set.

  - `links.first` (string)
    The URL to the first page of the paginated result set.
    Example: "/{resource}?limit=20"

  - `links.last` (string)
    The URL to the last page of the paginated result set.
    Example: "/{resource}?page=4&limit=20"

  - `links.next` (string)
    The URL to the next page of the paginated result set.
    Example: "/{resource}?page=3&limit=20"

  - `links.previous` (string)
    The URL to the previous page of the paginated result set.
    Example: "/{resource}?page=2&limit=20"

## Response 400 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 400

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Bad Request"

  - `message` (any)
    A short description of the error, indicating what is wrong with the request.
> Note: We return either a string or an array of strings, depending on the validation error(s). 

The description can be (among others):

  - id must be a UUID
  - Not enough balance
  - amount is not a valid decimal number.
  - currency must be one of the following values: cop, mxn, usd
  - reference must be a string
  - Customer not found for merchant
  - documentType is a required field
    Example: "id must be a UUID"

## Response 401 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 401

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Unauthorized"

  - `message` (string)
    A short description of the error, indicating what is wrong with the request.
In the case of a 401 Unauthorized error, the message is:

  - Unauthorized credentials
    Example: "Unauthorized credentials"