BEbelvo
Payment Authorizations (Brazil)

Create a new Payment Authorization

Changed on

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

post/payments/br/payment-authorizations/

Request

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

OR
OR

Example request

{
  "payment_method": "PIX_OF_IMMEDIATE",
  "description": "Blue Suede Shoes - Premium 3429123",
  "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
  "return_url": "https://merchant.com/return",
  "payer": {
    "customer": {
      "identifier": "12345678901",
      "name": "João da Silva",
      "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73"
    },
    "institution": "ef685cf7-d143-4671-a1e5-4d1d019a3f5c",
    "representative_identifier": "12345678901234"
  },
  "beneficiary": {
    "type": "BANK_ACCOUNT",
    "target": {
      "holder": {
        "identifier": "12345678901122",
        "name": "Frangos Enlatados"
      },
      "details": {
        "account_type": "CHECKINGS",
        "agency": "0444",
        "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
        "number": "457220"
      },
      "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
      "metadata": {
        "internal_reference_id": "GGq73487w2"
      }
    }
  },
  "payment_method_configuration": {
    "amount": 10000.05,
    "statement_description": "Blue Suede Shoes - Premium"
  },
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}

Response

OK - Payment Authorization created

idstring uuid required

The Belvo ID for the Payment Authorization.

created_atstring date-time required

The ISO-8601 timestamp of when the Payment Authorization was created.

updated_atstring 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_codestring 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_messagestring nullable required

A human-readable message explaining the reason for the current status (when applicable).

status_updated_atstring date-time required

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

authorized_atstring date-time nullable required

The ISO-8601 timestamp of when the Payment Authorization was authorized by the user.

external_idstring uuid nullable required

The merchant's internal ID for the authorization.

descriptionstring required

An internal description used by the merchant only.

return_urlstring uri required

The URL where the user will be redirected after authorization.

expiration_date_timestring 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.
chargesstring[] required

A list of Charge IDs associated with the Payment Authorization.

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 response

{
  "id": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432",
  "created_at": "2025-05-20T09:55:02Z",
  "updated_at": "2025-05-20T09:55:02Z",
  "status": "AWAITING_AUTHORIZATION",
  "status_updated_at": "2025-05-20T09:55:02Z",
  "authorized_at": "2025-05-20T09:55:02Z",
  "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
  "description": "Internal description used by the merchant only",
  "return_url": "https://merchant.com/return",
  "expiration_date_time": "2027-10-31T23:59:59Z",
  "payment_method": "PIX_OF_IMMEDIATE",
  "payer": {
    "customer": "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044",
    "institution": "770932b4-8f1f-4b0f-8470-1c605903fdb2",
    "representative_identifier": "12345678901122",
    "bank_account": {
      "holder": {
        "identifier": "***456789**"
      },
      "details": {
        "account_type": "CHECKINGS",
        "agency": "0001",
        "code": "12345678",
        "number": "***4567"
      }
    }
  },
  "beneficiary": {
    "type": "BANK_ACCOUNT",
    "target": "b6278377-f710-4d1a-a026-7bab757256d0"
  },
  "payment_method_configuration": {
    "amount": "10000.05",
    "statement_description": "Blue Suede Shoes - Premium",
    "authorization_url": "https://auth.belvo.com/authorize?token=abc123def456"
  },
  "charges": [
    "7d159b21-9f25-4365-9fa2-734d20797819"
  ],
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}

Changes

  • acb784e42ca0Revision changes
    • breaking

      the response property / became nullable for the status

    • warning

      added the new PIX_OF_SMART_TRANSFERS enum value to the response property for the response status

    • info

      added to the request body oneOf list

    • info

      added the optional property to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added to the response property anyOf list for the response status

    • info

      removed from the response property oneOf list for the response status