Skip to main content

​
Banks Reference

The Banks API provides access to the list of financial institutions available in Brazil for payment processing.

​
Overview

WEpayments supports a wide range of Brazilian banks and financial institutions. The Banks API allows you to retrieve the complete list of available institutions, which is essential for:
  • Payment Processing: Know which banks are supported for transactions
  • User Interface: Display bank options to your users
  • Integration: Validate bank codes before processing payments
  • Compliance: Ensure you’re working with authorized institutions

​
Available Institutions

The API returns information about all banks registered with the Brazilian Central Bank (Banco Central do Brasil) that are supported by WEpayments.

​
Institution Information

Each institution in the list includes:
FieldTypeDescription
codestringISPB code (unique identifier)
namestringFull institution name
short_namestringAbbreviated name
typestringInstitution type (bank, payment institution, etc.)

​
Use Cases

Retrieve the list of institutions to populate a dropdown or selection menu in your application:
const banks = await fetchBanks();
const bankOptions = banks.map(bank => ({
  value: bank.code,
  label: bank.name
}));
Validate bank codes before processing transactions:
function isValidBank(bankCode, bankList) {
  return bankList.some(bank => bank.code === bankCode);
}
Convert bank codes to readable names for display:
function getBankName(bankCode, bankList) {
  const bank = bankList.find(b => b.code === bankCode);
  return bank ? bank.name : 'Unknown Bank';
}
Filter institutions by type (e.g., only traditional banks):
const traditionalBanks = banks.filter(bank => bank.type === 'bank');

​
Common Banks in Brazil

Some of the major banks you’ll find in the list include:
  • Banco do Brasil - One of the largest banks in Brazil
  • Caixa Econômica Federal - Federal savings bank
  • Itaú Unibanco - Major private bank
  • Bradesco - One of the largest private banks
  • Santander Brasil - International bank with Brazilian operations
  • Nubank - Leading digital bank
  • Inter - Digital bank and payment institution
  • PagSeguro - Payment institution

​
Best Practices

Cache the Bank List: The list of institutions doesn’t change frequently. Cache it in your application to reduce API calls and improve performance.
Keep Updated: While the list is relatively stable, new institutions may be added. Refresh your cache periodically (e.g., weekly) to stay current.

​
Caching Strategy

// Example caching implementation
const CACHE_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days

async function getBanks() {
  const cached = localStorage.getItem('banks');
  const cacheTime = localStorage.getItem('banks_timestamp');
  
  if (cached && cacheTime) {
    const age = Date.now() - parseInt(cacheTime);
    if (age < CACHE_DURATION) {
      return JSON.parse(cached);
    }
  }
  
  // Fetch fresh data
  const banks = await fetchBanksFromAPI();
  localStorage.setItem('banks', JSON.stringify(banks));
  localStorage.setItem('banks_timestamp', Date.now().toString());
  
  return banks;
}

​
Integration Example

Here’s a complete example of integrating the Banks API: 
class BankService {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.wepayments.com/v1';
    this.cache = null;
  }
  
  async fetchBanks() {
    if (this.cache) return this.cache;
    
    const response = await fetch(`${this.baseUrl}/banks/institutions`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const data = await response.json();
    this.cache = data.data;
    return this.cache;
  }
  
  async getBankByCode(code) {
    const banks = await this.fetchBanks();
    return banks.find(bank => bank.code === code);
  }
  
  async searchBanks(query) {
    const banks = await this.fetchBanks();
    const lowerQuery = query.toLowerCase();
    return banks.filter(bank => 
      bank.name.toLowerCase().includes(lowerQuery) ||
      bank.short_name.toLowerCase().includes(lowerQuery)
    );
  }
}

// Usage
const bankService = new BankService('YOUR_API_KEY');
const banks = await bankService.fetchBanks();
console.log(`Found ${banks.length} institutions`);

​
Next Steps

List Institutions

View the API endpoint documentation

Payment Processing

Learn how to process payments