@yengapay/nodejs-sdk

Official Node.js SDK for YengaPay - Accept mobile money payments and send payouts in West Africa.

Installation

npm install @yengapay/nodejs-sdk
# or
yarn add @yengapay/nodejs-sdk

Features

• 💳 Direct Payment API - Accept mobile money payments via API
• 💸 Payout API - Send money to customers
• 🔄 Fluent Interface - Clean and intuitive API design
• 📦 TypeScript Support - Full type definitions included
• 🌍 Multi-Operator - Support for Orange Money, Moov Money, Coris Money, Sank Money
• 🔐 Secure - API key authentication

Quick Start

import { YengaPayClient } from '@yengapay/nodejs-sdk';

// Initialize the client with fluent interface
const client = new YengaPayClient()
  .withEnvironment('production') // or 'staging', 'development'
  .withApiKey('your-api-key')
  .withGroupId('your-group-id')
  .withProjectId('your-project-id');

// Alternative: custom base URL
const clientCustom = new YengaPayClient()
  .withApiBaseURL('https://api.yengapay.com')
  .withApiKey('your-api-key')
  .withGroupId('your-group-id')
  .withProjectId('your-project-id');

Direct Payment

1. Initialize Payment

// Step 1: Initialize payment and get available operators
const payment = await client.directPayment.init({
  amount: 1000, // Amount in XOF
  reference: 'ORDER-123', // Optional: your order reference
  customerEmailToNotify: '[email protected]', // Optional
  articles: [ // Optional: items being paid for
    {
      title: 'Product 1',
      description: 'Description',
      price: 1000,
      pictures: ['https://example.com/image.jpg']
    }
  ],
  metadata: { orderId: '123', customField: 'value' } // Optional
});

console.log('Payment Intent ID:', payment.paymentIntentId);
console.log('Expires at:', payment.expiresAt);
console.log('Available operators:', payment.availableOperators);

// Example operator:
// {
//   code: 'ORANGE',
//   name: 'Orange Money',
//   countryCode: 'BF',
//   countryName: 'Burkina Faso',
//   flow: 'ONE_STEP',
//   amount: 1000,
//   fees: 25,
//   totalAmount: 1025,
//   minAmount: 200,
//   maxAmount: 1000000
// }

2. Process Payment

One-Step Flow (Orange Money)

const result = await client.directPayment.pay({
  paymentIntentId: payment.paymentIntentId,
  operatorCode: 'ORANGE',
  countryCode: 'BF',
  customerMSISDN: '+22670123456',
  otp: '123456' // Customer enters OTP from their phone
});

if (result.status === 'DONE') {
  console.log('Payment successful!', result.transactionId);
} else if (result.status === 'PENDING') {
  console.log('Payment pending, wait for webhook');
}

Two-Step Flow (Coris Money, Sank Money)

// Step 2a: Send OTP
const otpResult = await client.directPayment.sendOtp({
  paymentIntentId: payment.paymentIntentId,
  operatorCode: 'CORISM',
  countryCode: 'BF',
  customerMSISDN: '+22670123456'
});

console.log(otpResult.message); // "Coris Money vous a envoyé un code OTP par SMS"

// Step 2b: Complete payment with OTP
const result = await client.directPayment.pay({
  paymentIntentId: payment.paymentIntentId,
  operatorCode: 'CORISM',
  countryCode: 'BF',
  customerMSISDN: '+22670123456',
  otp: '123456' // OTP received by customer
});

Push Notification Flow (Moov Money)

const result = await client.directPayment.pay({
  paymentIntentId: payment.paymentIntentId,
  operatorCode: 'MOOV',
  countryCode: 'BF',
  customerMSISDN: '+22670123456'
  // No OTP needed - customer approves on their phone
});

console.log(result.message); // "Le client doit valider sur son téléphone"

3. Check Payment Status

const status = await client.directPayment.getStatus(payment.paymentIntentId);

console.log('Status:', status.status); // PENDING, DONE, FAILED
if (status.status === 'DONE') {
  console.log('Transaction ID:', status.transactionId);
  console.log('Amount:', status.amount);
  console.log('Fees:', status.fees);
}

Payout

Single Payout

const payout = await client.payout.create({
  amount: 5000, // Amount in XOF
  destNumber: '+22670123456',
  destName: 'John Doe', // Optional
  destEmail: '[email protected]', // Optional
  paymentMethod: 'ORANGE_MONEY', // ORANGE_MONEY, MOOV_MONEY, TELECEL_MONEY, CORIS_MONEY, SANK_MONEY
  description: 'Payment for services' // Optional
});

console.log('Payout ID:', payout.id);
console.log('Status:', payout.status); // PENDING, PROCESSING, SUCCESS, FAILED

Bulk Payout

const bulkPayout = await client.payout.createBulk({
  name: 'Monthly Salaries', // Optional
  payouts: [
    {
      amount: 50000,
      destNumber: '+22670111111',
      destName: 'Employee 1',
      paymentMethod: 'ORANGE_MONEY'
    },
    {
      amount: 45000,
      destNumber: '+22670222222',
      destName: 'Employee 2',
      paymentMethod: 'MOOV_MONEY'
    }
  ]
});

console.log('Bulk Payout ID:', bulkPayout.id);
console.log('Total Count:', bulkPayout.totalCount);
console.log('Success Count:', bulkPayout.successCount);
console.log('Failed Count:', bulkPayout.failedCount);

Check Payout Status

// Single payout
const payoutStatus = await client.payout.getStatus('payout-id');
console.log(payoutStatus.status); // PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED

// Bulk payout
const bulkStatus = await client.payout.getBulkStatus('bulk-payout-id');
console.log(`Progress: ${bulkStatus.successCount}/${bulkStatus.totalCount}`);

Error Handling

import { YengaPayError, AuthenticationError, ValidationError } from '@yengapay/nodejs-sdk';

try {
  const payment = await client.directPayment.init({ amount: 100 });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key or permissions');
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof YengaPayError) {
    console.error('YengaPay error:', error.message, error.statusCode);
  } else {
    console.error('Unknown error:', error);
  }
}

Supported Operators

| Operator | Code | Countries | Flow Type | |----------|------|-----------|-----------| | Orange Money | ORANGE | BF, CI, SN, ML, NE | ONE_STEP | | Moov Money | MOOV | BF, CI, TG, BJ | TWO_STEP (Push) | | Coris Money | CORISM | BF | TWO_STEP (OTP) | | Sank Money | SANKM | BF | TWO_STEP (OTP) | | Telecel Money | TELECEL | BF | TWO_STEP |

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  InitDirectPaymentParams,
  ProcessPaymentParams,
  PaymentStatusResponse,
  CreatePayoutParams,
  AvailableOperator
} from '@yengapay/nodejs-sdk';

Development

# Build the SDK
nx build nodejs-sdk

# Run tests
nx test nodejs-sdk

# Lint
nx lint nodejs-sdk

License

MIT

Support

For support, email [email protected] or visit https://yengapay.com/docs