# List all payment requests

List all payment requests associated with your account

Endpoint: GET /payment_requests
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

  - `search` (string)
    Return results that match the reference you searched for. 


Note:
This filter supports both full and partial search queries. For example, searching for trai may match the following values (extacted
from the reference field)):

  - Awesome training sneakers 
  - Training equipment
    Example: "trai"

  - `customer_id` (string)
    The unique identifier created by Belvo used to reference the customer.
    Example: "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"

  - `order` (string)
    Return results in either ascending (oldest to newest) or descending (newest to oldest) order, according to the createdDate.

Can be either:
  - asc for ascending order
  - desc for descending order
    Enum: "asc", "desc"

  - `start_date` (string)
    Return items with a createdDate greater than or equal to the specified date. The date must be in the format YYYY-MM-DD.
    Example: "2024-01-01"

  - `end_date` (string)
    Return items with a createdDate less than or equal to the specified date. The date must be in the format YYYY-MM-DD.
    Example: "2024-01-30"

## Response 200 fields (application/json):

  - `items` (array)
    An array of payment request objects.

  - `items.id` (string)
    The unique identifier created by Belvo used to reference the payment request.
    Example: "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"

  - `items.createdDate` (string,null)
    The ISO-8601 timestamp when the payment request was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `items.lastUpdatedDate` (string,null)
    The ISO-8601 timestamp when information regarding the payment request was last updated.
    Example: "2022-02-09T08:45:50.406032Z"

  - `items.chargebackDate` (string,null)
    The ISO-8601 timestamp when Belvo marked the payment request as chargeback. Only present when status is chargeback. Chargebacks recorded before bankChargebackDate was introduced hold the date reported by the financial institution here instead.
    Example: "2022-02-11T17:42:11.123Z"

  - `items.bankChargebackDate` (string,null)
    The date the financial institution reported for the chargeback, in YYYY-MM-DD format. Use it to reconcile against the financial institution's statements. null when the payment request is not a chargeback or was charged back before this field was introduced.
    Example: "2022-02-10"

  - `items.status` (string)
    The status of the payment request. Can be either:
  - initial
    The payment request has been created.
  - processing
    The charge files have been generated for the payment request. Awaiting response from the financial institution.
  - successful
    The financial institution has confirmed the payment request and the funds have been transferred.
  - failed
    The financial institution has reported an error for the payment request and no funds have been transferred.
  - canceled
    The request was canceled. This is only possible if the payment request has not transitioned to the processing status.
  - chargeback
    The financial institution reversed a payment request that was successful.
    Enum: "initial", "processing", "successful", "failed", "canceled", "chargeback"

  - `items.failedReason` (string,null)
    The financial institution's failure code.

  - `items.failedReasonMessage` (string,null)
    The financial institution's failure message, describing the reason for the failure.

  - `items.amount` (string)
    The amount to debit from the customer.
    Example: "100000.00"

  - `items.currency` (string)
    The three-letter ISO 4217 currency code of the transaction. At the moment, we only support mxn.
    Enum: "mxn"

  - `items.customer` (string)
    The unique identifier created by Belvo used to reference the customer.
    Example: "3118128a-6792-4b06-bd61-4acf6f6ad6b5"

  - `items.customerName` (string)
    The name of the customer.
    Example: "Carlos Vives"

  - `items.reference` (string)
    A reference for the payment request.
    Example: "Monthly gym subscription"

  - `items.paymentMethod` (object)

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

  - `items.paymentMethod.details` (object)
    Details regarding the bank account associated with the payment method.

  - `items.paymentMethod.details.accountNumber` (string)
    The bank account number.
    Example: "445566790"

  - `items.paymentMethod.details.accountType` (string)
    The bank account type. Can be either:
  - savings
  - checking
  - debit_card
    Enum: "savings", "checking", "debit_card"

  - `items.paymentMethod.details.bank` (string)
    The name of the Mexican bank where the account is held.


For a full list of institutions, please see our dedicated Payment Institutions page.

  - `items.loanInformation` (object)
    (Optinal) Metadata about the loan associated with the payment request.

  - `items.loanInformation.reference` (string)
    Your reference for the loan associated with the payment request.
    Example: "Camera Purchase 1432"

  - `items.loanInformation.disbursementDate` (string)
    The date when the loan was disbursed, in YYYY-MM-DD format.
    Example: "2025-01-01"

  - `items.loanInformation.installmentNumber` (integer)
    The number of the installment being paid.
    Example: 1

  - `items.loanInformation.installmentAmount` (number)
    The amount of the installment being paid.
    Example: 100.02

  - `items.loanInformation.installmentDueDate` (string)
    The due date of the installment being paid, in YYYY-MM-DD format.
    Example: "2025-03-01"

  - `items.loanInformation.totalAmount` (number)
    The total amount of the loan.
    Example: 12000.24

  - `items.loanInformation.totalInstallments` (integer)
    The total number of installments for the loan.
    Example: 12

  - `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"