--- title: "Change a Payment Authorization's beneficiary" method: PATCH path: "/payments/br/payment-authorizations/{payment_authorization_id}/" tags: ["Payment Authorizations (Brazil)"] --- # Change a Payment Authorization's beneficiary `PATCH /payments/br/payment-authorizations/{payment_authorization_id}/` ## Request - Base URL: `https://sandbox.belvo.com` - URL: `https://sandbox.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 %} ## Path parameters - `payment_authorization_id` string, uuid, required ## Headers - `X-Belvo-API-Resource-Version` 'Payments-BR.V2' ## Request body - PatchPaymentAuthorizationSmartTransfers: Change the beneficiary bank account of a Smart Transfers (`PIX_OF_SMART_TRANSFERS`) Payment Authorization. The new bank account must be held by the same person or business as the current beneficiary account. - `beneficiary` object, required: The new beneficiary of the Payment Authorization. - `type` 'BANK_ACCOUNT', required: The type of beneficiary. At present, this must be set to `BANK_ACCOUNT`. - `target` string, uuid, required: The Belvo ID of the bank account that will receive the funds from now on. You can only send the ID of a bank account that you already registered: bank account details (an object) are not accepted here. The bank account must be active, belong to your organization, and have been created with the `Payments-BR.V2` version of the API. Otherwise, you receive a `400` error (`The bank account does not exist or is invalid.`). The bank account's holder (`holder.identifier`) must be the same as the holder of the current beneficiary bank account. In other words, you can only switch to another account of the same holder. ## Response `200` OK - Payment Authorization updated - PaymentAuthorization: Payment Authorization details. - `id` string, uuid, required: The Belvo ID for the Payment Authorization. - `created_at` string, date-time, required: The ISO-8601 timestamp of when the Payment Authorization was created. - `updated_at` string, date-time, required: The ISO-8601 timestamp of when the Payment Authorization was last updated. - `status` 'AWAITING_AUTHORIZATION' | 'PARTIALLY_ACCEPTED' | 'AUTHORIZED' | 'FAILED' | 'CONSUMED' | 'REVOKED', required: The current status of the Payment Authorization. Can be one of: - `AWAITING_AUTHORIZATION`: the authorization was created and is waiting for your user to approve it at their institution (using the `payment_method_configuration.authorization_url`). - `PARTIALLY_ACCEPTED`: your user approved the authorization, but the account requires approval from additional account holders before it becomes `AUTHORIZED`. - `AUTHORIZED`: the authorization was approved. For Smart Transfers, you can now create Charges. - `FAILED`: the authorization was rejected by the user or the institution, or could not be created. See `status_reason_code` for the reason. - `CONSUMED`: the authorization was fully used and cannot be used for further payments. For Smart Transfers, this happens when the `total_allowed_amount` is used up, or when the authorization expires. Reaching a `periodic_limits` cap (day, week, month or year) does not consume the authorization: it only blocks new Charges until that window resets. - `REVOKED`: the authorization was revoked by the payer, by the beneficiary, or by you using the Cancel a Payment Authorization endpoint. See `status_reason_code` for details. - `status_reason_code` string, nullable, required: A code indicating the reason for the current status, when the status is `FAILED` or `REVOKED`. `null` for other statuses. For `PIX_OF_SMART_TRANSFERS` authorizations, the possible codes are: - `USER_REJECTED`: the payer rejected the authorization at their institution. - `AUTHORIZATION_EXPIRED`: the payer did not approve the authorization within the allowed time. - `BANK_USER_MISMATCH`: the user who logged in to the institution is not the payer of the authorization. - `IDENTIFIER_MISMATCH`: the payer's CPF or CNPJ does not match the holder of the account at the institution. - `FEATURE_NOT_ENABLED_BY_INSTITUTION`: the institution does not support Smart Transfers. - `INSUFFICIENT_PERMISSION`: the payer does not have enough permissions on the account to approve the authorization. - `SAME_ORIGIN_DESTINATION_ACCOUNTS`: the payer account and the beneficiary account are the same account. - `ACCOUNT_NOT_ALLOWED`: the payer account does not allow payments. - `INSUFFICIENT_FUNDS`: the institution rejected the authorization because the payer account has insufficient funds. - `AMOUNT_OVER_LIMIT`: the requested limits exceed the limits set by the institution. - `OPEN_FINANCE_NETWORK_FAILURE`: an infrastructure failure in the Open Finance network prevented the authorization. - `NO_REASON_PROVIDED`: the institution rejected or revoked the authorization without giving a reason. - `REJECTED_UNKNOWN`: the institution rejected the authorization for a reason not covered by the other codes. - `PAYER_REVOKED_AUTHORIZATION`: the payer revoked the authorization (status `REVOKED`). - `BENEFICIARY_REVOKED_AUTHORIZATION`: the beneficiary revoked the authorization (status `REVOKED`). - `REVOKED_UNKNOWN`: the authorization was revoked for a reason not covered by the other codes (status `REVOKED`). - `UNEXPECTED_ERROR`: Belvo could not create the authorization at the institution. Contact support with the request ID. - `status_reason_message` string, nullable, required: A human-readable message explaining the reason for the current status (when applicable). - `status_updated_at` string, date-time, required: The ISO-8601 timestamp of when the status was last updated. - `authorized_at` string, date-time, nullable, required: The ISO-8601 timestamp of when the Payment Authorization was authorized by the user. - `external_id` string, uuid, nullable, required: The merchant's internal ID for the authorization. - `description` string, required: An internal description used by the merchant only. - `return_url` string, uri, required: The URL where the user will be redirected after authorization. - `expiration_date_time` string, date-time, nullable: The ISO-8601 timestamp after which the authorization can no longer be used. `null` if no expiration date was set. - `payment_method` 'PIX_OF_IMMEDIATE' | 'PIX_OF_SCHEDULED' | 'PIX_OF_SMART_TRANSFERS', required: The payment method that was authorized. Can be one of: - `PIX_OF_IMMEDIATE`: a single Pix payment, made immediately. - `PIX_OF_SCHEDULED`: a single Pix payment, scheduled for a future date. - `PIX_OF_SMART_TRANSFERS`: Smart Transfers, on-demand transfers between accounts held by the same person or business. You create each transfer as a Charge. - `payer` object, required: Details regarding the payer. - `customer` string, uuid: The Belvo ID for the customer. - `institution` string, uuid: The Belvo ID of the institution that the payer will use. - `representative_identifier` string, nullable: In the case that the customer is a business, the CPF of the representative authorized to make payments. `null` for individual customers. - `bank_account` object, nullable: The payer's account that the user selected at their institution when approving the authorization, with sensitive values masked. `null` until the authorization is `AUTHORIZED`, or if the institution did not return the account. - `holder` object: The holder of the payer's account. - `identifier` string: The CPF or CNPJ of the account holder, masked. - `details` object: Details of the payer's account. - `account_type` 'CHECKINGS' | 'SAVINGS' | 'SALARY' | 'PAYMENTS': The type of the payer's account. Can be one of: - `CHECKINGS`: checking account (Conta Corrente). - `SAVINGS`: savings account (Conta Poupança). - `SALARY`: salary account (Conta Salário). - `PAYMENTS`: prepaid payment account (Conta de Pagamento Pré-Paga). - `agency` string: The agency (branch) number of the payer's account. All but the last 4 characters are masked. - `code` string: The ISPB code of the institution that holds the payer's account. - `number` string: The payer's account number. All but the last 4 characters are masked. - `beneficiary` object, required: Details regarding the beneficiary of the payment. - `type` 'BANK_ACCOUNT': The type of beneficiary account. - `target` string, uuid: The Belvo ID of the bank account that will receive funds. - `payment_method_configuration` union, required: Configuration details for the payment method. - object: Configuration details for the `PIX_OF_IMMEDIATE` payment method. `PIX_OF_IMMEDIATE` Payment Authorizations aren't available yet. - `amount` string: The amount that your customer will be charged. - `statement_description` string: The description that will appear on your customer's bank statement. - `authorization_url` string, uri: The URL where the user should be redirected to authorize the payment. - object: Configuration details for the `PIX_OF_SCHEDULED` payment method. `PIX_OF_SCHEDULED` Payment Authorizations aren't available yet. - `amount` string: The amount that your customer will be charged. - `statement_description` string: The description that will appear on your customer's bank statement. - `dates` string[]: The date that the payment is scheduled to be made, in `YYYY-MM-DD` format. - `authorization_url` string, uri: The URL where the user should be redirected to authorize the payment. - object: Configuration details for the `PIX_OF_SMART_TRANSFERS` (Smart Transfers) payment method. Fields you did not send when creating the authorization are omitted. - `total_allowed_amount` string: The maximum total amount, in BRL, that can be transferred across all Charges under this authorization, as a decimal string. - `payment_transaction_limit` string: The maximum amount, in BRL, of a single Charge, as a decimal string. - `periodic_limits` PeriodicLimitsSmartTransfers: Limits that apply per calendar window. Define at least one window (`day`, `week`, `month`, or `year`). Each window you define needs at least one of `quantity_limit` or `transaction_limit`. When a window's limit is reached, Charges in that window fail (with a `status_reason_code` such as `CHARGE_PERIOD_LIMIT_REACHED`) until the window resets. Reaching a periodic limit does not change the Payment Authorization's status: it stays `AUTHORIZED` and does not become `CONSUMED`. - `day` PeriodLimitSmartTransfers: The limits for one calendar window. Send at least one of `quantity_limit` or `transaction_limit`. - `quantity_limit` integer: The maximum number of successful Charges allowed in the window. - `transaction_limit` string: The maximum total amount, in BRL, that can be transferred across all Charges in the window (not the limit for a single Charge). Decimal string, minimum `"0.01"`. - `week` PeriodLimitSmartTransfers: The limits for one calendar window. Send at least one of `quantity_limit` or `transaction_limit`. - `quantity_limit` integer: The maximum number of successful Charges allowed in the window. - `transaction_limit` string: The maximum total amount, in BRL, that can be transferred across all Charges in the window (not the limit for a single Charge). Decimal string, minimum `"0.01"`. - `month` PeriodLimitSmartTransfers: The limits for one calendar window. Send at least one of `quantity_limit` or `transaction_limit`. - `quantity_limit` integer: The maximum number of successful Charges allowed in the window. - `transaction_limit` string: The maximum total amount, in BRL, that can be transferred across all Charges in the window (not the limit for a single Charge). Decimal string, minimum `"0.01"`. - `year` PeriodLimitSmartTransfers: The limits for one calendar window. Send at least one of `quantity_limit` or `transaction_limit`. - `quantity_limit` integer: The maximum number of successful Charges allowed in the window. - `transaction_limit` string: The maximum total amount, in BRL, that can be transferred across all Charges in the window (not the limit for a single Charge). Decimal string, minimum `"0.01"`. - `start_date_time` string, date-time: The ISO-8601 timestamp from which Charges can be made. - `authorization_url` string, uri: The URL where you redirect your user to approve the authorization at their institution, while the authorization is `AWAITING_AUTHORIZATION`. - `charges` string[], required: A list of Charge IDs associated with the Payment Authorization. - `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 %} ## 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/patch.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)