@afrinet/sdk

Official Node.js SDK for the Afrinet Transaction Engine.

Server-side only. Never expose apiSecret in browsers or mobile clients.

Install

npm install @afrinet/sdk

Quick start

import Afrinet from "@afrinet/sdk";

const afrinet = new Afrinet({
  apiKey: process.env.AFRINET_API_KEY!,
  apiSecret: process.env.AFRINET_API_SECRET!,
  merchantId: process.env.AFRINET_MERCHANT_ID!,
  environment: "sandbox", // or "production"
});

// M-Pesa charge
const charge = await afrinet.charges.create({
  reference: "INV-API-001",
  description: "Order payment",
  amount: { currency: "KES", value: 1500 },
  paymentMethod: {
    paymentType: "mpesa",
    details: { type: "c2b", phoneNumber: "254712345678" },
  },
});

// Card charge
await afrinet.charges.create({
  reference: "INV-CARD-001",
  description: "Card checkout",
  amount: { currency: "KES", value: 1500 },
  paymentMethod: {
    paymentType: "card",
    details: {
      mode: "HOSTED_CHECKOUT",
      returnUrl: "https://merchant.example.com/return",
      cancelUrl: "https://merchant.example.com/cancel",
    },
  },
});

// M-Pesa payout
await afrinet.payouts.create({
  reference: "PO-API-001",
  description: "Vendor payout",
  recipient: [{
    amount: { currency: "KES", value: 500 },
    paymentMethod: {
      paymentType: "mpesa",
      details: {
        type: "b2c",
        phoneNumber: "254712345678",
        commandId: "BusinessPayment",
      },
    },
  }],
});

// Reversal
await afrinet.reversals.create({
  transactionCode: "04LCM000001",
  reason: "Customer refund",
});

Configuration

| Option | Required | Default | |--------|----------|---------| | apiKey | Yes | — | | apiSecret | Yes | — | | merchantId | Yes | — | | environment | No | sandbox | | baseUrl | No | env base URL | | timeout | No | 30000 ms | | maxNetworkRetries | No | 2 |

Security

• Requests are signed with HMAC-SHA256 (X-Afrinet-Signature)
• Secrets are never logged by the SDK (sanitizeForLogging helper included)
• Browser usage is blocked at initialization

Errors

import {
  AfrinetAuthenticationError,
  AfrinetInvalidRequestError,
  AfrinetApiError,
} from "@afrinet/sdk";

try {
  await afrinet.charges.create({ ... });
} catch (error) {
  if (error instanceof AfrinetAuthenticationError) {
    // invalid key or signature
  }
}

Development

npm install
npm test
npm run build