API Overview

The API is a modern, RESTful API designed to provide comprehensive banking and payment functionality for the Brazilian market.

Architecture

RESTful Design

Our API follows REST principles:

• Resource-based URLs: Each endpoint represents a specific resource
• HTTP Methods: Standard methods (GET, POST, PUT, DELETE)
• Stateless: Each request contains all necessary information
• JSON Format: All data exchanged in JSON format

Base URL Structure

https://api.bnscred.com.br/{version}/{module}/{resource}

Example:

https://api.bnscred.com.br/v3/account/5001/balance

API Modules

Account Management

Comprehensive account operations including:

• Balance inquiries (real-time and cached)
• Transaction history and KPIs
• PIX key listing
• Webhook configuration

Onboarding

Open an account for an individual (PF) or a company (PJ) by submitting the registration through the API, then start a cadastral update when the deadline expires.

Payment Operations

Full payment capabilities:

• PIX transfers using keys
• Manual transfers with recipient details
• Copy and paste code generation
• QR code payments

PIX Key Management (DICT)

Complete PIX key lifecycle:

• Registration (CPF, CNPJ, email, phone, EVP)
• Verification (OTP for email/phone)
• Deletion
• Ownership claims (portability)

Reporting & Analytics

Comprehensive data access:

• Transaction statements
• Daily balance summaries
• Client information queries
• Export functionality (XLSX)

Webhooks

Real-time event notifications:

• Transaction events
• PIX events
• Account events
• PIX key events

Request Format

Headers

All API requests require authentication headers:

Authorization: Bearer {access_token}
hmac: {hmac_signature}
Content-Type: application/json

Request Body

POST and PUT requests include JSON body:

{
  "field1": "value1",
  "field2": 123,
  "field3": true
}

Response Format

Success Response

{
  "worked": true,
  "data": {
    "id": 123,
    "field": "value"
  }
}

Error Response

{
  "worked": false,
  "error": "Descriptive error message",
  "error_code": "ERROR_CODE"
}

HTTP Status Codes

Pagination

List endpoints use cursor-based pagination:

{
  "next": "https://api.bnscred.com.br/v3/resource?cursor=abc123",
  "previous": "https://api.bnscred.com.br/v3/resource?cursor=xyz789",
  "results": []
}

Parameters:

• limit: Number of records per page (default: 50, max: 100)
• cursor: Position marker for pagination

Rate Limiting

To ensure fair usage and system stability:

• Rate Limit: 1000 requests per hour per API key
• Burst Limit: 100 requests per minute
• Headers: Rate limit information in response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1622547600

Data Types

Common Field Types

Dates and Times (UTC-0)

Example — converting from Brasília time (UTC−03:00) to UTC-0:

Local (America/Sao_Paulo): 2026-05-29 07:30:00 -03:00
Send as (UTC-0):           2026-05-29T10:30:00Z

Currency

All monetary values are in BRL (Brazilian Real) with 2 decimal places:

{
  "amount": 1000.50
}

Documents

Brazilian documents (CPF/CNPJ) can be sent with or without formatting:

{
  "document": "123.456.789-00"
}

or

{
  "document": "12345678900"
}

Idempotency

Prevent duplicate operations using idempotency keys:

POST /v3/cashout/create-cashout
idempotency-key: 550e8400-e29b-41d4-a716-446655440000

Benefits:

• Safe to retry requests
• Prevents duplicate transactions
• Automatic deduplication

Versioning

The API uses URL-based versioning:

• Current version: v3
• Version format: /v{version}/

Example:

https://api.bnscred.com.br/v3/account/balance

Version Lifecycle:

• New versions announced 6 months in advance
• Old versions supported for 12 months after deprecation
• Breaking changes only in new versions

Environments

Production

https://api.bnscred.com.br

• Real transactions
• Real money
• Rate limits apply

Sandbox

https://sandbox-api.example.com

• Test environment
• Fake money
• Same API structure
• No rate limits

Best Practices

1. Error Handling

Always handle errors gracefully:

try {
  const response = await fetch(url, options);
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error);
  }
} catch (error) {
  console.error('Network Error:', error);
}

2. Retry Logic

Implement exponential backoff for retries:

• Retry on 5xx errors
• Don't retry on 4xx errors (fix the request)
• Use exponential backoff (1s, 2s, 4s, 8s)

3. Caching

Cache appropriate responses:

• Balance: cache for 30-60 seconds
• PIX keys: cache for 5 minutes
• Static data: cache for longer periods

4. Logging

Log all API interactions:

• Request details (excluding sensitive data)
• Response status codes
• Error messages
• Response times

5. Security

Protect sensitive data:

• Never log bearer tokens or HMAC signatures
• Use HTTPS only
• Rotate credentials regularly
• Store credentials securely (environment variables)

SDKs and Libraries

Coming soon:

• JavaScript/TypeScript SDK
• Python SDK
• PHP SDK
• Java SDK

Next Steps

• Authentication Guide
• Getting Started
• API Reference