# Create a Charge

Create a Charge for a Payment Authorization. At present, you can create Charges only for Smart Transfers (PIX_OF_SMART_TRANSFERS) authorizations, and only while the authorization is AUTHORIZED. Otherwise, you receive a 400 error (Payment Authorization is not AUTHORIZED.).

A Charge moves from PENDING to SCHEDULED to SETTLED, or ends as FAILED or CANCELED. Belvo notifies you of status changes by webhook. SETTLED confirms that the payer's account was debited.

{% admonition type="warning" name="Rejected Charges still return 201" %}
  If the institution rejects the Charge immediately, the API still responds with 201 - Created, with the Charge status set to FAILED and the reason in status_reason_code. No webhook is sent for this rejection, so always check the status in the response.
{% /admonition %}

Endpoint: POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/
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"

## Path parameters:

  - `payment_authorization_id` (string, required)
    El payment-authorization.id al que pertenece el Charge.
    Example: "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432"

## Response 201 fields (application/json):

  - `id` (string)
    Identificador único de Belvo para el elemento actual.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `created_at` (string)
    La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo.
    Example: "2022-02-09T08:45:50.406032Z"

  - `status_updated_at` (string,null)
    La marca de tiempo ISO-8601 de cuando se actualizó por última vez el estado del Cargo.
    Example: "2025-06-09T08:45:50.406032Z"

  - `status` (string)
    The current status of the Charge. Can be one of the following values:

  - PENDING: the Charge was created and is being processed by the institution.
  - SCHEDULED: the institution accepted the Charge and will process it on its date.
  - SETTLED: the institution confirmed that the payer's account was debited.
  - CANCELED: the Charge was canceled before it was processed.
  - FAILED: the Charge was rejected or could not be processed. See status_reason_code for the reason.
    Enum: "PENDING", "SCHEDULED", "SETTLED", "CANCELED", "FAILED"

  - `status_reason_code` (string,null)
    El código de motivo para el estado actual del Cargo, si corresponde.

  - `status_reason_message` (string,null)
    Más información sobre el status_reason_code.

  - `payment_authorization` (string)
    The Belvo ID of the Payment Authorization that the Charge belongs to.
    Example: "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432"

  - `payment_method` (string)
    The payment method of the Payment Authorization that the Charge belongs to (for example, PIX_OF_SMART_TRANSFERS).
    Example: "PIX_OF_SMART_TRANSFERS"

  - `amount` (string,null)
    El monto del Charge.
    Example: "100.12"

  - `date` (string,null)
    La fecha original del Cargo.
    Example: "2025-06-09"

  - `end_to_end_id` (string,null)
    El ID de extremo a extremo del Cargo. Este es un identificador único para la transacción que se puede utilizar para rastrearla a través de diferentes sistemas.
    Example: "1234567890abcdef"

  - `statement_description` (string)
    La descripción que aparecerá en el extracto bancario del cliente (si se proporciona).
    Example: "Super Shoe Store - Brown Sneakers"

  - `external_id` (string)
    Un identificador único adicional para el recurso con fines internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para almacenar su propio identificador único para cada recurso (cliente, cuenta bancaria, intención de pago o inscripción). Esto puede ser útil para rastrear el recurso en su sistema y para fines de depuración.
{% /admonition %}
    Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `beneficiary` (object)
    Información sobre el beneficiario del Cargo.

  - `beneficiary.bank_account` (object)
    Información sobre la cuenta bancaria del beneficiario.

  - `beneficiary.bank_account.id` (string)
    ID único de Belvo utilizado para identificar la cuenta bancaria del beneficiario.
    Example: "088bc38f-1430-40c5-a5d2-80bd67189d11"

  - `beneficiary.bank_account.holder` (object)
    Información sobre el titular de la cuenta bancaria del beneficiario.

  - `beneficiary.bank_account.holder.name` (string)
    El nombre completo del titular de la cuenta bancaria del beneficiario.
    Example: "Jane Smith"

  - `beneficiary.bank_account.holder.identifier` (string)
    El identificador del titular de la cuenta bancaria del beneficiario. Puede ser un CPF (11 caracteres) o un CNPJ (14 caracteres).
    Example: "12345678901"

  - `beneficiary.bank_account.details` (object)
    Detalles de la cuenta bancaria del beneficiario.

  - `beneficiary.bank_account.details.institution` (string)
    El ID único de Belvo utilizado para identificar el banco del beneficiario.
    Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

  - `beneficiary.bank_account.details.agency` (string)
    El número de agencia de la cuenta bancaria del beneficiario.
    Example: "5678"

  - `beneficiary.bank_account.details.number` (string)
    El número de cuenta de la cuenta bancaria del beneficiario.
    Example: "987654321"

  - `beneficiary.bank_account.details.account_type` (string)
    El tipo de la cuenta bancaria del beneficiario. Puede ser CHECKINGS, SAVINGS o PAYMENTS.
    Example: "SAVINGS"

  - `beneficiary.bank_account.details.code` (string)
    El código ISPB del banco del beneficiario.
    Example: "678901"

  - `payer` (object)
    Información sobre el pagador del Cargo.

  - `payer.bank_account` (object)
    Información sobre la cuenta bancaria del pagador.

  - `payer.bank_account.holder` (object)
    Información sobre el titular de la cuenta bancaria del pagador.

  - `payer.bank_account.holder.identifier` (string)
    El identificador del titular de la cuenta bancaria del pagador. Puede ser un CPF (11 caracteres) o un CNPJ (14 caracteres).
    Example: "12345678902"

  - `payer.bank_account.details` (object)
    Detalles de la cuenta bancaria del pagador.

  - `payer.bank_account.details.institution` (string)
    ID único de Belvo utilizado para identificar el banco del pagador.

  - `payer.bank_account.details.code` (string)
    El código ISPB del banco del pagador.
    Example: "123345"

  - `payer.bank_account.details.account_type` (string)
    El tipo de la cuenta bancaria del pagador. Puede ser CHECKINGS, SAVINGS o PAYMENTS.
    Example: "CHECKINGS"

  - `payer.bank_account.details.agency` (string)
    El número de agencia de la cuenta bancaria del pagador.
    Example: "1234"

  - `payer.bank_account.details.number` (string)
    El número de cuenta de la cuenta bancaria del pagador.
    Example: "123456789"

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

  - `next` (string,null)
    El Belvo ID del siguiente Cargo en la secuencia (solo aplicable si el Cargo fue reintentado). Si es null, indica que no hay más Cargos en la secuencia.
    Example: "7d159b21-9f25-4365-9fa2-734d20797819"

  - `previous` (string,null)
    El ID de Belvo del Cargo anterior en la secuencia (solo aplicable si el Cargo fue reintentado). Si es null, indica que no hay Cargos anteriores en la secuencia.
    Example: "7d159b21-9f25-4365-9fa2-734d20797818"

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