Onafriq

This page contains information about configuring the Onafriq FSP integration in a 121 Platform Instance.

Configure Environment Variables

For the Onafriq FSP integration to work for any program, some settings need to be configured via environment variables:

Corporate code

ONAFRIQ_CORPORATE_CODE

The value is the corporate code provided by Onafriq.

Password

ONAFRIQ_PASSWORD

The value is the password provided by Onafriq.

Unique key

ONAFRIQ_UNIQUE_KEY

The value is a unique key provided by Onafriq.

API url

ONAFRIQ_API_URL

IMPORTANT: It should end with a trailing slash! The value is the base URL of Onafriq's API. The sandbox URL is https://async-v2.dev.apimfsafrica.com/. In production and staging, a different URL is used.

Currency code

ONAFRIQ_CURRENCY_CODE

The value is the currency code, e.g. 'CDF' for Congolese Franc. Currently 121 is set up only for currency CDF.

Country code

ONAFRIQ_COUNTRY_CODE

The value is the country code, e.g. 'CD' for DRC. Currently 121 is set up only for country DRC.

Sender details

Sender account details ONAFRIQ_SENDER_{MSISDN/NAME/SURNAME/DOB/DOCUMENT_ID/DOCUMENT_TYPE} are needed. They should identify the wallet from which money is transferred.

SFTP credentials

Sftp credentials ONAFRIQ_SFTP_{HOST/PORT/USERNAME/PASSPHRASE} are needed for sending the daily reconciliation report to Onafriq. Additionally, you need a private key file.

Subscribe to webhook

To be able to receive transaction status updates via callback, you have to configure the callback url once for every new environment (or again, when 121's callback URL would change for any reason. The 121 dev team will inform you of this.)

You can configure the callback URL simply by calling the POST /api/fsps/onafriq/webhook/subscribe endpoint. The right URL does not need to be passed, but is constructed from code.

IMPORTANT: There is a delay for the callbackUrl to be effectively updated. Even though the available GET /webhook/{ONAFRIQ_CORPORATE_CODE} immediately returns the updated callbackUrl, in practice callbacks related to transactions created after the webhook update are still sent to the old callbackUrl for some time. This delay is around 30 minutes according to Onafriq, but to be on the safe side it is good to take at least 2 hours.

Configuration

121 uses the Mobile wallet flow of Onafriq, where money is transferred from a sender mobile wallet to the recipients mobile wallet. Onafriq offers also Bank or Cash Pick Up transactions, but 121 does not use those at the moment.

Onafriq is a payment aggregator that can transfer money to a wide variety of local FSPs in many countries. This local FSP is not specified in the payment request from 121, but determined based on the recipient's phone number. Onafriq can however configure on setup that e.g. only Vodacom/Vodacash phone numbers are allowed, and other phone numbers are blocked.

Different countries have different required fields. Currently the 121 codebase is set up based on the requirements for DRC only.

Payment flow

When a payment is made to a registration with Onafriq FSP, then money is transferred to the mobile wallet of the recipient.

After a payment is made in the 121 platform, transactions are created with the status 'waiting' (indicating that at ths point we know only that the request to Onafriq transaction, but not yet of the payout to the recipient was successful). Once Onafriq has made the (un)succesful transaction to the recipient they inform us via callback of the transaction status. There is also an Onafriq endpoint 121 can call to proactively get the status. This is not used at the moment, but could be in the future as a backup for failing callbacks if applicable.

Onafriq API documentation

For more information about Onafriq's API used, see the Onafriq Async API documentation on Onafriq's website.