HunterTechPay SDK - JavaScript/TypeScript

Official SDK for integrating HunterTechPay into your JavaScript/TypeScript applications.

Version: 1.1.0 Last Updated: March 14, 2026

Table of Contents

• Installation
• Quick Start
• Available Methods
• Complete Examples
• Security
• Error Handling
• Support

Installation

npm install crypto-js
# or
yarn add crypto-js

Copy the huntertechpay.js file into your project.

Quick Start

Initialization

import HunterTechPay from './huntertechpay';

const hunter = new HunterTechPay({
  apiKey: 'htp_live_abc123...',      // API Key provided by HunterTechPay
  secretKey: 'sk_live_xyz789...',    // Secret Key (NEVER expose on client side!)
  baseUrl: 'https://api.huntertechpay.com'  // Production URL
});

Available Methods

1. Get Available Providers

const providers = await hunter.getProviders('CM');

console.log(providers);
// {
//   success: true,
//   country_code: 'CM',
//   currency: 'XAF',
//   providers: [
//     {
//       provider_code: 'orange_money',
//       name: 'Orange Money Cameroun',
//       cashin_service_code: 'OM_CM_CASHIN',   // ✅ Code for deposit
//       cashout_service_code: 'OM_CM_CASHOUT', // ✅ Code for withdrawal
//       supports_cashin: true,
//       supports_cashout: true,
//       logo_url: 'https://...',
//       is_active: true
//     }
//   ]
// }

2. Deposit (CASHIN) - Mobile Money → Wallet

Transfer money from a mobile money account to the HunterTechPay wallet.

const deposit = await hunter.deposit({
  amount: 5000,                    // Amount in XAF
  currency: 'XAF',                 // Currency (must match country)
  country: 'CM',                   // Country code (CM, SN, CI, etc.)
  phone: '+237690000000',          // Customer phone number
  provider: 'orange_money',        // Selected provider
  reference: 'DEPOSIT_' + Date.now(), // Your unique reference
  description: 'Deposit to wallet',   // Description (optional)
  callback_url: 'https://mysite.com/webhook', // Webhook (optional)
});

console.log('Deposit initiated:');
console.log('Transaction ID:', deposit.transaction_id);
console.log('Status:', deposit.status);  // 'pending', 'success', etc.

Flow:

1. User initiates a deposit
2. System automatically uses the CASHIN service code (e.g., OM_CM_CASHIN)
3. User receives a USSD push to confirm payment
4. Amount is debited from mobile money and credited to wallet

3. Withdraw (CASHOUT) - Wallet → Mobile Money

Transfer money from the HunterTechPay wallet to a mobile money account.

const withdrawal = await hunter.withdraw({
  amount: 3000,                       // Amount in XAF
  currency: 'XAF',                    // Currency (must match country)
  country: 'CM',                      // Country code
  phone: '+237670000000',             // Recipient phone number
  provider: 'mtn_momo',               // Selected provider
  reference: 'WITHDRAW_' + Date.now(), // Your unique reference
  description: 'Withdrawal to mobile money', // Description (optional)
  callback_url: 'https://mysite.com/webhook', // Webhook (optional)
});

console.log('Withdrawal initiated:');
console.log('Transaction ID:', withdrawal.transaction_id);
console.log('Status:', withdrawal.status);

Validation:

• System checks available balance before authorizing withdrawal
• System verifies CASHOUT is enabled for merchant

4. Initiate Generic Payment

const payment = await hunter.initiatePayment({
  amount: 5000,
  currency: 'XAF',
  country: 'CM',
  phone: '+237690000000',
  provider: 'orange_money',
  reference: 'ORDER_123',
  description: 'Purchase product XYZ',
  callback_url: 'https://mysite.com/webhook',
  return_url: 'https://mysite.com/success'
});

console.log('Payment initiated:', payment.transaction_id);

5. Check Transaction Status

// By transaction_id
const status = await hunter.checkStatus('txn_abc123');

// By reference
const status = await hunter.checkStatus('ORDER_123', 'reference');

console.log('Status:', status.status);  // 'pending', 'success', 'failed'
console.log('Amount:', status.amount);
console.log('Currency:', status.currency);

6. List Transactions

const transactions = await hunter.listTransactions({
  page: 1,
  page_size: 50,
  status: 'success',            // Filter by status (optional)
  start_date: '2026-03-01',     // Start date (optional)
  end_date: '2026-03-14'        // End date (optional)
});

console.log('Total transactions:', transactions.total);
transactions.transactions.forEach(tx => {
  console.log(`${tx.transaction_id}: ${tx.amount} ${tx.currency}`);
});

7. Get Balance

const balance = await hunter.getBalance('merchant_123');

console.log('Available balance:', balance.available_balance, balance.currency);
console.log('Pending balance:', balance.pending_balance, balance.currency);

Complete Examples

React Example

import React, { useState, useEffect } from 'react';
import HunterTechPay from './huntertechpay';

function PaymentPage() {
  const [providers, setProviders] = useState([]);
  const [loading, setLoading] = useState(false);

  // ⚠️ IMPORTANT: Initialize on server side, NEVER on client side!
  // This code should be in your backend Node.js
  const hunter = new HunterTechPay({
    apiKey: process.env.HUNTER_API_KEY,
    secretKey: process.env.HUNTER_SECRET_KEY,
  });

  useEffect(() => {
    loadProviders();
  }, []);

  const loadProviders = async () => {
    try {
      const data = await hunter.getProviders('CM');
      setProviders(data.providers);
    } catch (error) {
      console.error('Error:', error.message);
    }
  };

  const handleDeposit = async (provider) => {
    setLoading(true);
    try {
      const deposit = await hunter.deposit({
        amount: 5000,
        currency: 'XAF',
        country: 'CM',
        phone: '+237690000000',
        provider: provider.provider_code,
        reference: 'DEPOSIT_' + Date.now(),
      });

      alert(`Deposit initiated! ID: ${deposit.transaction_id}`);
    } catch (error) {
      alert(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <h1>Deposit to Wallet</h1>
      <div className="providers">
        {providers.map(provider => (
          <div key={provider.provider_code} className="provider-card">
            <img src={provider.logo_url} alt={provider.name} />
            <h3>{provider.name}</h3>
            <p>CASHIN Code: {provider.cashin_service_code}</p>
            <button
              onClick={() => handleDeposit(provider)}
              disabled={!provider.supports_cashin || loading}
            >
              {provider.supports_cashin ? 'Deposit' : 'Not available'}
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

export default PaymentPage;

Security - VERY IMPORTANT

❌ NEVER DO THIS

// ❌ DANGER: Exposing secret key on client side
const hunter = new HunterTechPay({
  apiKey: 'htp_live_...',
  secretKey: 'sk_live_...'  // ❌ EXPOSED in browser!
});

✅ CORRECT APPROACH

// ✅ Frontend (React, Vue, Angular)
const handlePayment = async () => {
  // Call your backend
  const response = await fetch('/api/payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: 5000,
      provider: 'orange_money',
      phone: '+237690000000'
    })
  });

  const data = await response.json();
  console.log('Transaction ID:', data.transaction_id);
};

// ✅ Backend (Node.js/Express)
app.post('/api/payment', async (req, res) => {
  const hunter = new HunterTechPay({
    apiKey: process.env.HUNTER_API_KEY,      // ✅ Secure
    secretKey: process.env.HUNTER_SECRET_KEY, // ✅ Server side only
  });

  try {
    const deposit = await hunter.deposit({
      amount: req.body.amount,
      currency: 'XAF',
      country: 'CM',
      phone: req.body.phone,
      provider: req.body.provider,
      reference: 'DEP_' + Date.now()
    });

    res.json(deposit);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Error Handling

try {
  const deposit = await hunter.deposit({...});
} catch (error) {
  if (error instanceof HunterTechPayError) {
    console.error('Error code:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Data:', error.data);

    // Specific error handling by code
    switch (error.statusCode) {
      case 400:
        alert('Invalid parameters: ' + error.message);
        break;
      case 403:
        alert('Access denied: ' + error.message);
        break;
      case 404:
        alert('Provider not found');
        break;
      default:
        alert('Error: ' + error.message);
    }
  } else {
    console.error('Network error:', error);
  }
}

Currency/Country Validation

The SDK automatically validates that the currency matches the country:

| Country | Accepted Currency | Rejected Currency | |---------|-------------------|-------------------| | CM (Cameroon) | ✅ XAF | ❌ XOF | | SN (Senegal) | ✅ XOF | ❌ XAF |

Error Example:

// Attempt: XOF in Cameroon
const deposit = await hunter.deposit({
  currency: 'XOF',  // ❌ Error
  country: 'CM'
});

// Error returned:
// "Invalid currency for country CM. Expected XAF, got XOF"

License

MIT

Support

• Complete Documentation: DOCUMENTATION_INDEX.md
• Email: [email protected]
• GitHub: https://github.com/hunter-tech-africa