---
title: "Create a new Payment Authorization"
method: POST
path: "/payments/br/payment-authorizations/"
tags: ["Payment Authorizations (Brazil)"]
---

# Create a new Payment Authorization

`POST /payments/br/payment-authorizations/`

{% admonition type="warning" name="Coming Soon" %}
  This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}

Create a Payment Authorization.

## Headers

- `X-Belvo-API-Resource-Version` 'Payments-BR.V2'

## Request body

- union
  - CreatePaymentAuthorizationImmediate — Create an Immediate Payment Authorization.
    - `payment_method` 'PIX_OF_IMMEDIATE', required — The payment method to authorize. For immediate one-time payments, this must be set to `PIX_OF_IMMEDIATE`.
    - `description` string, required — An internal description for the merchant.
    - `external_id` string, uuid — (Highly Recommended) The merchant's internal ID for the authorization.
    - `return_url` string, uri, required — The URL that the user should be redirected to after authorizing the payment in the institution.
    - `payer` object, required — Details regarding the payer.
      - `customer` union, required — Details of the customer making payments to the beneficiary. You can either provide the customer's CPF or CNPJ, or their Belvo ID. If you provide the Belvo ID, it must be a UUID of a customer that has already been created in Belvo. If you provide the CPF or CNPJ, we will check if the customer exists in Belvo. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.
        - CustomerObject — Details of the customer making payments to the beneficiary. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.
          - `identifier` string, required — The CPF or CNPJ of the customer. For CPF, must be 11 characters. For CNPJ, must be 14 characters.
          - `name` string, required — The full name of the customer.
          - `external_id` string, uuid — An additional unique identifier for the resource for internal purposes. {% admonition type="success" name="Highly Recommended" %} We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes. {% /admonition %}
        - string, uuid — The Belvo ID of previously created customer that will make the payments to the beneficiary. {% admonition type="warning" name="Customer from Payments-BR.V2" %} The provided customer ID must be one that was created using the `Payments-BR.V2` version of our API. For example, using either the Bank Account Details option when created the Payment Authorization, or the Create a Customer endpoint with the `X-Belvo-API-Resource-Version: Payments-BR.V2` header. If you provide an ID that is not `Payments-BR.V2` version compliant, you will receive the following error: `The customer does not exist or is invalid.`. {% /admonition %}
      - `institution` string — The Belvo ID of the institution that they payer will use to pay for the merchant's service. To get the Belvo ID of an institution, use the [Institutions endpoint](https://developers.belvo.com/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil).
      - `representative_identifier` string — In the case that the customer is a business, this is the CPF of the representative authorized to make payments for the business.
    - `beneficiary` object, required — Details regarding the beneficiary of the payment.
      - `type` 'BANK_ACCOUNT', required — The type of beneficiary account. At present, this must be set to `BANK_ACCOUNT`.
      - `target` union, required — Details regarding the bank account that will receive funds. You can either provide the complete details of the bank account or the Belvo ID. If you provide the complete bank account details, we will check if the bank account exists in Belvo. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID.
        - BankAccountObject — Details of the bank account to be registered. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID.
          - `holder` object, required — Details of the account holder.
            - `identifier` string, required — The CPF (11 digits) or CNPJ (14 digits) of the account holder.
            - `name` string, required — The full name or business name of the account holder.
          - `details` object, required — Details of the bank account.
            - `account_type` 'CHECKINGS' | 'SAVINGS' | 'PAYMENTS', required — The type of bank account. Can be either: - `CHECKINGS` (also known as Conta Corrente in Brazil) - `SAVINGS` (also known as Conta Poupança in Brazil) - `PAYMENTS` (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
            - `agency` string, required — The agency (branch number) of the institution where the account was created.
            - `institution` string, uuid, required — The Belvo ID of the financial institution.
            - `number` string, required — The bank account number. {% admonition type="info" name="Valid Account Number characters" %} You can only send through numbers (`^[0-9]+$`) in the string. For example, `"457220"` is a valid bank account number, while "`45722-0`" is invalid as it contains a hyphen (`-`). {% /admonition %}
          - `external_id` string, uuid — An additional unique identifier for the resource for internal purposes. {% admonition type="success" name="Highly Recommended" %} We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes. {% /admonition %}
          - `metadata` MetadataPayments — 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 %}
        - string, uuid — The Belvo ID of the bank account you previously registered that will receive funds. {% admonition type="warning" name="Bank Account from Payments-BR.V2" %} The provided bank account ID must be one that was created using the `Payments-BR.V2` version of our API. For example, using either the Bank Account Details option when created the Payment Authorization, or the Register Bank Account endpoint with the `X-Belvo-API-Resource-Version: Payments-BR.V2` header. If you provide an ID that is not `Payments-BR.V2` version compliant, you will receive the following error: `The bank account does not exist or is invalid.`. {% /admonition %}
    - `payment_method_configuration` object, required — Details regarding the payment.
      - `amount` number, float, required — The amount that your customer will be charged.
      - `statement_description` string, required — The description that will appear on your customer's bank statement.
    - `metadata` MetadataPayments — 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 %}
  - CreatePaymentAuthorizationScheduled — Create a Scheduled Payment Authorization.
    - `payment_method` 'PIX_OF_SCHEDULED', required — The payment method to authorize. For scheduled one-time payments, this must be set to `PIX_OF_SCHEDULED`.
    - `description` string, required — An internal description for the merchant.
    - `external_id` string, uuid — (Highly Recommended) The merchant's internal ID for the authorization.
    - `return_url` string, uri, required — The URL that the user should be redirected to after authorizing the payment in the institution.
    - `payer` object, required — Details regarding the payer.
      - `customer` union, required — Details of the customer making payments to the beneficiary. You can either provide the customer's CPF or CNPJ, or their Belvo ID. If you provide the Belvo ID, it must be a UUID of a customer that has already been created in Belvo. If you provide the CPF or CNPJ, we will check if the customer exists in Belvo. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.
        - CustomerObject — Details of the customer making payments to the beneficiary. If the customer exists, we return their Belvo ID. If not, we create a new customer and return the newly assigned Belvo ID.
          - `identifier` string, required — The CPF or CNPJ of the customer. For CPF, must be 11 characters. For CNPJ, must be 14 characters.
          - `name` string, required — The full name of the customer.
          - `external_id` string, uuid — An additional unique identifier for the resource for internal purposes. {% admonition type="success" name="Highly Recommended" %} We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes. {% /admonition %}
        - string, uuid — The Belvo ID of previously created customer that will make the payments to the beneficiary. {% admonition type="warning" name="Customer from Payments-BR.V2" %} The provided customer ID must be one that was created using the `Payments-BR.V2` version of our API. For example, using either the Bank Account Details option when created the Payment Authorization, or the Create a Customer endpoint with the `X-Belvo-API-Resource-Version: Payments-BR.V2` header. If you provide an ID that is not `Payments-BR.V2` version compliant, you will receive the following error: `The customer does not exist or is invalid.`. {% /admonition %}
      - `institution` string — The Belvo ID of the institution that they payer will use to pay for the merchant's service. To get the Belvo ID of an institution, use the [Institutions endpoint](https://developers.belvo.com/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil).
      - `representative_identifier` string — In the case that the customer is a business, this is the CPF of the representative authorized to make payments for the business.
    - `beneficiary` object, required — Details regarding the beneficiary of the payment.
      - `type` 'BANK_ACCOUNT', required — The type of beneficiary account. At present, this must be set to `BANK_ACCOUNT`.
      - `target` union, required — Details regarding the bank account that will receive funds. You can either provide the complete details of the bank account or the Belvo ID. If you provide the complete bank account details, we will check if the bank account exists in Belvo. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID.
        - BankAccountObject — Details of the bank account to be registered. If the bank account exists, we return their Belvo ID. If not, we create a new bank account and return the newly assigned Belvo ID.
          - `holder` object, required — Details of the account holder.
            - `identifier` string, required — The CPF (11 digits) or CNPJ (14 digits) of the account holder.
            - `name` string, required — The full name or business name of the account holder.
          - `details` object, required — Details of the bank account.
            - `account_type` 'CHECKINGS' | 'SAVINGS' | 'PAYMENTS', required — The type of bank account. Can be either: - `CHECKINGS` (also known as Conta Corrente in Brazil) - `SAVINGS` (also known as Conta Poupança in Brazil) - `PAYMENTS` (also known as Conta de Pagamento Instantâneo or Conta de Pagamento in Brazil)
            - `agency` string, required — The agency (branch number) of the institution where the account was created.
            - `institution` string, uuid, required — The Belvo ID of the financial institution.
            - `number` string, required — The bank account number. {% admonition type="info" name="Valid Account Number characters" %} You can only send through numbers (`^[0-9]+$`) in the string. For example, `"457220"` is a valid bank account number, while "`45722-0`" is invalid as it contains a hyphen (`-`). {% /admonition %}
          - `external_id` string, uuid — An additional unique identifier for the resource for internal purposes. {% admonition type="success" name="Highly Recommended" %} We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes. {% /admonition %}
          - `metadata` MetadataPayments — 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 %}
        - string, uuid — The Belvo ID of the bank account you previously registered that will receive funds. {% admonition type="warning" name="Bank Account from Payments-BR.V2" %} The provided bank account ID must be one that was created using the `Payments-BR.V2` version of our API. For example, using either the Bank Account Details option when created the Payment Authorization, or the Register Bank Account endpoint with the `X-Belvo-API-Resource-Version: Payments-BR.V2` header. If you provide an ID that is not `Payments-BR.V2` version compliant, you will receive the following error: `The bank account does not exist or is invalid.`. {% /admonition %}
    - `payment_method_configuration` object, required — Details regarding the payment.
      - `amount` number, float, required — The amount that your customer will be charged.
      - `statement_description` string, required — The description that will appear on your customer's bank statement.
      - `dates` string[], required — The date that the payment is scheduled to be made, in `YYYY-MM-DD` format. Must be at least one day into the future.
    - `metadata` MetadataPayments — 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 %}

## Response `201`

OK - Payment Authorization created

- PaymentAuthorization — Payment Authorization details.
  - `id` string, uuid, required — The Belvo ID for the Payment Authorization.
  - `created_at` string, date-time, required — The ISO-8601 timestamp of when the Payment Authorization was created.
  - `updated_at` string, date-time, required — The ISO-8601 timestamp of when the Payment Authorization was last updated.
  - `status` 'AWAITING_AUTHORIZATION' | 'PARTIALLY_ACCEPTED' | 'AUTHORIZED' | 'FAILED' | 'CONSUMED' | 'REVOKED', required — The current status of the Payment Authorization.
  - `status_reason_code` string, nullable, required — A code indicating the reason for the current status (when applicable). For a full list of possible codes and messages, please see our dedicated Error Codes and Messages article.
  - `status_reason_message` string, nullable, required — A human-readable message explaining the reason for the current status (when applicable).
  - `status_updated_at` string, date-time, required — The ISO-8601 timestamp of when the status was last updated.
  - `authorized_at` string, date-time, nullable, required — The ISO-8601 timestamp of when the Payment Authorization was authorized by the user.
  - `external_id` string, uuid, nullable, required — The merchant's internal ID for the authorization.
  - `description` string, required — An internal description used by the merchant only.
  - `return_url` string, uri, required — The URL where the user will be redirected after authorization.
  - `payment_method` 'PIX_OF_IMMEDIATE' | 'PIX_OF_SCHEDULED', required — The payment method that was authorized.
  - `payer` object, required — Details regarding the payer.
    - `customer` string, uuid — The Belvo ID for the customer.
    - `institution` string, uuid — The Belvo ID of the institution that the payer will use.
    - `representative_identifier` string — In the case that the customer is a business, the CPF of the representative authorized to make payments.
  - `beneficiary` object, required — Details regarding the beneficiary of the payment.
    - `type` 'BANK_ACCOUNT' — The type of beneficiary account.
    - `target` string, uuid — The Belvo ID of the bank account that will receive funds.
  - `payment_method_configuration` union, required — Configuration details for the payment method.
    - object — Configuration details for the `PIX_OF_IMMEDIATE` payment method.
      - `amount` string — The amount that your customer will be charged.
      - `statement_description` string — The description that will appear on your customer's bank statement.
      - `authorization_url` string, uri — The URL where the user should be redirected to authorize the payment.
    - object — Configuration details for the `PIX_OF_SCHEDULED` payment method.
      - `amount` string — The amount that your customer will be charged.
      - `statement_description` string — The description that will appear on your customer's bank statement.
      - `dates` string[] — The date that the payment is scheduled to be made, in `YYYY-MM-DD` format.
      - `authorization_url` string, uri — The URL where the user should be redirected to authorize the payment.
  - `charges` string[], required — A list of Charge IDs associated with the Payment Authorization.
  - `metadata` MetadataPayments — 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 %}

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Access to Belvo API denied
- `404` — Not Found Error
- `408` — Request Timeout
- `500` — Unexpected Error

---

[API](https://skmtc.net/belvo/apis/belvo-api-docs.md) · [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/versions/3423c786ece5/schema)