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:

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.

Program FSP Configuration

When adding Onafriq as an FSP to a program, the following configuration properties must be set.

• corporateCodeOnafriq - This differs per used wallets. Multiple programs can use the same wallet.
• passwordOnafriq - This is currently the same across all wallets, but this may change in the future.
• uniqueKeyOnafriq - This is currently the same across all wallets, but this may change in the future.

Subscribe to webhook

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

As typically every program uses a new wallet, this functionality works per program. Although technically - if a new program uses an existing wallet - this is not needed.

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

IMPORTANT: This step should not be forgotten, as forgetting it will not lead transaction requests to be blocked right away. Instead, simply no callback will come in, which is not informative.

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.