Cookbook

Common integration patterns and recipes for NabooPay.

Accepting Payments

Basic Payment

Accept a simple one-time payment:

const payment = await fetch('https://api.naboopay.com/api/v2/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method_of_payment: ['wave', 'orange_money', 'bank'],
    products: [{
      name: 'Product Name',
      category: 'general',
      price: 5000,
      quantity: 1
    }],
    success_url: 'https://yoursite.com/success',
    error_url: 'https://yoursite.com/error'
  })
}).then(r => r.json());

// Redirect customer
window.location.href = payment.checkout_url;

Multiple Products

Sell multiple items in one transaction:

const cart = await fetch('https://api.naboopay.com/api/v2/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method_of_payment: ['wave', 'orange_money', 'bank'],
    products: [
      {
        name: 'T-Shirt (Large)',
        category: 'clothing',
        price: 15000,
        quantity: 2,
        description: 'Cotton t-shirt, blue'
      },
      {
        name: 'Shipping',
        category: 'shipping',
        price: 2000,
        quantity: 1
      }
    ],
    success_url: 'https://yoursite.com/order/success',
    error_url: 'https://yoursite.com/order/failed'
  })
}).then(r => r.json());

Card-Only Payment

Accept only card payments (Visa & Mastercard):

const payment = await fetch('https://api.naboopay.com/api/v2/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method_of_payment: ['bank'],
    products: [{
      name: 'Premium Subscription',
      category: 'subscription',
      price: 25000,
      quantity: 1
    }],
    success_url: 'https://yoursite.com/success',
    error_url: 'https://yoursite.com/error'
  })
}).then(r => r.json());

With Customer Info

Include customer details for better tracking:

const payment = await fetch('https://api.naboopay.com/api/v2/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method_of_payment: ['wave', 'orange_money'],
    products: [{
      name: 'Order #1234',
      category: 'order',
      price: 50000,
      quantity: 1
    }],
    customer: {
      name: 'Amadou Diallo',
      email: 'amadou@example.com',
      phone: '+221771234567'
    },
    success_url: 'https://yoursite.com/success',
    error_url: 'https://yoursite.com/error'
  })
}).then(r => r.json());

---

Sending Payouts

Send Money to Wave

const payout = await fetch('https://api.naboopay.com/api/v2/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    full_name: 'Fatou Ndiaye',
    phone_number: '+221771234567',
    amount: 10000,
    method_of_payment: 'wave'
  })
}).then(r => r.json());

console.log(payout.payout_id); // payout_xyz789
console.log(payout.status);    // 'pending' or 'completed'

Send Money to Orange Money

const payout = await fetch('https://api.naboopay.com/api/v2/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    full_name: 'Ousmane Ba',
    phone_number: '+221761234567',
    amount: 25000,
    method_of_payment: 'orange_money'
  })
}).then(r => r.json());

Check Balance Before Payout

Always verify you have sufficient funds:

async function sendPayout(recipient, amount, method) {
  // 1. Check balance
  const accounts = await fetch('https://api.naboopay.com/api/v2/accounts', {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  }).then(r => r.json());

  const balance = accounts.accounts[0].balance;

  if (balance < amount) {
    throw new Error(`Insufficient balance: ${balance} XOF (need ${amount} XOF)`);
  }

  // 2. Send payout
  const payout = await fetch('https://api.naboopay.com/api/v2/payouts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      full_name: recipient.name,
      phone_number: recipient.phone,
      amount: amount,
      method_of_payment: method
    })
  }).then(r => r.json());

  return payout;
}

// Usage
await sendPayout(
  { name: 'Fatou Ndiaye', phone: '+221771234567' },
  10000,
  'wave'
);

---

Managing Transactions

List Recent Transactions

const transactions = await fetch(
  'https://api.naboopay.com/api/v2/transactions?limit=20',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());

transactions.forEach(t => {
  console.log(`${t.order_id}: ${t.status} - ${t.amount} XOF`);
});

Filter by Status

// Get only paid transactions
const paid = await fetch(
  'https://api.naboopay.com/api/v2/transactions?status=paid',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());

// Get pending transactions
const pending = await fetch(
  'https://api.naboopay.com/api/v2/transactions?status=pending',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());

Filter by Date Range

const startDate = '2024-01-01';
const endDate = '2024-01-31';

const januaryTransactions = await fetch(
  `https://api.naboopay.com/api/v2/transactions?start_date=${startDate}&end_date=${endDate}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());

Cancel a Pending Transaction

const cancelled = await fetch(
  `https://api.naboopay.com/api/v2/transactions/${orderId}`,
  {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  }
).then(r => r.json());

console.log(cancelled.status); // 'cancelled'

---

Account Management

Get Account Balance

const accounts = await fetch('https://api.naboopay.com/api/v2/accounts', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
}).then(r => r.json());

const currentAccount = accounts.accounts.find(a => a.type === 'current');
console.log(`Balance: ${currentAccount.balance} XOF`);

Get Account Statistics

const stats = await fetch(
  `https://api.naboopay.com/api/v2/accounts/${accountId}/stats`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());

console.log('Total received:', stats.total_received);
console.log('Total sent:', stats.total_sent);

---

Error Handling

Wrap API Calls

async function nabooPayRequest(endpoint, options = {}) {
  const response = await fetch(`https://api.naboopay.com/api/v2${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  const data = await response.json();

  if (!response.ok) {
    const error = new Error(data.error || 'API request failed');
    error.status = response.status;
    error.data = data;
    throw error;
  }

  return data;
}

// Usage with error handling
try {
  const payment = await nabooPayRequest('/transactions', {
    method: 'POST',
    body: JSON.stringify({
      method_of_payment: ['wave'],
      products: [{ name: 'Test', category: 'test', price: 1000, quantity: 1 }],
      success_url: 'https://example.com/success',
      error_url: 'https://example.com/error'
    })
  });
} catch (error) {
  if (error.status === 401) {
    console.error('Invalid API key');
  } else if (error.status === 429) {
    console.error('Rate limited - slow down requests');
  } else {
    console.error('Error:', error.message);
  }
}

---

Testing Checklist

Before going live, verify:

• API key works in production environment
• Transactions create successfully
• Checkout page loads and displays correctly
• Success/error URLs redirect properly
• Webhook endpoint receives and processes events
• Payouts send to correct recipients
• Error handling works for common failures
• Rate limiting is handled gracefully