# Obtén los movimientos de tu cuenta

Obtén un estado de los movimientos que han ocurrido dentro de tu cuenta.

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

## Query parameters:

  - `page` (integer)
    Un número de página dentro del conjunto de resultados paginados.
    Example: 1

  - `limit` (integer)
    Indica cuántos resultados devolver por página. Por defecto, devolvemos 20 resultados por página.

ℹ️ El número mínimo de resultados devueltos por página es 1 y el máximo es 100. Si introduces un valor mayor que 100, nuestra API usará por defecto el valor máximo (100).
    Example: 15

  - `from_created_date` (string)
    Filtrar movimientos creados en o después de esta fecha, en formato YYYY-MM-DD.

  - `until_created_date` (string)
    Filtrar movimientos creados en o antes de esta fecha, en formato YYYY-MM-DD.

  - `type` (string)
    Filtrar movimientos por uno de estos tipos (credit o debit).
    Enum: "credit", "debit"

  - `withdrawal_id` (string)
    Filtrar movimientos por este ID de retiro.

  - `reason` (array)
    Filtrar movimientos por una o más de las siguientes razones:
- 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)
    Un arreglo de objetos de movimiento.

  - `items.id` (string)
    El identificador único creado por Belvo utilizado para referenciar el movimiento.
    Example: "38848ec1-79bb-4827-87b1-819f186ad273"

  - `items.createdDate` (string)
    La marca de tiempo ISO-8601 cuando el movimiento fue creado en la base de datos de Belvo.
    Example: "2025-05-14T16:20:00Z"

  - `items.lastUpdatedDate` (string)
    La marca de tiempo ISO-8601 cuando se actualizó por última vez la información sobre el movimiento.
    Example: "2025-05-14T16:25:00Z"

  - `items.chargebackDate` (string,null)
    La marca de tiempo ISO-8601 cuando Belvo marcó la solicitud de pago relacionada como chargeback (solo aplicable si el movimiento fue causado por un chargeback (reason = payments_service_chargeback)). Los chargebacks registrados antes de que se introdujera bankChargebackDate mantienen aquí la fecha reportada por la institución bancaria.

  - `items.bankChargebackDate` (string,null)
    La fecha que la institución bancaria reportó para la devolución de cargo, en formato YYYY-MM-DD, para conciliar con sus estados de cuenta (solo aplicable si el movimiento fue causado por una devolución de cargo (reason = payments_service_chargeback)). null para devoluciones de cargo registradas antes de que se introdujera este campo.

  - `items.type` (string)
    El tipo de movimiento. Puede ser:
  - credit (dinero depositado en tu cuenta)
  - debit (dinero retirado de tu cuenta)
    Enum: "credit", "debit"

  - `items.reason` (string)
    La razón del movimiento. Puede ser:

  - withdrawal: El saldo fue transferido a la cuenta del comerciante.
  - payments_service_charge: Se realizó un cargo exitoso.
  - payments_service_fee: La comisión de Belvo por un cargo exitoso o fallido.
  - payments_service_fee_tax: El impuesto sobre la payments_service_fee.
  - payments_service_chargeback: Ocurrió un contracargo.
  - penny_validation_fee: La comisión de Belvo por una validación de centavos.
  - penny_validation_fee_tax: El impuesto sobre la penny_validation_fee.
  - adjustment: Usado en el caso de cualquier otro movimiento necesario para ajustar el saldo del comerciante.
    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)
    La cantidad del movimiento.
    Example: 125.5

  - `items.currency` (string)
    El código de moneda de tres letras (ISO-4217).
    Example: "MXN"

  - `items.paymentRequest` (string)
    El ID de la solicitud de pago asociada.
    Example: "136771f0-13d7-4725-ae0b-e25e9055716d"

  - `items.paymentRequestReference` (string,null)
    Una referencia para la solicitud de pago.
    Example: "INV-2025-001"

  - `items.paymentRequestDisplayReference` (string,null)
    Una descripción de referencia que se muestra en el estado de cuenta bancario de su cliente.
    Example: "Payment to ACME Corp"

  - `items.customerName` (string)
    El nombre del cliente asociado al movimiento.
    Example: "Juan Pérez"

  - `items.customerDocumentType` (string)
    El tipo de documento del cliente. Para 🇲🇽 México, puede ser uno de los siguientes:
  - mx_rfc: Número de Identificación Fiscal (Registro Federal de Contribuyentes)
  - mx_curp: Clave Única de Registro de Población (Clave Única de Registro de Población)
    Enum: "mx_rfc", "mx_curp"

  - `items.customerDocumentNumber` (string)
    El número de documento del cliente.
    Example: "HEGJ850506SX1"

  - `items.paymentMethodType` (string)
    El tipo de método de pago. Para México, este valor se establece en bank_account.
    Enum: "bank_account"

  - `items.accountNumber` (string)
    El número de cuenta de su cliente.
    Example: 12345678901234568

  - `items.withdrawalId` (string,null)
    ID interno de Belvo para movimientos donde el reason es withdrawal.
    Example: "9e637645-efe8-4fb7-a442-fa2eeb5ad606"

  - `items.withdrawalCreatedDate` (string,null)
    La marca de tiempo ISO-8601 para movimientos donde el reason es withdrawal.
    Example: "2025-05-10T14:30:00Z"

  - `items.withdrawalExtra` (object,null)
    Un objeto personalizable que contiene pares clave-valor adicionales que solicitaste a Belvo incluir para movimientos donde el reason es withdrawal.
    Example: {"reference_id":"ABC123","withdrawal_method":"bank_transfer"}

  - `metadata` (object)
    Metadatos adicionales sobre el conjunto de resultados paginados.

  - `metadata.totalItems` (integer)
    El número total de elementos en el conjunto de resultados paginados.
    Example: 100

  - `metadata.itemCount` (integer)
    El número de elementos en la página actual.
    Example: 10

  - `metadata.itemsPerPage` (integer)
    El número de elementos solicitados por página.
    Example: 10

  - `metadata.totalPages` (integer)
    El número total de páginas en el conjunto de resultados paginados.
    Example: 10

  - `metadata.currentPage` (integer)
    El número de página actual.
    Example: 1

  - `links` (object)
    Enlaces para navegar por el conjunto de resultados paginados.

  - `links.first` (string)
    La URL a la primera página del conjunto de resultados paginados.
    Example: "/{resource}?limit=20"

  - `links.last` (string)
    La URL a la última página del conjunto de resultados paginados.
    Example: "/{resource}?page=4&limit=20"

  - `links.next` (string)
    La URL a la siguiente página del conjunto de resultados paginados.
    Example: "/{resource}?page=3&limit=20"

  - `links.previous` (string)
    La URL a la página anterior del conjunto de resultados paginados.
    Example: "/{resource}?page=2&limit=20"

## Response 400 fields (application/json):

  - `statusCode` (integer)
    El código de estado HTTP para este error.
    Example: 400

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Bad Request"

  - `message` (any)
    Una breve descripción del error, indicando qué está mal con la solicitud.
> Nota: Devolvemos una cadena o un arreglo de cadenas, dependiendo del/los error(es) de validación.

La descripción puede ser (entre otras):

  - 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)
    El código de estado HTTP para este error.
    Example: 401

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Unauthorized"

  - `message` (string)
    Una breve descripción del error, indicando qué está mal con la solicitud. En el caso de un error 401 Unauthorized, el mensaje es:

  - Unauthorized credentials
    Example: "Unauthorized credentials"