# 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)
    The payment-authorization.id the Charge belongs to.
    Example: "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432"

## Response 201 fields (application/json):

  - `id` (string)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `created_at` (string)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `status_updated_at` (string,null)
    The ISO-8601 timestamp of when the status of the Charge was last updated.
    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)
    The reason code for the current status of the Charge, if applicable.

  - `status_reason_message` (string,null)
    Further information regarding the 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)
    The amount of the Charge.
    Example: "100.12"

  - `date` (string,null)
    The original date of the Charge.
    Example: "2025-06-09"

  - `end_to_end_id` (string,null)
    The end-to-end ID of the Charge. This is a unique identifier for the transaction that can be used to track it across different systems.
    Example: "1234567890abcdef"

  - `statement_description` (string)
    The description that will appear on the customer's bank statement (if provided).
    Example: "Super Shoe Store - Brown Sneakers"

  - `external_id` (string)
    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 %}
    Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `beneficiary` (object)
    Information about the beneficiary of the Charge.

  - `beneficiary.bank_account` (object)
    Information about the beneficiary's bank account.

  - `beneficiary.bank_account.id` (string)
    Belvo's unique ID used to identify the beneficiary's bank account.
    Example: "088bc38f-1430-40c5-a5d2-80bd67189d11"

  - `beneficiary.bank_account.holder` (object)
    Information about the holder of the beneficiary's bank account.

  - `beneficiary.bank_account.holder.name` (string)
    The full name of the holder of the beneficiary's bank account.
    Example: "Jane Smith"

  - `beneficiary.bank_account.holder.identifier` (string)
    The identifier of the holder of the beneficiary's bank account. Can be either a CPF (11 characters) or CNPJ (14 characters).
    Example: "12345678901"

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

  - `beneficiary.bank_account.details.institution` (string)
    Belvo's unique ID used to identify the beneficiary's bank.
    Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

  - `beneficiary.bank_account.details.agency` (string)
    The agency number of the beneficiary's bank account.
    Example: "5678"

  - `beneficiary.bank_account.details.number` (string)
    The account number of the beneficiary's bank account.
    Example: "987654321"

  - `beneficiary.bank_account.details.account_type` (string)
    The type of the beneficiary's bank account. Can be either CHECKINGS, SAVINGS, or PAYMENTS.
    Example: "SAVINGS"

  - `beneficiary.bank_account.details.code` (string)
    The ISPB code of the beneficiary's bank.
    Example: "678901"

  - `payer` (object)
    Information about the payer of the Charge.

  - `payer.bank_account` (object)
    Information about the payer's bank account.

  - `payer.bank_account.holder` (object)
    Information about the holder of the payer's bank account.

  - `payer.bank_account.holder.identifier` (string)
    The identifier of the holder of the payer bank account. Can be either a CPF (11 characters) or CNPJ (14 characters).
    Example: "12345678902"

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

  - `payer.bank_account.details.institution` (string)
    Belvo's unique ID used to identify the payer's bank.

  - `payer.bank_account.details.code` (string)
    The ISPB code of the payer's bank.
    Example: "123345"

  - `payer.bank_account.details.account_type` (string)
    The type of the payer's bank account. Can be either CHECKINGS, SAVINGS, or PAYMENTS.
    Example: "CHECKINGS"

  - `payer.bank_account.details.agency` (string)
    The agency number of the payer's bank account.
    Example: "1234"

  - `payer.bank_account.details.number` (string)
    The account number of the payer's bank account.
    Example: "123456789"

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

  - `next` (string,null)
    The Belvo ID of the next Charge in the sequence (only applicable if the Charge was retried). If null, it indicates that there are no further Charges in the sequence.
    Example: "7d159b21-9f25-4365-9fa2-734d20797819"

  - `previous` (string,null)
    The Belvo ID of the previous Charge in the sequence (only applicable if the Charge was retried). If null, it indicates that there are no previous Charges in the sequence.
    Example: "7d159b21-9f25-4365-9fa2-734d20797818"

## Response 400 fields (application/json):

  - `code` (string, required)
    A unique error code (null, does_not_exist, required, already_registered, invalid_choice, max_length, min_length, blank, null, cancellation_error, idempotency_key_invalid) that allows you to classify and handle the error programmatically.
    Example: "required"

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


The description can be (among others):

  - This field is required.
  - Object with name=narnia does not exist.
  - This field may not be null.
  - This field may not be blank.
  - This customer is already registered
  - Ensure this field has at least 2 characters.
  - Ensure this field has no more than 4 characters.
  - Entered value is not valid.
  - You must set all required fields: username, password, username_type.
  - Payment Intent cannot be canceled because it is not SCHEDULED.
  - Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.
  - The provided idempotency key is invalid.
    Example: "This field is required."

  - `request_id` (string, required)
    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"

  - `field` (string,null)
    Name of the field where the error was encountered.

> Note: This field is only present when the error is related to a specific field.
    Example: "institution"

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