Boleto.Cloud Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with Boleto.Cloud involves a series of steps designed to enable Brazilian payment processing, including Boleto Bancário and Pix. The process typically begins with account registration, followed by the acquisition of API credentials. Developers then use these credentials to authenticate API requests, enabling the creation and management of payments. Boleto.Cloud provides SDKs for common programming languages to streamline this integration process, supporting a RESTful API architecture with JSON payloads. The platform is designed for developers familiar with web service integrations seeking to implement payment solutions within a Brazilian financial context.

For a quick reference, the table below summarizes the core steps for a rapid integration:

Create an account and get keys

Before making any API calls, you need a Boleto.Cloud account and the necessary API credentials. The platform offers a free plan for testing and limited usage, allowing up to 10 boletos per month, which is suitable for initial setup and development.

1. Sign Up for a Boleto.Cloud Account: Navigate to the Boleto.Cloud registration page. Provide the required information, including your company details, and complete the sign-up process. Ensure all information is accurate, as it may be used for compliance checks, such as those related to LGPD (Lei Geral de Proteção de Dados).

2. Access Your Dashboard: Once registered and logged in, you will be redirected to your Boleto.Cloud dashboard.

3. Locate API Credentials: Within the dashboard, look for a section related to API Keys, Integrations, or Developers. Typically, you will find your API Token and Account Code here. These are crucial for authenticating your requests to the Boleto.Cloud API.

   • The API Token serves as a secret key to authenticate your application, similar to how an OAuth 2.0 bearer token functions.
   • The Account Code identifies your specific account within the Boleto.Cloud system.

   Keep these credentials secure and never expose them in public repositories or client-side code. It's recommended to use environment variables or a secure configuration management system to handle these keys in production environments.

Your first request

After obtaining your API credentials, the next step is to make your first authenticated request. This example will demonstrate how to create a simple Boleto Bancário using the API. While Boleto.Cloud supports multiple SDKs (PHP, Java, Ruby, Python, Node.js, .NET), this example will use a cURL command for direct API interaction, showcasing the underlying HTTP request structure. For language-specific examples, refer to the Boleto.Cloud SDK installation and configuration guide.

The core of the Boleto.Cloud API is RESTful, accepting JSON payloads for request bodies and returning JSON responses. All requests should be made to the base API URL, which is typically https://api.boleto.cloud/v1/ followed by the specific endpoint.

Example: Creating a Boleto Bancário

To create a Boleto Bancário, you typically need to specify details about the recipient (sacado), the payer (cedente, implied by your account), and the payment itself (valor, vencimento, etc.).

Endpoint: POST /boletos

Headers:

• Content-Type: application/json
• Authorization: Bearer YOUR_API_TOKEN
• X-Account-Code: YOUR_ACCOUNT_CODE

Replace YOUR_API_TOKEN and YOUR_ACCOUNT_CODE with your actual credentials.

Request Body (JSON):

{
  "valor": 100.00,
  "vencimento": "2026-06-30",
  "sacado": {
    "nome": "Nome do Cliente Teste",
    "cpf_cnpj": "000.000.000-00",
    "endereco": {
      "logradouro": "Rua Teste",
      "numero": "123",
      "bairro": "Centro",
      "cidade": "São Paulo",
      "estado": "SP",
      "cep": "01000-000"
    }
  },
  "instrucoes": [
    "Não receber após o vencimento."
  ],
  "juros": {
    "tipo": "percentual_ao_mes",
    "valor": 0.5
  },
  "multa": {
    "tipo": "percentual",
    "valor": 2.0
  }
}

cURL Example:

curl -X POST \
  https://api.boleto.cloud/v1/boletos \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'X-Account-Code: YOUR_ACCOUNT_CODE' \
  -d '{
    "valor": 100.00,
    "vencimento": "2026-06-30",
    "sacado": {
      "nome": "Nome do Cliente Teste",
      "cpf_cnpj": "000.000.000-00",
      "endereco": {
        "logradouro": "Rua Teste",
        "numero": "123",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "estado": "SP",
        "cep": "01000-000"
      }
    },
    "instrucoes": [
      "Não receber após o vencimento."
    ],
    "juros": {
      "tipo": "percentual_ao_mes",
      "valor": 0.5
    },
    "multa": {
      "tipo": "percentual",
      "valor": 2.0
    }
  }'

Upon a successful request, the API will return a JSON response containing the details of the newly created Boleto, including its unique ID, barcode, and the URL to view or download the Boleto PDF. A typical successful response will have an HTTP status code 201 Created.

For more detailed information on request parameters and response structures for different payment types, consult the Boleto.Cloud API reference.

Common next steps

Once you have successfully made your first API call, consider these common next steps to further integrate and leverage Boleto.Cloud's capabilities:

1. Explore Other Payment Methods: Beyond Boleto Bancário, Boleto.Cloud also supports Pix payments. Implement Pix integration to offer instant payment options to your customers.

2. Handle Webhooks: Set up webhooks to receive real-time notifications about payment status changes (e.g., payment confirmed, payment overdue). This is crucial for automating your order fulfillment and reconciliation processes. For general guidance on webhook security, refer to the Stripe webhooks security documentation.

3. Integrate SDKs: While direct API calls are useful for understanding the API, using one of the provided Boleto.Cloud SDKs (PHP, Java, Ruby, Python, Node.js, .NET) can significantly simplify development by handling authentication, request formatting, and response parsing.

4. Implement Subscription Management: If your business model involves recurring payments, explore Boleto.Cloud's subscription management features to automate the creation and collection of recurring Boletos or Pix charges.

5. Generate Payment Links: For simpler payment collection scenarios, utilize the API to generate payment links that can be shared with customers via email, SMS, or social media.

6. Testing in Sandbox Environment: Thoroughly test your integration in a sandbox or test environment provided by Boleto.Cloud to ensure all payment flows work as expected before going live. Details on the testing environment are typically found within the Boleto.Cloud documentation.

7. Error Handling and Logging: Implement robust error handling and logging mechanisms in your application to gracefully manage API failures and aid in debugging.

Troubleshooting the first call

When making your initial API request to Boleto.Cloud, you might encounter common issues. Here are some troubleshooting tips:

• Authentication Errors (401 Unauthorized):

  • Incorrect API Token: Double-check that your Authorization: Bearer YOUR_API_TOKEN header contains the exact API Token copied from your Boleto.Cloud dashboard. Ensure there are no extra spaces or characters.
  • Missing Account Code: Verify that the X-Account-Code: YOUR_ACCOUNT_CODE header is present and correct. Both the API Token and Account Code are required for authentication.
  • Expired Token: Although less common for API keys, if you are using temporary tokens, ensure they haven't expired.

• Bad Request Errors (400 Bad Request):

  • Invalid JSON Payload: Ensure your request body is valid JSON. Use a JSON linter or validator to check for syntax errors (e.g., missing commas, unclosed brackets, incorrect data types).
  • Missing Required Fields: Review the Boleto.Cloud API reference for the specific endpoint you are calling. Make sure all mandatory fields (e.g., valor, vencimento, sacado.nome) are included in your request body.
  • Incorrect Data Formats: Ensure data types match the API's expectations (e.g., dates in YYYY-MM-DD format, numerical values for amounts).

• Forbidden Errors (403 Forbidden):

  • Account Permissions: Your account might not have the necessary permissions to perform the requested action. Contact Boleto.Cloud support if you suspect a permission issue.
  • IP Whitelisting: If Boleto.Cloud implements IP whitelisting for enhanced security, ensure your server's IP address is registered.

• Not Found Errors (404 Not Found):

  • Incorrect Endpoint URL: Verify that the URL you are calling is correct and matches the Boleto.Cloud API documentation. Check for typos in the base URL or endpoint path.

• Server Errors (5xx Errors):

  • These indicate an issue on the Boleto.Cloud server. While less common, if you consistently receive 5xx errors, check the Boleto.Cloud homepage or status page for any service announcements, or contact their support team.

• Network Issues: Ensure your development environment has a stable internet connection and no firewall rules are blocking outgoing requests to api.boleto.cloud.

When troubleshooting, always examine the HTTP status code and the response body. The response body often contains specific error messages that can guide you to the root cause of the problem. Use tools like Postman, Insomnia, or browser developer tools to inspect requests and responses more easily.