Wave API Client

Features

Installation

npm install wave-api-client
# or
yarn add wave-api-client

Getting Started

import { WaveClient } from 'wave-api-client';
// Initialize the client with your API key
const waveClient = new WaveClient({
 apiKey: 'wave_sn_prod_xxxx', // Replace with your API key
 // Optional configuration
 // baseUrl: 'https://api.wave.com',
 // timeout: 30000, // 30 seconds
 // debug: false
});
// Use the client to interact with Wave API
async function getBalance() {
 try {
 const balance = await waveClient.balance.getBalance();
 console.log(`Balance: ${balance.amount} ${balance.currency}`);
 return balance;
 } catch (error) {
 console.error('Error getting balance:', error);
 throw error;
 }
}

API Overview

Balance & Reconciliation API

// Get current wallet balance
const balance = await waveClient.balance.getBalance();
// Get balance with optional parameters
const balanceWithSubaccounts = await waveClient.balance.getBalance({
 include_subaccounts: true
});
// List transactions
const transactions = await waveClient.balance.listTransactions({
 date: '2023-01-01',
 after: 'cursor_token',
 include_subaccounts: true
});
// Refund a transaction
await waveClient.balance.refundTransaction('transaction_id');

Checkout API

// Create a checkout session
const session = await waveClient.checkout.createSession({
 amount: '1000',
 currency: 'XOF',
 success_url: 'https://example.com/success',
 error_url: 'https://example.com/error',
 // Optional parameters
 cancel_url: 'https://example.com/cancel',
 client_reference: 'order_12345',
 aggregated_merchant_id: 'merchant_123',
 restrict_payer_mobile: '+221700000000'
});
// Get session details
const sessionDetails = await waveClient.checkout.getSession('session_123');
// Get session by transaction ID
const sessionByTx = await waveClient.checkout.getSessionByTransactionId('transaction_123');
// Search sessions by client reference
const sessions = await waveClient.checkout.searchSessions('order_12345');
// Refund a session
await waveClient.checkout.refundSession('session_123');
// Expire a session
await waveClient.checkout.expireSession('session_123');

Payout API

// Send a single payout (requires an idempotency key)
const payout = await waveClient.payout.createPayout({
 receive_amount: '5000',
 currency: 'XOF',
 mobile: '+221700000000',
 name: 'John Doe',
 // Optional parameters
 national_id: '1234567890',
 payment_reason: 'Salary payment',
 client_reference: 'payment_12345',
 aggregated_merchant_id: 'merchant_123'
}, 'unique-idempotency-key-123');
// Create a batch of payouts
const batch = await waveClient.payout.createPayoutBatch({
 payouts: [
 {
 receive_amount: '5000',
 currency: 'XOF',
 mobile: '+221700000000',
 name: 'John Doe',
 client_reference: 'payment_12345'
 },
 {
 receive_amount: '3000',
 currency: 'XOF',
 mobile: '+221700000001',
 name: 'Jane Smith',
 client_reference: 'payment_12346'
 },
 ]
}, 'batch-idempotency-key-123');
// Get payout details
const payoutDetails = await waveClient.payout.getPayout('payout_123');
// Get batch details
const batchDetails = await waveClient.payout.getPayoutBatch('batch_123');
// Search payouts by client reference
const payouts = await waveClient.payout.searchPayouts('payment_12345');
// Reverse a payout
await waveClient.payout.reversePayout('payout_123');

Merchants API

// List merchants
const merchants = await waveClient.merchants.listMerchants();
// List merchants with filters
const filteredMerchants = await waveClient.merchants.listMerchants({
 status: 'active',
 search: 'store',
 first: 10,
 after: 'cursor_token'
});
// Get merchant details
const merchant = await waveClient.merchants.getMerchant('merchant_123');

Error Handling

import { WaveApiError, ValidationError } from 'wave-api-client';
try {
 await waveClient.checkout.createSession({
 // Invalid request
 });
} catch (error) {
 if (error instanceof ValidationError) {
 console.error('Validation error:', error.message, error.details);
 } else if (error instanceof WaveApiError) {
 console.error(`API error (${error.statusCode}):`, error.message);
 } else {
 console.error('Unexpected error:', error);
 }
}

Documentation

Development

# Clone the repository
git clone https://github.com/0xc007b/wave-api-client.git
cd wave-api-client
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Lint the code
npm run lint

License