# Crear una nueva Autorización de Pago

Create a Payment Authorization. The request body depends on the payment_method. At present, only Smart Transfers (PIX_OF_SMART_TRANSFERS) is available. The Immediate (PIX_OF_IMMEDIATE) and Scheduled (PIX_OF_SCHEDULED) payment methods aren't available yet.

For Smart Transfers (PIX_OF_SMART_TRANSFERS):
  1. Create the authorization. The response includes payment_method_configuration.authorization_url.
  2. Redirect your user to the authorization_url to approve the authorization at their institution.
  3. Wait for the PAYMENT_AUTHORIZATION webhook with the status set to AUTHORIZED.
  4. Create each transfer with the Create a Charge/createpaymentauthorizationchargebrazil) endpoint.

To create a Smart Transfers authorization against a specific payer account, send payer.account_details (together with the required payer.institution). Your user can then only approve the authorization for that account. If you do not send it, your user selects the account at their institution.

{% admonition type="warning" name="Smart Transfers: same holder only" %}
  The beneficiary bank account must be held by the payer (the same CPF, or the same CNPJ root for businesses). Otherwise, the Payment Authorization is created with the FAILED status and the API returns a 500 error.
{% /admonition %}

Endpoint: POST /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"

## Response 201 fields (application/json):

  - `id` (string, required)
    El Belvo ID para la Autorización de Pago.
    Example: "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432"

  - `created_at` (string, required)
    La marca de tiempo ISO-8601 de cuando se creó la Autorización de Pago.
    Example: "2025-05-20T09:55:02Z"

  - `updated_at` (string, required)
    La marca de tiempo ISO-8601 de cuándo se actualizó por última vez la Autorización de Pago.
    Example: "2025-05-20T09:55:02Z"

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

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

  - `status_reason_message` (string,null, required)
    Un mensaje legible por humanos que explica la razón del estado actual (cuando sea aplicable).

  - `status_updated_at` (string, required)
    La marca de tiempo ISO-8601 de cuando se actualizó por última vez el estado.
    Example: "2025-05-20T09:55:02Z"

  - `authorized_at` (string,null, required)
    La marca de tiempo ISO-8601 de cuando la Autorización de Pago fue autorizada por el usuario.
    Example: "2025-05-20T09:55:02Z"

  - `external_id` (string,null, required)
    El ID interno del comerciante para la autorización.
    Example: "c169a8a9-e9f5-48db-9f4a-818caef9356b"

  - `description` (string, required)
    Una descripción interna utilizada solo por el comerciante.
    Example: "Internal description used by the merchant only"

  - `return_url` (string, required)
    La URL a la que el usuario será redirigido después de la autorización.
    Example: "https://merchant.com/return"

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

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

  - `payer` (object, required)
    Detalles sobre el pagador.

  - `payer.customer` (string)
    El Belvo ID para el cliente.
    Example: "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044"

  - `payer.institution` (string)
    El ID de Belvo de la institución que el pagador utilizará.
    Example: "770932b4-8f1f-4b0f-8470-1c605903fdb2"

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

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

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

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

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

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

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

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

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

  - `beneficiary` (object, required)
    Detalles sobre el beneficiario del pago.

  - `beneficiary.type` (string)
    El tipo de cuenta del beneficiario.
    Enum: "BANK_ACCOUNT"

  - `beneficiary.target` (string)
    El Belvo ID de la cuenta bancaria que recibirá fondos.
    Example: "b6278377-f710-4d1a-a026-7bab757256d0"

  - `payment_method_configuration` (object, required)
    Detalles de configuración para el método de pago.

  - `charges` (array, required)
    Una lista de IDs de Charge asociados con la Autorización de Pago.
    Example: ["7d159b21-9f25-4365-9fa2-734d20797819"]

  - `metadata` (object)
    Objeto opcional y personalizable donde puedes proporcionar cualquier par clave-valor adicional para tus propósitos internos. Por ejemplo, un número de referencia interno para la intención de pago.

{% admonition type="info" name="Limitaciones de Metadata" %}
  Solo puedes proporcionar hasta 50 claves (las claves pueden tener hasta 50 caracteres cada una y cada valor puede tener hasta 500 caracteres). No soportamos objetos anidados, solo valores ASCII.
{% /admonition %}
    Example: {"internal_reference_id":"GGq73487w2"}

## Response 400 fields (application/json):

  - `code` (string, required)
    Un código de error único (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) que te permite clasificar y manejar el error de manera programática.
    Example: "required"

  - `message` (string, required)
    Una breve descripción del error.

La descripción puede ser (entre otras):

  - Este campo es obligatorio.
  - El objeto con nombre=narnia no existe.
  - Este campo no puede ser nulo.
  - Este campo no puede estar en blanco.
  - Este cliente ya está registrado.
  - Asegúrese de que este campo tenga al menos 2 caracteres.
  - Asegúrese de que este campo no tenga más de 4 caracteres.
  - El valor ingresado no es válido.
  - Debe establecer todos los campos obligatorios: username, password, username_type.
  - Payment Intent no puede ser cancelado porque no está SCHEDULED.
  - Payment Intent no puede ser cancelado ya que el tiempo límite (23:59:00) ha pasado.
  - La clave de idempotencia proporcionada no es válida.
    Example: "This field is required."

  - `request_id` (string, required)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `field` (string,null)
    Nombre del campo donde se encontró el error.

> Nota: Este campo solo está presente cuando el error está relacionado con un campo específico.
    Example: "institution"

## Response 403 fields (application/json):

  - `code` (string)
    Un código de error único (access_to_resource_denied) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Una breve descripción del error.

Para los errores access_to_resource_denied, la descripción es:

  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Un código de error único (not_found) que te permite clasificar y manejar el error de manera programática.
    Example: "not_found"

  - `message` (string)
    Una breve descripción del error.

Para errores not_found, la descripción es:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Un código de error único (request_timeout) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Una breve descripción del error.

Para los errores de request_timeout, la descripción es:

  - 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)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    Un código de error único (unexpected_error) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Una breve descripción del error.

Para los errores unexpected_error, la descripción es:

- Belvo no puede procesar la solicitud debido a un problema interno del sistema o a una respuesta no soportada de una institución.
    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)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"