Sign in

v1

latestOpenAPI 3.0.22026-08-061464031.4 MB
Payment Authorizations (Brazil)

Create a new Payment Authorization

{% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %}

Create a Payment Authorization.

post/payments/br/payment-authorizations/

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, then you must send through this header set to Payments-BR.V2.

{% admonition type="warning" name="Coming Soon" %} This version is in Coming Soon. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %}

Request body

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.

status_reason_codestring nullable required

A code indicating the reason for the current status (when applicable). For a full list of possible codes and messages, please see our dedicated Error Codes and Messages article.

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.

payment_method'PIX_OF_IMMEDIATE' | 'PIX_OF_SCHEDULED' required

The payment method that was authorized.

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",
  "payment_method": "PIX_OF_IMMEDIATE",
  "payer": {
    "customer": "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044",
    "institution": "770932b4-8f1f-4b0f-8470-1c605903fdb2",
    "representative_identifier": "12345678901122"
  },
  "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"
  }
}