BEbelvo
Payment Authorizations (Brazil)

Create a Charge

Changed on

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 %}

post/payments/br/payment-authorizations/{payment_authorization_id}/charges/

Request

Path parameters

payment_authorization_idstring uuid required
Example:9fc68b84-f2d6-4142-b2ad-9d2d1ad70432

The payment-authorization.id the Charge belongs to.

Headers

X-Belvo-API-Resource-Version'Payments-BR.V2'
Example:Payments-BR.V2

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.

Request body

amountstring required

The amount to transfer, in BRL, as a decimal string. Minimum "0.01". Must not be greater than the authorization's payment_transaction_limit or total_allowed_amount (when set).

The cumulative limits (total_allowed_amount across Charges and the periodic_limits windows) are enforced by the institution: a Charge that exceeds them is returned with the FAILED status. A Charge that breaks a periodic_limits window fails with a status_reason_code such as CHARGE_PERIOD_LIMIT_REACHED, and you can create Charges again once that window resets. The Payment Authorization only becomes CONSUMED when the total_allowed_amount is used up or the authorization expires.

datestring date required

The date of the transfer, in YYYY-MM-DD format. Can be today. Must be on or after the date of the authorization's start_date_time or, if no start_date_time was set, on or after the date the authorization was created (in UTC).

statement_descriptionstring required

The description that appears on the payer's bank statement.

external_idstring uuid nullable

(Highly Recommended) Your internal ID for the Charge, as a UUID.

metadataMetadataPayments

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 request

{
  "amount": "1500.00",
  "date": "2026-11-03",
  "statement_description": "Transfer to investment account",
  "external_id": "0b6a1f9e-6c3d-4f7a-8e21-5d4c3b2a1f00",
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}

Response

OK - Charge created

idstring uuid

Belvo's unique identifier for the current item.

created_atstring date-time

The ISO-8601 timestamp of when the data point was created in Belvo's database.

status_updated_atstring date-time nullable

The ISO-8601 timestamp of when the status of the Charge was last updated.

status'PENDING' | 'SCHEDULED' | 'SETTLED' | 'CANCELED' | 'FAILED'

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.
status_reason_codestring nullable

The reason code for the current status of the Charge, if applicable.

status_reason_messagestring nullable

Further information regarding the status_reason_code.

payment_authorizationstring uuid

The Belvo ID of the Payment Authorization that the Charge belongs to.

payment_methodstring

The payment method of the Payment Authorization that the Charge belongs to (for example, PIX_OF_SMART_TRANSFERS).

amountstring nullable

The amount of the Charge.

datestring date nullable

The original date of the Charge.

end_to_end_idstring nullable

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.

statement_descriptionstring

The description that will appear on the customer's bank statement (if provided).

external_idstring 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 %}

metadataMetadataPayments

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 %}

nextstring uuid nullable

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.

previousstring uuid nullable

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 response

{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "status_updated_at": "2025-06-09T08:45:50.406032Z",
  "status": "PENDING",
  "payment_authorization": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432",
  "payment_method": "PIX_OF_SMART_TRANSFERS",
  "amount": "100.12",
  "date": "2025-06-09",
  "end_to_end_id": "1234567890abcdef",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "beneficiary": {
    "bank_account": {
      "id": "088bc38f-1430-40c5-a5d2-80bd67189d11",
      "holder": {
        "name": "Jane Smith",
        "identifier": "12345678901"
      },
      "details": {
        "institution": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "agency": "5678",
        "number": "987654321",
        "account_type": "SAVINGS",
        "code": "678901"
      }
    }
  },
  "payer": {
    "bank_account": {
      "holder": {
        "identifier": "12345678902"
      },
      "details": {
        "code": "123345",
        "account_type": "CHECKINGS",
        "agency": "1234",
        "number": "123456789"
      }
    }
  },
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  },
  "next": "7d159b21-9f25-4365-9fa2-734d20797819",
  "previous": "7d159b21-9f25-4365-9fa2-734d20797818"
}

Changes