Merchant Wallets

Merchant wallets are specialized wallets designed for business accounts. They support all standard wallet operations while maintaining business-specific metadata such as business name and type.

Merchant vs Regular Wallets

Merchant wallets are designated with type: "MERCHANT" and ownerType: "MERCHANT" in the database. They support business information like business name and business type, making them ideal for payment collection and settlement scenarios.

API Reference

Create Merchant Wallet

Expand

Use Cases

Payment Collection

Merchant wallets are ideal for businesses collecting payments from customers. Funds are credited to the merchant wallet and can be settled to bank accounts or used for disbursements.

Multi-Currency Support

Create merchant wallets in different currencies (KES, USD, EUR, GBP) to support international transactions and settlements.

Sandbox Testing

In sandbox mode, merchant wallets are automatically initialized with test funds, allowing you to test payment flows without real money.

Best Practices

1Store business metadata: Use the metadata field to store business registration numbers, tax IDs, and other relevant information for compliance.
2Monitor balance: Regularly check wallet balances before initiating disbursements to ensure sufficient funds.
3Use webhooks: Subscribe to merchant wallet events (credits, debits) to keep your system synchronized with wallet activities.
4Separate concerns: Use different merchant wallets for different business units or purposes (e.g., online sales, physical store).

Code Examples

merchant-wallets.js

const BASE = 'https://api.wasaapay.com/api/v1/partner';
const headers = { 'X-API-Key': process.env.WASAAPAY_API_KEY };

// Create a merchant wallet
const res = await fetch(`${BASE}/merchant-wallets`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'X-Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    externalUserId: 'merchant_001',
    businessName: 'Acme Electronics Ltd',
    businessType: 'retail',
    currency: 'KES',
  }),
});
const { data: wallet } = await res.json();

// Get balance
const bal = await fetch(`${BASE}/merchant-wallets/${wallet.id}/balance`, { headers });
const { data: balance } = await bal.json();
console.log('Merchant balance:', balance.availableBalance, 'KES');

// Transaction history
const txns = await fetch(`${BASE}/merchant-wallets/${wallet.id}/transactions`, { headers });
const { data: transactions } = await txns.json();