#Accounts Overview

The Bloque SDK provides comprehensive functionality for managing various types of financial accounts.

#Account Types

The SDK supports multiple account types, each designed for specific use cases:

#Virtual Cards

Create instant virtual cards for online payments. Cards are:

• PCI-compliant: Secure storage and display of sensitive card data
• Instant: Cards are created immediately and ready to use
• Multiple: Users can have multiple cards for different purposes

Learn more about Virtual Cards

#Bancolombia Accounts

Create payment accounts that integrate with Bancolombia's banking system:

• Reference codes: Unique codes for receiving payments
• Bank integration: Direct integration with Bancolombia
• Payment tracking: Full visibility into payment status

Learn more about Bancolombia Accounts

#BRE-B Keys

Create and resolve BRE-B payment keys for real-time payment routing:

• Supported key types: PHONE, EMAIL, ID, ALPHA, BCODE
• Key creation: Create a BRE-B account and associate it to a ledgerId when provided, or create one automatically
• Key resolution: Resolve a key before initiating a payment flow
• Lifecycle management: Suspend, activate, and delete stored keys
• Payouts: Pay to resolved keys with session.swap.breb.create()

Learn more about BRE-B

#Common Operations

All account types support common operations:

#Listing Accounts

List all accounts for a user with their current balances:

import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: 'your-origin',
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production',
});

// Connect to user session
const userSession = await bloque.connect('user-alias');

// List all card accounts
const cards = await userSession.accounts.card.list();

console.log(`Found ${cards.accounts.length} card accounts`);

cards.accounts.forEach((card) => {
  console.log('Card:', card.metadata?.name);
  console.log('Balance:', card.balance);
});

#Get Account by URN

Fetch full account details (including balance) for any account by URN:

const account = await bloque.accounts.get(
  'did:bloque:mediums:virtual:account:acc-12345',
);
console.log(account.status, account.urn, account.balance);

#Checking Balance

Get the current balance for any account by URN (works for card, virtual, bancolombia, breb, us-account, polygon):

const balance = await bloque.accounts.balance(
  'did:bloque:mediums:virtual:account:acc-12345',
);
Object.entries(balance).forEach(([asset, b]) => {
  console.log(`${asset}: current=${b.current}, pending=${b.pending}`);
});

#Viewing Transactions

List transaction history with pagination:

const movements = await bloque.accounts.card.movements({
  urn: 'did:bloque:account:card:usr-123:crd-456',
  asset: 'DUSD/6',
  limit: 50,
  direction: 'in', // incoming transactions only
});

console.log(`Found ${movements.data.length} transactions`);

#Viewing Global Transactions (All Accounts)

List transactions across all your accounts (cards, virtual, polygon, etc.) without account URN:

const transactions = await bloque.accounts.transactions({
  asset: 'DUSD/6',
  limit: 10,
});

console.log(`Found ${transactions.data.length} transactions`);
console.log('Has more:', transactions.hasMore);

#Transfers

Transfer funds between any accounts:

const transfer = await bloque.accounts.transfer({
  sourceUrn: 'did:bloque:account:card:usr-123:crd-456',
  destinationUrn: 'did:bloque:account:virtual:acc-67890',
  amount: '1000000000000',
  asset: 'KSM/12',
});

console.log('Transfer queued:', transfer.queueId);

Learn more about Transfers

#Supported Assets

#User Sessions

const userSession = await bloque.connect('user-alias');
const cards = await userSession.accounts.card.list();

#Account Webhooks

All account types support webhook notifications for lifecycle events. Pass a webhookUrl when creating an account to receive real-time POST notifications when state transitions occur — such as when an account becomes active after on-chain settlement.

Learn more about Account Webhooks

#Best Practices

1. Use User Sessions: Connect to user sessions for account operations
2. Verify Users: Ensure users complete KYC before creating accounts
3. Handle States: Check account status before operations
4. Pagination: Use pagination for large transaction lists
5. Error Handling: Always use try-catch blocks
6. Test First: Test in sandbox mode before production
7. Configure Webhooks: Set up webhooks to react to account activation instead of polling

#Next Steps

• Account Webhooks - Real-time account lifecycle notifications
• Virtual Cards - Create and manage virtual cards
• Bancolombia - Bancolombia account integration
• BRE-B - Create and resolve BRE-B keys
• Transfers - Transfer funds between accounts
• Compliance - KYC verification