Banco do Brasil Getting Started Guide for Developers (2026)

Getting started overview

Integrating with Banco do Brasil's APIs requires developers to follow a structured process, beginning with registration on their dedicated developer portal. This portal serves as the central hub for accessing documentation, managing applications, and obtaining credentials necessary for API interactions. The primary goal of the initial setup is to establish a secure connection, enabling applications to interact with Banco do Brasil's financial services, which are compliant with Brazilian Open Banking regulations. The process typically involves creating an account, registering an application to receive API keys, and then utilizing these keys to authenticate requests, often via OAuth 2.0 protocols. Developers can utilize sandbox environments to test their integrations before moving to production.

Quick Reference Steps

Create an account and get keys

To begin, developers must create an account on the Banco do Brasil Developer Portal. This registration process typically requires standard user information and agreement to the terms of service. Upon successful account creation, log in to the portal to proceed with application registration. Navigate to the 'My Applications' or similar section, where you will initiate the creation of a new application. During this step, you'll provide details about your application, such as its name, description, and redirect URIs if you plan to implement the Authorization Code flow for user-facing applications. The portal will then provision your API credentials, which include a Client ID and a Client Secret. These keys are fundamental for authenticating your application with Banco do Brasil's APIs. The Client ID is a public identifier for your application, while the Client Secret is a confidential key that must be secured and never exposed in client-side code. For enhanced security, some platforms, including Banco do Brasil, may employ PKCE (Proof Key for Code Exchange) for public clients to mitigate interception attacks.

Your first request

After obtaining your Client ID and Client Secret, the next step is to acquire an OAuth 2.0 access token. Banco do Brasil APIs primarily use OAuth 2.0 for authentication. The specific grant type you use (e.g., Client Credentials or Authorization Code) will depend on whether your application needs to access resources on behalf of a user or directly access its own resources. For a basic server-to-server integration, the Client Credentials grant type is common for initial testing in a sandbox environment.

Step-by-step token acquisition (Client Credentials Grant)

1. Construct the Token Request: Your application will make a POST request to the Banco do Brasil OAuth token endpoint. The request body typically includes grant_type=client_credentials, client_id, and client_secret. These parameters are often sent as application/x-www-form-urlencoded or as a JSON body.
2. Encode Credentials: For the Client Credentials grant, you might need to encode your Client ID and Client Secret together using Base64 and include them in the Authorization header with the Basic scheme. For example, Authorization: Basic Base64(client_id:client_secret). Refer to the Banco do Brasil API reference for exact endpoint details and request formats.
3. Send the Request: Use a tool like cURL or an HTTP client library in your preferred programming language to send the POST request to the token endpoint.

curl -X POST \
  https://oauth.bb.com.br/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic YOUR_BASE64_ENCODED_CLIENT_ID_AND_SECRET' \
  -d 'grant_type=client_credentials'

A successful response will return a JSON object containing your access_token, its token_type (e.g., Bearer), and an expires_in value indicating its validity duration. The access token is what you will use to authenticate subsequent API calls.

Making your first authenticated API call

With the access token in hand, you can now make your first request to a protected API endpoint. For instance, you might query a sandbox endpoint for account information or a list of available services. Include the access token in the Authorization header of your API request, formatted as Bearer YOUR_ACCESS_TOKEN.

curl -X GET \
  https://api.bb.com.br/open-banking/v1/accounts \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-fapi-interaction-id: YOUR_UNIQUE_REQUEST_ID' \
  -H 'Accept: application/json'

Replace YOUR_ACCESS_TOKEN with the actual token you received and ensure you are targeting the correct API endpoint, which may vary between sandbox and production environments. The x-fapi-interaction-id header is often required for Open Banking APIs to track requests.

Common next steps

After successfully making your first API call, several common next steps can help you further integrate and develop your application:

• Explore API Catalog: Dive deeper into the Banco do Brasil API documentation to understand the full range of available services, including Pix payments, account information, credit operations, and investment APIs. Each API has specific endpoints, request/response formats, and required scopes.
• Implement Webhooks: For real-time notifications about events (e.g., payment status updates), consider implementing webhooks. This involves setting up an endpoint on your server to receive push notifications from Banco do Brasil. Refer to Twilio's webhook security guide for best practices on securing your webhook endpoints.
• Error Handling and Retries: Develop robust error handling mechanisms for different API response codes (e.g., 4xx for client errors, 5xx for server errors). Implement retry logic with exponential backoff for transient errors to improve application resilience.
• Security Best Practices: Ensure your application adheres to security best practices, such as securely storing API keys and tokens, validating input, and sanitizing output. For production environments, consider additional security measures like IP whitelisting.
• Move to Production: Once your integration is thoroughly tested in the sandbox, follow Banco do Brasil's procedures for moving your application to the production environment. This often involves additional verification steps and potentially different API endpoints and credentials.
• Monitor and Log: Implement comprehensive logging and monitoring for your API integrations to track usage, identify issues, and ensure optimal performance.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check Credentials: Verify that your Client ID and Client Secret are correct and have not expired or been revoked. Ensure they are correctly Base64 encoded if required for the Authorization header.
• Review OAuth Token Request: Double-check the token endpoint URL, grant type, and the format of your request body. A common mistake is incorrect Content-Type headers.
• Verify Access Token: Ensure the access token received is valid, unexpired, and correctly included in the Authorization: Bearer YOUR_ACCESS_TOKEN header for subsequent API calls.
• Endpoint and Method Mismatch: Confirm you are using the correct API endpoint (sandbox vs. production) and the correct HTTP method (GET, POST, PUT, DELETE) for the specific resource you are trying to access.
• Required Headers: Some APIs, especially those compliant with Open Banking standards, require specific custom headers (e.g., x-fapi-interaction-id, x-fapi-financial-id). Consult the Banco do Brasil API specifications to ensure all mandatory headers are included.
• Scope Issues: If you requested a token with insufficient scopes, your API calls might be rejected. Ensure your token request includes all necessary OAuth scopes for the resources you intend to access.
• Network and Firewall: Check for any network connectivity issues or firewall restrictions that might be preventing your application from reaching Banco do Brasil's API endpoints.
• Error Messages: Pay close attention to the error messages returned by the API. They often provide specific clues about what went wrong. For example, invalid_client usually indicates an issue with your Client ID or Secret, while invalid_grant suggests a problem with the token request.
• Consult Documentation: Always refer back to the official Banco do Brasil Developer Portal documentation for the most up-to-date and specific troubleshooting guidance.