# List all Payment Authorizations

List all Payment Authorizations associated with your Belvo account.

Endpoint: GET /payments/br/payment-authorizations/
Version: 1.223.0
Security: basicAuth

## Header parameters:

  - `X-Belvo-API-Resource-Version` (string)
    Header indicating which version of the Payment API you want to use. Currently this is only applicable for Bank Accounts, Customers, and Payment Authorizations in Brazil. In the case that you are using our Payment Authorizations product (including Smart Transfers authorizations and their Charges), then you must send through this header set to Payments-BR.V2.
    Enum: "Payments-BR.V2"

## Query parameters:

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

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

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

  - `id__in` (array)
    Return information for these resource ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `amount` (number)
    Return results only for this value.
    Example: 1000.02

  - `amount__gt` (number)
    Return results only for more than this amount.
    Example: 1000.02

  - `amount__gte` (number)
    Return results only for and more than this amount.
    Example: 1000.02

  - `amount__lt` (number)
    Return results only for less than this amount.
    Example: 1000.02

  - `amount__lte` (number)
    Return results only for this amount or less.
    Example: 1000.02

  - `amount__range` (array)
    Return results between this amount range. The first value indicates the start of the range and the second value indicates the end of the range.
    Example: [100,5000]

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

  - `customer` (string)
    The customer.id you want to get results for.
    Example: "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d"

  - `customer__in` (array)
    One or more customer.ids that you want to get results for.
    Example: ["cb320adc-9a6b-4224-933a-5b08cf771ac7"]

  - `external_id` (string)
    Return objects with this external ID.
    Example: "295ebb46-65b8-47de-85cd-34ffbc327c09"

  - `external_id__in` (array)
    Return objects with these external IDs.
    Example: ["446bdd9f-5b3e-4c05-9159-7a5c87cfc810"]

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

Note:

This filter supports both full and partial search queries, with a minimum of three characters required.

For example, searching for trai may match the following values:

  - Awesome training sneakers 
  - Training equipment

Searching for car may match the following values:

        - Carlos Vives
        - Carmen Domínguez 
        - carlos.vives@musicabrazil.br
    Example: "trai"

  - `updated_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `updated_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `updated_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `updated_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `updated_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `updated_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908&page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of Payment Authorization objects.

  - `results.id` (string, required)
    The Belvo ID for the Payment Authorization.
    Example: "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432"

  - `results.created_at` (string, required)
    The ISO-8601 timestamp of when the Payment Authorization was created.
    Example: "2025-05-20T09:55:02Z"

  - `results.updated_at` (string, required)
    The ISO-8601 timestamp of when the Payment Authorization was last updated.
    Example: "2025-05-20T09:55:02Z"

  - `results.status` (string, required)
    The current status of the Payment Authorization. Can be one of:
  - AWAITING_AUTHORIZATION: the authorization was created and is waiting for your user to approve it at their institution (using the payment_method_configuration.authorization_url).
  - PARTIALLY_ACCEPTED: your user approved the authorization, but the account requires approval from additional account holders before it becomes AUTHORIZED.
  - AUTHORIZED: the authorization was approved. For Smart Transfers, you can now create Charges.
  - FAILED: the authorization was rejected by the user or the institution, or could not be created. See status_reason_code for the reason.
  - CONSUMED: the authorization was fully used and cannot be used for further payments. For Smart Transfers, this happens when the total_allowed_amount is used up, or when the authorization expires. Reaching a periodic_limits cap (day, week, month or year) does not consume the authorization: it only blocks new Charges until that window resets.
  - REVOKED: the authorization was revoked by the payer, by the beneficiary, or by you using the Cancel a Payment Authorization endpoint. See status_reason_code for details.
    Enum: "AWAITING_AUTHORIZATION", "PARTIALLY_ACCEPTED", "AUTHORIZED", "FAILED", "CONSUMED", "REVOKED"

  - `results.status_reason_code` (string,null, required)
    A code indicating the reason for the current status, when the status is FAILED or REVOKED. null for other statuses.

For PIX_OF_SMART_TRANSFERS authorizations, the possible codes are:
  - USER_REJECTED: the payer rejected the authorization at their institution.
  - AUTHORIZATION_EXPIRED: the payer did not approve the authorization within the allowed time.
  - BANK_USER_MISMATCH: the user who logged in to the institution is not the payer of the authorization.
  - IDENTIFIER_MISMATCH: the payer's CPF or CNPJ does not match the holder of the account at the institution.
  - FEATURE_NOT_ENABLED_BY_INSTITUTION: the institution does not support Smart Transfers.
  - INSUFFICIENT_PERMISSION: the payer does not have enough permissions on the account to approve the authorization.
  - SAME_ORIGIN_DESTINATION_ACCOUNTS: the payer account and the beneficiary account are the same account.
  - ACCOUNT_NOT_ALLOWED: the payer account does not allow payments.
  - INSUFFICIENT_FUNDS: the institution rejected the authorization because the payer account has insufficient funds.
  - AMOUNT_OVER_LIMIT: the requested limits exceed the limits set by the institution.
  - OPEN_FINANCE_NETWORK_FAILURE: an infrastructure failure in the Open Finance network prevented the authorization.
  - NO_REASON_PROVIDED: the institution rejected or revoked the authorization without giving a reason.
  - REJECTED_UNKNOWN: the institution rejected the authorization for a reason not covered by the other codes.
  - PAYER_REVOKED_AUTHORIZATION: the payer revoked the authorization (status REVOKED).
  - BENEFICIARY_REVOKED_AUTHORIZATION: the beneficiary revoked the authorization (status REVOKED).
  - REVOKED_UNKNOWN: the authorization was revoked for a reason not covered by the other codes (status REVOKED).
  - UNEXPECTED_ERROR: Belvo could not create the authorization at the institution. Contact support with the request ID.

  - `results.status_reason_message` (string,null, required)
    A human-readable message explaining the reason for the current status (when applicable).

  - `results.status_updated_at` (string, required)
    The ISO-8601 timestamp of when the status was last updated.
    Example: "2025-05-20T09:55:02Z"

  - `results.authorized_at` (string,null, required)
    The ISO-8601 timestamp of when the Payment Authorization was authorized by the user.
    Example: "2025-05-20T09:55:02Z"

  - `results.external_id` (string,null, required)
    The merchant's internal ID for the authorization.
    Example: "c169a8a9-e9f5-48db-9f4a-818caef9356b"

  - `results.description` (string, required)
    An internal description used by the merchant only.
    Example: "Internal description used by the merchant only"

  - `results.return_url` (string, required)
    The URL where the user will be redirected after authorization.
    Example: "https://merchant.com/return"

  - `results.expiration_date_time` (string,null)
    The ISO-8601 timestamp after which the authorization can no longer be used. null if no expiration date was set.
    Example: "2027-10-31T23:59:59Z"

  - `results.payment_method` (string, required)
    The payment method that was authorized. Can be one of:
  - PIX_OF_IMMEDIATE: a single Pix payment, made immediately.
  - PIX_OF_SCHEDULED: a single Pix payment, scheduled for a future date.
  - PIX_OF_SMART_TRANSFERS: Smart Transfers, on-demand transfers between accounts held by the same person or business. You create each transfer as a Charge.
    Enum: "PIX_OF_IMMEDIATE", "PIX_OF_SCHEDULED", "PIX_OF_SMART_TRANSFERS"

  - `results.payer` (object, required)
    Details regarding the payer.

  - `results.payer.customer` (string)
    The Belvo ID for the customer.
    Example: "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044"

  - `results.payer.institution` (string)
    The Belvo ID of the institution that the payer will use.
    Example: "770932b4-8f1f-4b0f-8470-1c605903fdb2"

  - `results.payer.representative_identifier` (string,null)
    In the case that the customer is a business, the CPF of the representative authorized to make payments. null for individual customers.
    Example: "12345678901122"

  - `results.payer.bank_account` (object,null)
    The payer's account that the user selected at their institution when approving the authorization, with sensitive values masked. null until the authorization is AUTHORIZED, or if the institution did not return the account.

  - `results.payer.bank_account.holder` (object)
    The holder of the payer's account.

  - `results.payer.bank_account.holder.identifier` (string)
    The CPF or CNPJ of the account holder, masked.
    Example: "***456789**"

  - `results.payer.bank_account.details` (object)
    Details of the payer's account.

  - `results.payer.bank_account.details.account_type` (string)
    The type of the payer's account. Can be one of:
  - CHECKINGS: checking account (Conta Corrente).
  - SAVINGS: savings account (Conta Poupança).
  - SALARY: salary account (Conta Salário).
  - PAYMENTS: prepaid payment account (Conta de Pagamento Pré-Paga).
    Enum: "CHECKINGS", "SAVINGS", "SALARY", "PAYMENTS"

  - `results.payer.bank_account.details.agency` (string)
    The agency (branch) number of the payer's account. All but the last 4 characters are masked.
    Example: "0001"

  - `results.payer.bank_account.details.code` (string)
    The ISPB code of the institution that holds the payer's account.
    Example: "12345678"

  - `results.payer.bank_account.details.number` (string)
    The payer's account number. All but the last 4 characters are masked.
    Example: "***4567"

  - `results.beneficiary` (object, required)
    Details regarding the beneficiary of the payment.

  - `results.beneficiary.type` (string)
    The type of beneficiary account.
    Enum: "BANK_ACCOUNT"

  - `results.beneficiary.target` (string)
    The Belvo ID of the bank account that will receive funds.
    Example: "b6278377-f710-4d1a-a026-7bab757256d0"

  - `results.payment_method_configuration` (object, required)
    Configuration details for the payment method.

  - `results.charges` (array, required)
    A list of Charge IDs associated with the Payment Authorization.
    Example: ["7d159b21-9f25-4365-9fa2-734d20797819"]

  - `results.metadata` (object)
    Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the payment intent.

{% admonition type="info" name="Metadata Limitations" %}
  You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.
{% /admonition %}
    Example: {"internal_reference_id":"GGq73487w2"}

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"