# Payment Authorizations (Brazil)

A Payment Authorization is the consent that your user gives you to charge (debit money from) their accounts. You need to perform one Payment Authorization per ‘contract’ (for example, if your company does both electricity and water but they are billed separately, then you will create two separate Payment Authorizations).

Once the user confirms the authorization, you will need to listen for a a `PAYMENT_AUTHORIZATION` webhook with the status set to `AUTHORIZED`. Once you receive this webhook, the authorization process is complete, and you will be able to charge your user.

{% admonition type="info" name="What is a Charge?" %}
A **Charge** represents the individual payment (debit) that your customer will make.
{% /admonition %}

{% admonition type="info" name="Smart Transfers" %}
**Smart Transfers** (`PIX_OF_SMART_TRANSFERS`) let your user authorize you once to move money, on demand, between accounts they hold (for example, from their checking account to their investment account). The beneficiary account must belong to the payer. After the Payment Authorization is `AUTHORIZED`, you create each transfer as a Charge, within the limits that the user approved.
{% /admonition %}

{% admonition type="warning" name="Available payment methods" %}
At present, only Smart Transfers (`PIX_OF_SMART_TRANSFERS`) is available. The Immediate (`PIX_OF_IMMEDIATE`), Scheduled (`PIX_OF_SCHEDULED`), and Pix Automático payment methods aren't available yet.
{% /admonition %}

{% admonition type="danger" name="Version Header" %}
  The Payment Authorization resource requires that you send through the `X-Belvo-API-Resource-Version` header set to `Payments-BR.V2`.
{% /admonition %}

## Create a new Payment Authorization

 - [POST /payments/br/payment-authorizations/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationbrazil.md): Create a Payment Authorization. The request body depends on the payment_method. At present, only Smart Transfers (PIX_OF_SMART_TRANSFERS) is available. The Immediate (PIX_OF_IMMEDIATE) and Scheduled (PIX_OF_SCHEDULED) payment methods aren't available yet.

For Smart Transfers (PIX_OF_SMART_TRANSFERS):
  1. Create the authorization. The response includes payment_method_configuration.authorization_url.
  2. Redirect your user to the authorization_url to approve the authorization at their institution.
  3. Wait for the PAYMENT_AUTHORIZATION webhook with the status set to AUTHORIZED.
  4. Create each transfer with the Create a Charge/createpaymentauthorizationchargebrazil) endpoint.

To create a Smart Transfers authorization against a specific payer account, send payer.account_details (together with the required payer.institution). Your user can then only approve the authorization for that account. If you do not send it, your user selects the account at their institution.

{% admonition type="warning" name="Smart Transfers: same holder only" %}
  The beneficiary bank account must be held by the payer (the same CPF, or the same CNPJ root for businesses). Otherwise, the Payment Authorization is created with the FAILED status and the API returns a 500 error.
{% /admonition %}

## List all Payment Authorizations

 - [GET /payments/br/payment-authorizations/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationsbrazil.md): List all Payment Authorizations associated with your Belvo account.

## Get details about a Payment Authorization

 - [GET /payments/br/payment-authorizations/{payment_authorization_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationbrazil.md): Get the details about a specific Payment Authorization.

## Change a Payment Authorization's beneficiary

 - [PATCH /payments/br/payment-authorizations/{payment_authorization_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/patchpaymentauthorizationbrazil.md): Change the beneficiary bank account of a Smart Transfers (PIX_OF_SMART_TRANSFERS) Payment Authorization. Charges that you create after the change are paid to the new bank account. The response is the complete, updated Payment Authorization.

You can only edit a Payment Authorization while its status is AUTHORIZED. Otherwise, you receive a 400 error (The Payment Authorization is not authorized. It cannot be edited.). Payment Authorizations with the PIX_OF_IMMEDIATE or PIX_OF_SCHEDULED payment method cannot be edited.

If the holder name of the new bank account is different from the current one, Belvo also updates the authorization at the payer's institution.

{% admonition type="warning" name="Same holder only" %}
  The new beneficiary bank account must have the same holder (holder.identifier) as the current beneficiary bank account. Otherwise, the request fails with a 500 error (unexpected_error) and the beneficiary is not changed. You also receive a 500 error if the institution does not accept the update.
{% /admonition %}

## Cancel a Payment Authorization

 - [POST /payments/br/payment-authorizations/{payment_authorization_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationbrazil.md): Cancel a Payment Authorization

We respond with a 204 - No Content and will inform you via webhook that the Payment Authorization was canceled successfully.

{% admonition type="warning" name="Cancellation Time Restrictions (Pix Automático)" %}
For Pix Automático Payment Authorizations, the latest you can cancel a Payment Authorization is by 22:00:00 (GMT-3) on the day before the next Charge date. This restriction doesn't apply to Smart Transfers (see below). If you miss the cutoff time, the Payment Authorization will be cancelled, but the Charge will still be processed.
{% /admonition %}

{% admonition type="info" name="Smart Transfers" %}
  You can cancel a Smart Transfers (PIX_OF_SMART_TRANSFERS) Payment Authorization only while its status is AUTHORIZED. Otherwise, you receive a 400 error. After you cancel it, the status changes to REVOKED asynchronously: wait for the PAYMENT_AUTHORIZATION webhook (or check the authorization) to confirm it.
{% /admonition %}

## Create a Charge

 - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationchargebrazil.md): 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 %}

## List all Charges for a Payment Authorization

 - [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationchargesbrazil.md): List all Charges associated with a Payment Authorization

## Get details about a Charge for a Payment Authorization

 - [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationchargebrazil.md): Get the details about a specific Charge associated with a Payment Authorization.

## Retry a failed Charge for a Payment Authorization

 - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/retrypaymentauthorizationchargebrazil.md): {% admonition type="warning" name="Coming Soon" %}
  This endpoint isn't available yet. It applies only to Pix Automático Payment Authorizations, which aren't available yet. You cannot use it for Smart Transfers (PIX_OF_SMART_TRANSFERS) Charges.
{% /admonition %}

Retry a failed Charge for a given Payment Authorization.

{% admonition type="warning" name="Additional documentation" %}
  Please make sure to read the dedicated Retrying Charges and Linked Charges documentation before attempting to retry a Charge.
{% /admonition %}

{% admonition type="info" name="Not available for Smart Transfers" %}
  You cannot retry Charges of Smart Transfers (PIX_OF_SMART_TRANSFERS) authorizations. To transfer the funds again, create a new Charge with the Create a Charge/createpaymentauthorizationchargebrazil) endpoint.
{% /admonition %}

## Cancel a scheduled Charge

 - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationchargebrazil.md): Cancel a scheduled Charge.

We respond with a 204 - No Content and will inform you via webhook that the Charge was canceled successfully.

{% admonition type="warning" name="Cancellation Time Restriction (Pix Automático)" %}
  For Pix Automático Charges, the latest you can cancel a scheduled Charge is by 22:00:00 (GMT-3) on the day before the Charge date. If you miss the cutoff time, you will receive an API error from Belvo and the payment will go through. This restriction doesn't apply to Smart Transfers (see below).
{% /admonition %}

{% admonition type="info" name="Smart Transfers" %}
  For Smart Transfers (PIX_OF_SMART_TRANSFERS) Charges, you can cancel a Charge when all of the following are true:
    - The Charge status is PENDING or SCHEDULED.
    - It is before the Charge date (Brasília time): the cutoff is 23:59:59 (GMT-3) on the day before the Charge date. A Charge dated today cannot be canceled.
    - The Payment Authorization is AUTHORIZED.
{% /admonition %}