BCA Merchant SDK (Unofficial)

⚠️ Disclaimer: Unofficial SDK, not affiliated with Bank Central Asia (BCA). Use at your own risk.

Unofficial JavaScript SDK for BCA Merchant API. Access transaction history, QRIS payments, and manage multiple outlets programmatically. Works with Node.js, Bun, Deno, and browsers.

✨ Features

• 🔐 Auto-login - Encrypted credentials
• 🔄 Auto-refresh token - Never worry about expired tokens
• 🏪 Multi-outlet support - Manage all your merchants
• 📊 Transaction history - Get daily transactions
• 📷 QRIS image download - Get QRIS images for all outlets
• 🎯 Dynamic QRIS - Convert static QRIS to dynamic with custom amount
• 💳 QRIS support - Full QRIS transaction details
• 🔑 Key Set rotation - Rotate encryption keys for security
• 💾 Custom storage - Store tokens anywhere (file, database, Redis, memory)
• 📝 TypeScript ready - Full type definitions

📦 Installation

npm install github:nds-stack/bca-merchant-sdk

🚀 Quick Start

const BCAMerchantSDK = require('@nds-stack/bca-merchant-sdk');

async function main() {
  const bca = new BCAMerchantSDK();
  
  // Set your credentials
  bca.setCredentials('[email protected]', 'password');
  
  // Get all merchants with QRIS images
  const merchants = await bca.getMerchantsWithQRIS();
  console.log('Your merchants:', merchants);
  
  // Get transactions for first merchant
  const result = await bca.getTransactions(merchants[0].mid);
  console.log('Total today:', result.output_schema.summary.amount);
}

📚 API Reference

new BCAMerchantSDK(options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | storage | Object | FileStorage | Custom storage (must have save, load, clear) | | storageFile | string | 'bca-tokens.json' | File path (if using default file storage) | | credentials | { email, password } | - | Initial credentials | | keySet | { rawIv, rawSalt, words } | Auto-rotate | Custom encryption key set |

Authentication

.setCredentials(email, password)

Set credentials for automatic login when token expires.

.login(email, password)

Manual login - returns tokens with access_token, refresh_token, expires_in.

.getTokenStatus()

Check current token validity.

const status = bca.getTokenStatus();
// { access_token: { valid: true }, refresh_token: { valid: true }, ... }

Merchant / Outlet Methods

.getMerchants()

Returns list of all merchants/outlets.

const merchants = await bca.getMerchants();
// [{ mid: '00XXXXXXX', name: 'Your Outlet', type: 'QRIS Statis', ... }]

.getMerchantsWithQRIS()

Returns merchants with QRIS image URLs.

const merchants = await bca.getMerchantsWithQRIS();
// [
//   {
//     mid: '00XXXXXXX',
//     name: 'Your Outlet',
//     nmid: 'ID10XXXXXXXXXXX',
//     qris_image: 'https://bms.ebanksvc.bca.co.id/image/...',
//     acquirers: ['BCA']
//   }
// ]

.getOutletCount()

Get outlet count by type.

const count = await bca.getOutletCount();
// { output_schema: { retail: 1, qris_statis: 2, pameran: 0 } }

QRIS Methods

.getQRISList()

Get raw QRIS statis list response.

.getQRISImageUrl(mid)

Get QRIS image URL for specific merchant.

const imageUrl = await bca.getQRISImageUrl('00XXXXXXX');

.downloadQRISImage(mid)

Download QRIS image as base64 string.

const base64Image = await bca.downloadQRISImage('00XXXXXXX');
const fs = require('fs');
fs.writeFileSync('qris.png', Buffer.from(base64Image, 'base64'));

.generateDynamicQRISString(mid, amount)

Generate dynamic QRIS string with fixed amount.

const dynamicQRIS = await bca.generateDynamicQRISString('00XXXXXXX', 50000);
// Returns QRIS string ready to be converted to QR code

.generateDynamicQRISImage(mid, amount)

Generate dynamic QRIS as base64 image. Ready to save or display!

const fs = require('fs');
const base64QRIS = await bca.generateDynamicQRISImage('00XXXXXXX', 50000);
fs.writeFileSync('qris-50000.png', Buffer.from(base64QRIS, 'base64'));
console.log('✅ QRIS Rp 50.000 siap di-scan!');

Transaction Methods

.getTransactions(mid, date?, endDate?)

Get transactions for a specific merchant.

| Param | Type | Required | Description | |-------|------|----------|-------------| | mid | string | ✅ | Merchant ID | | date | string | ❌ | Start date (YYYY-MM-DD), default: today | | endDate | string | ❌ | End date (YYYY-MM-DD), default: today |

// Single day
const result = await bca.getTransactions('00XXXXXXX', '2026-01-01');

// Date range
const result = await bca.getTransactions('00XXXXXXX', '2026-01-01', '2026-01-31');

console.log(result.output_schema.transaction);
console.log('Total amount:', result.output_schema.summary.amount);

.getAllTransactions(mid, date?, endDate?)

Get ALL transactions with auto-pagination.

Key Set Management (Static Methods)

BCAMerchantSDK.addKeySet(keySet)

Add new encryption key set for rotation.

BCAMerchantSDK.getKeySets()

Get all registered key sets.

BCAMerchantSDK.resetKeySetRotation()

Reset key set rotation index.

💾 Custom Token Storage

By default, SDK stores tokens in a JSON file. You can provide your own storage implementation to save tokens anywhere you want (database, Redis, memory, etc.).

Storage Interface

Your custom storage must implement these methods:

| Method | Type | Description | |--------|------|-------------| | save(tokens) | async | Save token object | | load() | async | Load saved token (return null if none) | | clear() | async | Clear/delete saved token |

Example: SQLite Storage

const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database('./bca.db');

// Create table (run once)
db.run(`CREATE TABLE IF NOT EXISTS bca_tokens (
  id INTEGER PRIMARY KEY,
  access_token TEXT,
  refresh_token TEXT,
  expires_in INTEGER,
  refresh_expires_in INTEGER,
  token_type TEXT,
  session_state TEXT,
  scope TEXT,
  saved_at TEXT
)`);

// Custom storage implementation
const sqliteStorage = {
  save: async (tokens) => {
    return new Promise((resolve, reject) => {
      db.run(
        `INSERT OR REPLACE INTO bca_tokens (id, access_token, refresh_token, expires_in, refresh_expires_in, token_type, session_state, scope, saved_at)
         VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?)`,
        [tokens.access_token, tokens.refresh_token, tokens.expires_in, tokens.refresh_expires_in, tokens.token_type, tokens.session_state, tokens.scope, new Date().toISOString()],
        function(err) {
          if (err) reject(err);
          else resolve(tokens);
        }
      );
    });
  },
  
  load: async () => {
    return new Promise((resolve, reject) => {
      db.get('SELECT * FROM bca_tokens WHERE id = 1', (err, row) => {
        if (err) reject(err);
        else resolve(row || null);
      });
    });
  },
  
  clear: async () => {
    return new Promise((resolve, reject) => {
      db.run('DELETE FROM bca_tokens WHERE id = 1', (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
  }
};

// Use SQLite storage
const bca = new BCAMerchantSDK({
  storage: sqliteStorage,
  credentials: { email: '[email protected]', password: 'password' }
});

// SDK will auto-save tokens to SQLite!
const merchants = await bca.getMerchants();

Other Storage Examples

Redis:

const Redis = require('ioredis');
const redis = new Redis();

const redisStorage = {
  save: async (tokens) => {
    await redis.setex('bca:tokens', 28800, JSON.stringify(tokens));
    return tokens;
  },
  load: async () => {
    const data = await redis.get('bca:tokens');
    return data ? JSON.parse(data) : null;
  },
  clear: async () => { await redis.del('bca:tokens'); }
};

MongoDB:

const mongoose = require('mongoose');
const Token = mongoose.model('Token', new mongoose.Schema({
  access_token: String,
  refresh_token: String,
  expires_in: Number,
}));

const mongoStorage = {
  save: async (tokens) => {
    await Token.deleteMany({});
    return await Token.create(tokens);
  },
  load: async () => await Token.findOne(),
  clear: async () => await Token.deleteMany({})
};

Memory (for testing):

const memoryStorage = {
  _data: null,
  save: (tokens) => { this._data = tokens; return tokens; },
  load: () => this._data,
  clear: () => { this._data = null; }
};

📖 Examples

Generate Dynamic QRIS for Payment

const bca = new BCAMerchantSDK();
bca.setCredentials('[email protected]', 'password');
const fs = require('fs');

// Generate dynamic QRIS langsung dapat base64 image!
const base64QRIS = await bca.generateDynamicQRISImage('00XXXXXXX', 50000);

// Simpan ke file PNG
fs.writeFileSync('qris-50000.png', Buffer.from(base64QRIS, 'base64'));
console.log('✅ QRIS Rp 50.000 siap di-scan!');

Monitor All Merchants Daily Total

const bca = new BCAMerchantSDK();
bca.setCredentials('[email protected]', 'password');

const merchants = await bca.getMerchants();
let totalAmount = 0;

for (const m of merchants) {
  const result = await bca.getTransactions(m.mid);
  totalAmount += parseFloat(result.output_schema.summary?.amount || 0);
}

console.log(`Total today: Rp ${totalAmount.toLocaleString()}`);

Query Date Range

const bca = new BCAMerchantSDK();
bca.setCredentials('[email protected]', 'password');

// Get transactions for January 2026
const result = await bca.getTransactions('00XXXXXXX', '2026-01-01', '2026-01-31');

console.log(`Total transactions: ${result.output_schema.total_transaction}`);
console.log(`Total amount: Rp ${result.output_schema.summary.amount}`);

🔧 Requirements

• Node.js >= 18.0.0 (uses native fetch and webcrypto)

🛠️ Dependencies

| Package | Purpose | |---------|---------| | crypto-js | AES encryption for login | | @nds-stack/qris-utils | QRIS parsing and dynamic generation |

⚠️ Important Notes

• This SDK uses pre-collected encryption key sets
• Key sets rotate automatically for security
• Please use responsibly and respect BCA's rate limits
• QRIS images from API are static - use generateDynamicQRIS methods for fixed amount

📄 License

MIT © NDS Stack

⚠️ Disclaimer

This project is for educational purposes only. It is not affiliated with, endorsed by, or connected to Bank Central Asia (BCA). The author is not responsible for any misuse or violation of BCA's terms of service. Use at your own risk.