# 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)
    O payment-authorization.id ao qual o Charge pertence.
    Example: "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432"

## Response 201 fields (application/json):

  - `id` (string)
    Identificador único da Belvo para o item atual.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `created_at` (string)
    O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
    Example: "2022-02-09T08:45:50.406032Z"

  - `status_updated_at` (string,null)
    O carimbo de data e hora ISO-8601 de quando o status da Cobrança foi atualizado pela última vez.
    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)
    O código de motivo para o status atual da Cobrança, se aplicável.

  - `status_reason_message` (string,null)
    Mais informações sobre o 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)
    O valor da Charge.
    Example: "100.12"

  - `date` (string,null)
    A data original da Cobrança.
    Example: "2025-06-09"

  - `end_to_end_id` (string,null)
    O ID de ponta a ponta da Cobrança. Este é um identificador único para a transação que pode ser usado para rastreá-la em diferentes sistemas.
    Example: "1234567890abcdef"

  - `statement_description` (string)
    A descrição que aparecerá no extrato bancário do cliente (se fornecida).
    Example: "Super Shoe Store - Brown Sneakers"

  - `external_id` (string)
    Um identificador exclusivo adicional para o recurso para fins internos.

{% admonition type="success" name="Altamente Recomendado" %}
  Recomendamos usar este campo para armazenar seu próprio identificador exclusivo para cada recurso (cliente, conta bancária, intenção de pagamento ou inscrição). Isso pode ser útil para rastrear o recurso em seu sistema e para fins de depuração.
{% /admonition %}
    Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `beneficiary` (object)
    Informações sobre o beneficiário da Cobrança.

  - `beneficiary.bank_account` (object)
    Informações sobre a conta bancária do beneficiário.

  - `beneficiary.bank_account.id` (string)
    ID único da Belvo usado para identificar a conta bancária do beneficiário.
    Example: "088bc38f-1430-40c5-a5d2-80bd67189d11"

  - `beneficiary.bank_account.holder` (object)
    Informações sobre o titular da conta bancária do beneficiário.

  - `beneficiary.bank_account.holder.name` (string)
    O nome completo do titular da conta bancária do beneficiário.
    Example: "Jane Smith"

  - `beneficiary.bank_account.holder.identifier` (string)
    O identificador do titular da conta bancária do beneficiário. Pode ser um CPF (11 caracteres) ou CNPJ (14 caracteres).
    Example: "12345678901"

  - `beneficiary.bank_account.details` (object)
    Detalhes da conta bancária do beneficiário.

  - `beneficiary.bank_account.details.institution` (string)
    ID único do Belvo usado para identificar o banco do beneficiário.
    Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

  - `beneficiary.bank_account.details.agency` (string)
    O número da agência da conta bancária do beneficiário.
    Example: "5678"

  - `beneficiary.bank_account.details.number` (string)
    O número da conta do banco do beneficiário.
    Example: "987654321"

  - `beneficiary.bank_account.details.account_type` (string)
    O tipo da conta bancária do beneficiário. Pode ser CHECKINGS, SAVINGS ou PAYMENTS.
    Example: "SAVINGS"

  - `beneficiary.bank_account.details.code` (string)
    O código ISPB do banco do beneficiário.
    Example: "678901"

  - `payer` (object)
    Informações sobre o pagador da Cobrança.

  - `payer.bank_account` (object)
    Informações sobre a conta bancária do pagador.

  - `payer.bank_account.holder` (object)
    Informações sobre o titular da conta bancária do pagador.

  - `payer.bank_account.holder.identifier` (string)
    O identificador do titular da conta bancária do pagador. Pode ser um CPF (11 caracteres) ou CNPJ (14 caracteres).
    Example: "12345678902"

  - `payer.bank_account.details` (object)
    Detalhes da conta bancária do pagador.

  - `payer.bank_account.details.institution` (string)
    ID único do Belvo usado para identificar o banco do pagador.

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

  - `payer.bank_account.details.account_type` (string)
    O tipo da conta bancária do pagador. Pode ser CHECKINGS, SAVINGS ou PAYMENTS.
    Example: "CHECKINGS"

  - `payer.bank_account.details.agency` (string)
    O número da agência da conta bancária do pagador.
    Example: "1234"

  - `payer.bank_account.details.number` (string)
    O número da conta bancária do pagador.
    Example: "123456789"

  - `metadata` (object)
    Objeto opcional e personalizável onde você pode fornecer quaisquer pares de chave-valor adicionais para seus propósitos internos. Por exemplo, um número de referência interno para a intenção de pagamento.

{% admonition type="info" name="Limitações de Metadata" %}
  Você pode fornecer até 50 chaves (as chaves podem ter até 50 caracteres cada e cada valor pode ter até 500 caracteres). Não suportamos objetos aninhados, apenas valores ASCII.
{% /admonition %}
    Example: {"internal_reference_id":"GGq73487w2"}

  - `next` (string,null)
    O ID Belvo da próxima Cobrança na sequência (aplicável apenas se a Cobrança foi tentada novamente). Se for null, isso indica que não há mais Cobranças na sequência.
    Example: "7d159b21-9f25-4365-9fa2-734d20797819"

  - `previous` (string,null)
    O ID Belvo da Cobrança anterior na sequência (aplicável apenas se a Cobrança foi tentada novamente). Se for null, indica que não há Cobranças anteriores na sequência.
    Example: "7d159b21-9f25-4365-9fa2-734d20797818"

## Response 400 fields (application/json):

  - `code` (string, required)
    Um código de erro único (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) que permite classificar e tratar o erro de forma programática.
    Example: "required"

  - `message` (string, required)
    Uma breve descrição do erro.

A descrição pode ser (entre outras):

  - Este campo é obrigatório.
  - Objeto com nome=narnia não existe.
  - Este campo não pode ser nulo.
  - Este campo não pode estar em branco.
  - Este cliente já está registrado.
  - Certifique-se de que este campo tenha pelo menos 2 caracteres.
  - Certifique-se de que este campo não tenha mais de 4 caracteres.
  - O valor inserido não é válido.
  - Você deve definir todos os campos obrigatórios: username, password, username_type.
  - Payment Intent não pode ser cancelado porque não está SCHEDULED.
  - Payment Intent não pode ser cancelado pois o horário limite (23:59:00) já passou.
  - A chave de idempotência fornecida é inválida.
    Example: "This field is required."

  - `request_id` (string, required)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `field` (string,null)
    Nome do campo onde o erro foi encontrado.

> Nota: Este campo só está presente quando o erro está relacionado a um campo específico.
    Example: "institution"

## Response 403 fields (application/json):

  - `code` (string)
    Um código de erro único (access_to_resource_denied) que permite classificar e tratar o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Uma breve descrição do erro.

Para erros access_to_resource_denied, a descrição é:

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

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Um código de erro único (not_found) que permite classificar e lidar com o erro programaticamente.
    Example: "not_found"

  - `message` (string)
    Uma breve descrição do erro.

Para erros not_found, a descrição é:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Um código de erro único (request_timeout) que permite classificar e lidar com o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Uma breve descrição do erro.

Para erros de request_timeout, a descrição é:

  - 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)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    Um código de erro único (unexpected_error) que permite classificar e tratar o erro de forma programática.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Uma breve descrição do erro.

Para erros unexpected_error, a descrição é:

  - Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituição.
    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)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"