--- title: "Create a Charge" method: POST path: "/payments/br/payment-authorizations/{payment_authorization_id}/charges/" tags: ["Payment Authorizations (Brazil)"] --- # Create a Charge `POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/` ## Request - Base URL: `https://sandbox.belvo.com` - URL: `https://sandbox.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/charges/` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 %} ## Path parameters - `payment_authorization_id` string, uuid, required ## Headers - `X-Belvo-API-Resource-Version` 'Payments-BR.V2' ## Request body - CreateChargeSmartTransfers: Create a Charge (a single transfer) for a Smart Transfers (`PIX_OF_SMART_TRANSFERS`) Payment Authorization. The funds always go to the authorization's beneficiary account: you cannot send a different beneficiary for a Smart Transfers Charge. - `amount` string, 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. - `date` string, 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_description` string, required: The description that appears on the payer's bank statement. - `external_id` string, uuid, nullable: (Highly Recommended) Your internal ID for the Charge, as a UUID. - `metadata` MetadataPayments: 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 %} ## Response `201` OK - Charge created - ChargeV2 - `id` string, uuid: Belvo's unique identifier for the current item. - `created_at` string, date-time: The ISO-8601 timestamp of when the data point was created in Belvo's database. - `status_updated_at` string, 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_code` string, nullable: The reason code for the current status of the Charge, if applicable. - `status_reason_message` string, nullable: Further information regarding the `status_reason_code`. - `payment_authorization` string, uuid: The Belvo ID of the Payment Authorization that the Charge belongs to. - `payment_method` string: The payment method of the Payment Authorization that the Charge belongs to (for example, `PIX_OF_SMART_TRANSFERS`). - `amount` string, nullable: The amount of the Charge. - `date` string, date, nullable: The original date of the Charge. - `end_to_end_id` string, 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_description` string: The description that will appear on the customer's bank statement (if provided). - `external_id` string, 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 %} - `beneficiary` object: Information about the beneficiary of the Charge. - `bank_account` object: Information about the beneficiary's bank account. - `id` string, uuid: Belvo's unique ID used to identify the beneficiary's bank account. - `holder` object: Information about the holder of the beneficiary's bank account. - `name` string: The full name of the holder of the beneficiary's bank account. - `identifier` string: The identifier of the holder of the beneficiary's bank account. Can be either a CPF (11 characters) or CNPJ (14 characters). - `details` object: Details of the beneficiary's bank account. - `institution` string, uuid: Belvo's unique ID used to identify the beneficiary's bank. - `agency` string: The agency number of the beneficiary's bank account. - `number` string: The account number of the beneficiary's bank account. - `account_type` string: The type of the beneficiary's bank account. Can be either `CHECKINGS`, `SAVINGS`, or `PAYMENTS`. - `code` string: The ISPB code of the beneficiary's bank. - `payer` object: Information about the payer of the Charge. - `bank_account` object: Information about the payer's bank account. - `holder` object: Information about the holder of the payer's bank account. - `identifier` string: The identifier of the holder of the payer bank account. Can be either a CPF (11 characters) or CNPJ (14 characters). - `details` object: Details of the payer's bank account. - `institution` string, uuid: Belvo's unique ID used to identify the payer's bank. - `code` string: The ISPB code of the payer's bank. - `account_type` string: The type of the payer's bank account. Can be either `CHECKINGS`, `SAVINGS`, or `PAYMENTS`. - `agency` string: The agency number of the payer's bank account. - `number` string: The account number of the payer's bank account. - `metadata` MetadataPayments: 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 %} - `next` string, 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. - `previous` string, 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. ## Other responses - `400`: Validation Error - `401`: Unauthorized - `403`: Access to Belvo API denied - `404`: Not Found Error - `408`: Request Timeout - `500`: Unexpected Error ## Changes - **2026-10-21** `acb784e42ca0`: 1 info - endpoint added [Operation history](https://skmtc.dev/belvo/apis/belvo-api-docs/changes/payments/br/payment-authorizations/:payment_authorization_id/charges/post.md) --- [API](https://skmtc.dev/belvo/apis/belvo-api-docs.md) - [All operations](https://skmtc.dev/belvo/apis/belvo-api-docs/llms.txt) - [OpenAPI document](https://skmtc.dev/belvo/apis/belvo-api-docs/revisions/acb784e42ca0?raw)