Response Codes

We have a set of response and status codes at both the acknowledgement and callback levels.

With Async Payouts, the instructions will be acknowledged, and the webhook will share status changes as the transaction is updated.

Successful response code

If you get a successful response with code MR101, then you know that is the final status, and it was successful.

Failure response codes

If you get any ER response then the transaction has failed and the status will never change. The partner should re-initiate the transaction following resolution of the issue highlighted in the ER status description.

A transaction that receives a clear error response (any ER code) is considered failed and will not be reprocessed. Where the sender has already been charged, the partner can safely refund the sender. Where the sender has not been charged, no refund is necessary.

Pending response code

A pending result may occur due to downstream systems are processing the transaction.

❗️
Note:
For pending responses, a call back will be sent to the partner when final status is confirmed.

callService Response Codes - Acknowledgement

The table below describes the available response codes in the acknowledgement level

Code	Message	Description
100	Success	Instruction Successful
101	Fail	Instruction unsuccessful

The status code 101 will never change status; once instruction is unsuccessful, the partner should re-initiate the transaction following resolution of the issue returned in the fail message.

The following table shows you what to do based on the fail message you get.

Fail Message	Action
Invalid Credentials	Check password or corporate code provided if valid
Credentials required	Check either password or corporateCode should be set in the request if missing
MfsSign is required	Check MfsSign should be set the request if missing
MfsSign is invalid	generated mfsSign is not correct(refer section 4.1.1 to see how its generated
BatchId is required	Check batchId should be set in the request
BatchId is Duplicated	Send new batch with unique batchId
Transaction already exist with given ThirdParty	Send transaction with new unique thirdparty
ThirdParty is required	Check thirdParty should be set in the request
Amount is required	Amount must be greater than zero or amount object should be set from request
Amount currency is required	Amount currency should be set from the request
Amount currency code must be less or equal to 3	Currency code is in format(ISO 4217)
Recipient Account number is required	If destAcctType is set to 2(bank) Recipient Account number should be set in the request
Invalid Account number provided	Account number is numeric value(may be mobile wallet account or bank account) e.g 534677268
MFS Bank code is required	If destAcctType is set to 2(bank) ,check MfsBankCode should be set in the request
Destination type is required	Check destAcctType should be set in the request
Destination type value not permitted	Check destAcctType can only be either set to 1(Mobile Wallet) or 2(bank)
Amount type value not permitted	Check amountType can only be either 1(Send amount) or 2(Receive (payout) amount)
Send Fee is required	If amountType is set to 1(Send amount) then sendFee Object needs to be set
Send Fee Amount currency is required	If amountType is set to 1(Send amount) then sendFee currency needs to be set
Send Fee Amount currency must be equal to 3	Currency code is in format (ISO 4217)
Send Fee Amount is required	If amountType is set to 1(Send amount) then sendFee amount needs to be set
InstructionType is required	Check instructionType object should be set in the request
FromCountry is required	Check fromCountry should be set in the request
Invalid fromCountry	country must be in format fromCountry should be in format (ISO-31662)
Sender Name is required	Check sender Name should be set in the request
Sender Surname is required	Check sender Surname should be set in the request
Sender is required	Check Sender object missing in the request
Recipient msisdn is required	if destAcctType is set to 1(mobile wallet) then recipient Msisdn needs to be set
Recipient msisdn has invalid format	msisdn passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900
ToCountry is required	Check toCountry should be set in the request
Invalid To Country	country must be in format toCountry should be in format (ISO 3166-2)
Recipient Name is required	Check recipient name should be set in the request
Recipient Surname is required	Check recipient surname should be set in the request
Recipient is required	Check Recipient Object missing in the request
Exceeded Tx Limit	Transactions size should not exceed the agreed amount of transactions per batch

callService Callback - Response Codes

The table below describes the available response codes in the callback sent to share status changes as the transaction is updated.

Code	Message	Description	Action
MR101	Success	The transaction has been successfully executed to the destination platform.	No further action is required.
ER103	Partner corridor not active	The attempted corridor is inactive.	Contact Onafriq Support.
ER108	Subscriber not found	Subscriber not registered on destination platform.	Double check the mobile number, and/or inform sending customer that the recipient account cannot be found on the destination platform, thus the transfer cannot proceed.
ER109	Subscriber not authorized to receive amount	Amount being sent exceeds the limit allowed for the client.	Contact recipient before retry, alternatively try smaller amount.
ER110	Insufficient fund in merchant account	The transaction failed due to insufficient funds on the on the E-wallet merchant account to process the transaction.	Contact Onafriq Support
ER111	Transaction could not be executed	The requested transaction cannot be executed.	Failure on receiving wallet. Refund sender.
ER200	E-Wallet System error	The transaction failed due to an error occurring on the E-Wallet platform.	Failure on receiving wallet. Refund sender.
ER201	MFS System error	The transaction failed due to an error occurring on the Onafriq platform.	Contact Onafriq Support.
ER202	Blacklist error	The log failed as the subscriber matched to a blacklist item	Contact Onafriq Support.
ER203	Daily Sender Velocity Limit Exceeded	The log failed as the request causes the daily velocity limit to be exceeded for the sender	Retry next day.
ER204	Daily Recipient Velocity Limit Exceeded	The log failed as the request causes the daily velocity limit to be exceeded for the recipient	Retry next day.
ER205	Weekly Sender velocity Limit Exceeded	The log failed as the request causes the weekly velocity limit to be exceeded for the sender	Retry next week.
ER206	Weekly Recipient velocity Limit Exceeded	The log failed as the request causes the weekly velocity limit to be exceeded for the recipient	Retry next week.
ER207	Monthly Sender velocity Limit Exceeded	The log failed as the request causes the monthly velocity limit to be exceeded for the sender	Retry next month.
ER208	Monthly Recipient velocity Limit Exceeded for Recipient	The log failed as the request causes the monthly velocity limit to be exceeded for the recipient	Retry next month.
ER209	Transaction Max Amount exceeded	The log failed as the max transaction amount will be /has been exceeded.	Confirm max transaction limit, amend amount and retry.
ER212	Invalid bank account number	The bank account number provided is invalid.	Confirm and provide valid bank account number and retry. Or inform sending customer that the recipient bank account number provided is invalid, thus the transfer cannot proceed.
ER213	Invalid MFS Africa bank code	The Onafriq bank code provided is invalid.	Correct mfs bank code and retry.
ER500	Internal server error	The transaction failed due to an error in the processing flow.	Contact Onafriq Support.