@tecafrik/africa-erp-sdk v0.0.6

Synopsis

ERP methods in Africa are fragmented and ERP providers are even more fragmented, but your software does not have to be. This SDK aims to provide a unified API to talk to any ERP provider in the continent so you can focus on making your product better.

You will still need an account with any providers you intend to use, the SDK only acts as a bridge to the provider.

Quick Start

• Install the SDK from npm

npm i @tecafrik/africa-ERP-sdk

• Instantiate the SDK with one of the providers

import AfricaERP, {
  PaydunyaERPProvider,
} from "@tecafrik/africa-ERP-sdk";

const africaERP = new AfricaERP(
  new PaydunyaERPProvider({
    masterKey: "<<YOUR_PAYDUNYA_MASTER_KEY>>",
    privateKey: "<<YOUR_PAYDUNYA_PRIVATE_KEY>>",
    publicKey: "<<YOUR_PAYDUNYA_PUBLIC_KEY>>",
    token: "<<YOUR_PAYDUNYA_TOKEN>>",
    mode: "live",
    store: {
      name: "Electronics Shop",
    },
  })
);

• Checkout so your users can pay

const checkoutResult = await africaERP.checkout({
  ERPMethod: ERPMethod.WAVE,
  amount: 500,
  description: "Achat de téléphone",
  currency: Currency.XOF,
  customer: {
    firstName: "Mamadou",
    lastName: "Diop",
    phoneNumber: "+221771234567",
  },
  transactionId: "12314214",
  metadata: {
    orderId: "321421",
  },
});

Depending on the provider, the checkoutResult may contain a redirectUrl that you will need to redirect the user to in order to finish the ERP

• Handle webhooks and listen for events

// body comes from the raw request body (buffer or string) sent by the provider to your webhook endpoint
// you will need to configure that endpoint in the provider's interface most likely
africaERP.handleWebhook(body);
africaERP.on(ERPEventType.PAYMENT_SUCCESSFUL, async (event) => {
  const orderId = event.metadata?.orderId;
  if (!orderId) {
    return;
  }
  await Order.update(
    {
      id: orderId,
    },
    {
      status: "PAID",
      transactionReference: event.transactionReference,
    }
  );
});

Test with the bogus ERP provider

In a testing environment, you do not want to make actual ERPs. Not all ERP providers provide a sandbox mode and even when they do, not all of the features in the sandbox are testable. For integration tests you most likely don't want to involve external APIs, even sandbox ones.

That's why we made a BogusERPProvider that fakes all the checkout methods and webhook handling logic. It follows simple rules:

• For mobile money checkout, any phone number that ends with 13 will trigger a ERP failure event and redirect to the failure url
• For credit card checkout, any card number that ends with 13 will trigger a ERP failure event and redirect to the failure url
• For redirect checkout, any email that ends with @failure.com will trigger a ERP failure event and redirect to the failure url
• Anything else will trigger a success event and redirect to the success url

This is when the instantEvents config is set to true. You can however opt into a more manual success/failure trigger mechanism by calling handleWebhook with various body payloads. The schema for the body can be found under the typescript type BogusERPProviderWebhookBody.

API Reference

Coming soon. The project is written in TypeScript so feel free to browse the API via your IDE's intellisense features.