rachfinance (JavaScript / Node.js SDK)

Official JavaScript/Node.js client for the Rach Finance API. Works in Node.js (CommonJS) and the browser.

Covers every API endpoint: Crypto Payment Gateway, Wallet-as-a-Service, Remittance/FX, OTC Trading, KYC, Analytics, Team Management, Webhooks, Subscriptions, and more.

Installation

npm install rachfinance

yarn add rachfinance

Quick start

const RachFinance = require('rachfinance');

// --- With API key (server-to-server) ---
const rach = new RachFinance({ apiKey: 'live_sk_...' });

// Create a crypto payment session
const session = await rach.checkout.create({
  amount: 100,
  currency: 'USD',
  customerEmail: '[email protected]',
  reference: 'ORDER-001',
  paymentMethod: 'crypto',
});
console.log(session.payment_url); // redirect your customer here

// --- With JWT (dashboard / management endpoints) ---
const dash = new RachFinance();
await dash.auth.login({ email: '[email protected]', password: 'secret' });
// Token is stored automatically — all subsequent calls use it
const balance = await dash.balance.get();

Authentication

Two auth modes — pick whichever matches the endpoint you're calling:

| Mode | How to set it | Used for | |------|--------------|----------| | API Key | new RachFinance({ apiKey: 'live_sk_...' }) | Checkout, WaaS, Remittance, Refunds, Rates | | JWT | call rach.auth.login(...) | Everything else (Auth, KYC, Analytics, Team…) |

Key prefix sets the environment automatically — no toggle needed:

• test_sk_... → sandbox (testnets, no real funds)
• live_sk_... → production (mainnet)

Constructor options

const rach = new RachFinance({
  apiKey:  'live_sk_...',     // merchant API key
  token:   'eyJhbGci...',    // JWT (optional — or call auth.login())
  baseUrl: 'https://payments-api-dev-966260606560.europe-west2.run.app', // default
});

Services

Checkout (Crypto Payment Gateway)

const rach = new RachFinance({ apiKey: 'live_sk_...' });

// Hosted page — customer picks network
const session = await rach.checkout.create({
  amount: 100, currency: 'USD',
  customerEmail: '[email protected]',
  reference: 'ORDER-001',
  paymentMethod: 'crypto',
});
// → { payment_url: 'https://...', session_id: '...', status: 'pending' }

// Direct payment — you specify network, get deposit address
const direct = await rach.checkout.create({
  amount: 100, currency: 'USDT',
  customerEmail: '[email protected]',
  reference: 'ORDER-002',
  paymentMethod: 'crypto',
  network: 'BSC',   // BSC | ETH | POL | TRX | SOL
});
// → { deposit_address: '0x...', qr_code: 'data:image/png;base64,...' }

// Check payment status
const status = await rach.checkout.verify(session.session_id);

// Trigger instant blockchain check
await rach.checkout.verifyNow(session.session_id);

// List all sessions
const list = await rach.checkout.list({ page: 1, limit: 20 });

// Stats
const stats = await rach.checkout.stats();

Wallet-as-a-Service (WaaS)

const rach = new RachFinance({ apiKey: 'live_sk_...' });

// Create a wallet for a customer (idempotent)
const wallet = await rach.waas.createWallet({
  customerId: 'cust_123',
  customerEmail: '[email protected]',
  customerName: 'Jane Smith',
});

// Get/derive a deposit address
const addr = await rach.waas.getAddress({ customerId: 'cust_123', network: 'ETH' });
console.log(addr.address);

// Transfer out
const tx = await rach.waas.transfer({
  customerId: 'cust_123',
  network: 'ETH',
  toAddress: '0xRecipient...',
  amount: '10.5',    // always string
  currency: 'USDT',
});

// Transaction history
const txns = await rach.waas.getTransactions({ customerId: 'cust_123', network: 'ETH' });

// Gas estimate
const gas = await rach.waas.estimateGas({ network: 'ETH', currency: 'USDT' });

Remittance / FX

const rach = new RachFinance({ apiKey: 'live_sk_...' });

// 1. Get a quote
const quote = await rach.remittance.getQuote({
  sourceCurrency: 'USD', destCurrency: 'NGN', amount: 500,
});

// 2. Create the transfer
const transfer = await rach.remittance.createTransfer({
  quoteId: quote.quote_id,
  recipientName: 'Amara Okafor',
  recipientAccount: '0123456789',
  recipientBankCode: '058',
  recipientCountry: 'NG',
  reference: 'PAY-001',
});

// 3. Track
const status = await rach.remittance.getTransfer(transfer.transfer_id);
const all    = await rach.remittance.listTransfers({ page: 1 });
const rates  = await rach.remittance.getRates();

Auth

const rach = new RachFinance();

await rach.auth.register({
  email: '[email protected]', password: 'StrongP@ss1',
  firstName: 'Rachel', lastName: 'Okafor',
  businessName: 'Acme Ltd', country: 'NG',
});

await rach.auth.login({ email: '[email protected]', password: 'StrongP@ss1' });

const me = await rach.auth.getProfile();
await rach.auth.updateProfile({ phone: '+2348012345678', city: 'Lagos' });
await rach.auth.changePassword({ currentPassword: '...', newPassword: '...' });

Two-Factor Auth

const status = await rach.twoFactor.getStatus();
const setup  = await rach.twoFactor.setup();       // get QR code + secret
// Show setup.qr_code to user to scan in their authenticator app
await rach.twoFactor.enable({ secret: setup.secret, code: '123456' });
await rach.twoFactor.disable('654321');

KYC

// 1. Upload documents first
const { upload_url, object_path } = await rach.files.getUploadUrl({
  filename: 'id.jpg', contentType: 'image/jpeg', use: 'kyc',
});
await fetch(upload_url, { method: 'PUT', body: fileBlob });

// 2. Submit KYC
await rach.kyc.submit({
  accountType: 'business',
  businessName: 'Acme Ltd',
  businessRegistration: 'RC123456',
  directorId: object_path,
});

const status = await rach.kyc.getStatus();
// { status: 'pending' | 'approved' | 'rejected' }

Balance & Withdrawals

// Balances
const balances = await rach.balance.get();
await rach.balance.swap({ sourceCurrency: 'USD', destCurrency: 'NGN', amount: '500' });

// Withdraw
await rach.withdrawal.request({
  amount: 500, currency: 'USD', method: 'fiat', settlementAccountId: 3,
});
await rach.withdrawal.request({
  amount: 100, currency: 'USDT', method: 'crypto', network: 'BSC',
});
const history = await rach.withdrawal.history({ page: 1 });

Team

await rach.team.invite({ email: '[email protected]', role: 'developer', permissions: '...' });
const team = await rach.team.list();
await rach.team.updatePermissions('member_id', { role: 'finance', permissions: '...' });
await rach.team.remove('member_id');

Analytics

const dash     = await rach.analytics.dashboard({ days: 30 });
const overview = await rach.analytics.overview({ days: 30 });
const revenue  = await rach.analytics.revenue({ days: 7 });
const txns     = await rach.analytics.transactions({ limit: 50 });

Settings

// Webhook
await rach.settings.webhook.configure({
  webhookUrl: 'https://yourapp.com/webhooks', walletWebhookEnabled: true,
});
const { secret } = await rach.settings.webhook.rotateSecret();
await rach.settings.webhook.test();

// Settlement accounts
await rach.settings.settlement.add({
  currency: 'GBP', bankName: 'Barclays',
  accountNumber: '12345678', accountName: 'Acme Ltd',
});
const accounts = await rach.settings.settlement.list();

// Business wallet
await rach.settings.businessWallet.generate();
const { address } = await rach.settings.businessWallet.getAddress('ETH');

OTC Trading

const quote   = await rach.otc.getQuote({ sourceCurrency: 'USD', destCurrency: 'NGN', amount: 10000 });
const order   = await rach.otc.createOrder({ sourceCurrency: 'USD', destCurrency: 'NGN',
                    sourceAmount: 10000, payoutDetails: 'GTB | 0123456789 | Name' });
await rach.otc.markAsPaid(order.order_id, proofOfPaymentPath);
const status  = await rach.otc.getOrder(order.order_id);
const history = await rach.otc.getHistory();

More services

// Notifications
await rach.notifications.registerToken('fcm_device_token');
await rach.notifications.updatePreferences({ paymentReceived: true, withdrawalSuccess: true });

// API Keys
const keys = await rach.apiKeys.get();
await rach.apiKeys.rotateTest();
await rach.apiKeys.rotateProduction();

// Subscriptions
const plans = await rach.subscription.plans();
await rach.subscription.upgrade({ plan: 'professional', duration: 'monthly' });

// Refunds
await rach.refunds.create({ sessionId: '...', amount: 50, reason: 'Customer request' });
const refund = await rach.refunds.get('refund_id');

// Rates
const rate = await rach.rates.getRate('USD-NGN');

Error handling

All methods throw an error with status, message, and data when the server returns a non-2xx response:

try {
  await rach.checkout.create({ ... });
} catch (err) {
  console.log(err.status);   // 401
  console.log(err.message);  // 'Invalid API key'
  console.log(err.data);     // full response body
}

Browser usage

<script src="https://cdn.jsdelivr.net/npm/rachfinance/index.js"></script>
<script>
  const rach = new window.RachFinance({ apiKey: 'live_sk_...' });
</script>

Webhooks

Configure your endpoint in rach.settings.webhook.configure(). All events POST a JSON payload with a X-Webhook-Signature header (HMAC-SHA256 of the raw body, using your webhook secret).

app.post('/webhooks', (req, res) => {
  const { event, reference, status, blockchain_tx_hash } = req.body;
  if (event === 'payment.confirmed') {
    await fulfillOrder(reference);
  }
  res.sendStatus(200);
});

Support

• Docs: see the docs/ folder
• Email: [email protected]