Error Handling

Callback Error Codes

The table below contains the error codes returned in the application callback / webhook payload. This is populated in the field error_message of the payload.

Format:

{
	//...
  "error_message": "Error Code | Error Fault | Error Message",
	//...
}

Sample output:

{
	//...
  "error_message": "5200 | Merchant | Invalid account number",
	//...
}

Error Code	Error Fault	Error Message
3100	Switch	The transaction failed processing at the switch - General Error
3110	Switch	The transaction failed processing at the switch - Internal Error
3120	Provider	A Backend Error occurred at the payment provider
3130	Switch	Transaction failed with no reason returned from the switch
3200	Switch	Failure to queue transaction at the switch due to downtime or server load on the switch
3210	Switch	Provider failure to authenticate at the switch due to server load on the switch
3300	Switch	Customer information mismatch at the switch
4100	Customer	Customer has insufficient / low balance, or account limit(s) have been reached
4200	Customer	Customer failed to 1. Respond to the prompt on time or 2. Enter the correct pin
5100	Merchant	Customer is either not registered for this service, invalid network, account is ported, inactive or dormant
5200	Merchant	Invalid account number
5210	Merchant	Invalid amount
6100	Provider	Transaction is found to be a duplicate at the provider / switch. Wait a few minutes and retry.
6200	Switch	The transaction failed processing at the switch - Backend Error
6300	Provider	Email field must contain a valid email
6400	Provider	The provider's balance with the switch is low / insufficient to perform the transaction
6500	Provider	Failure to queue transaction at the provider due to downtime or server load on the provider
7100	OGateway	Transaction Processing Failed at OGateway

Error Faults

There are 5 Error Fault types maintained by Open Gateway

Fault Name	Reason / Description
Customer	Customer fault stems from situations where the final outcome of a transaction is customer dependent e.g. when a customer fails to enter their pin to approve a transaction, or when a customers daily limit on their account is exceeded.
Merchant	Merchant faults are due to incorrect information passed to OGateway such as a provided phone number with an incorrect network, or an incorrect phone number.
OGateway	OGateway faults relate to internal issues that may occur at OGateways side which may include brief service disruptions causing transaction failures.
Provider	We work with partners in processing our transactions. These partners may have brief service disruptions causing some transactions to fail.
Switch	These faults emanate from the Telco, Bank or the national switch (GHIPSS) depending on where a provider routes the transaction through. This is the final error fault level.

Examples

Customer Fault

The customer failed to respond to the Mobile Money prompt, or did not go to their approvals screen to approve the transaction.

{
  "id": "5ba941b5-eb5c-4618-b8ec-4d1419fb2d38",
  "amount": "22",
  "fee": "0",
  "currency": "GHS",
  "status": "FAILED",
  "channel": "MOMO",
  "type": "DEBIT",
  "reason": "Payment for services",
  "network": "MTN",
  "bear_fee": "business",
  "customer": {
    "accountName": "Bernard Danso",
    "accountNumber": "0249123456"
  },
  "metadata": {
    "transactionAmount": 132, //for payouts
    "smsFee": 0 //for collections
  },
  "created_at": "2023-07-06T13:35:41.308Z",
  "updated_at": "2023-07-06T13:40:41.308Z",
  "checkout_url": null,
  "instructions": "If no prompt pops up, pls check your Approval List by dialing *170# and choosing option 6 then option 3.", // for collections
  "error_message": "4200 | Customer | Customer failed to 1. Respond to the prompt on time or 2. Enter the correct pin",
  "telco_response": "Request timeout",
  "virtual_account": null,
  "provider_message": "Failed",
  "reference_business": "d20d4d8df15712345432"
}

Merchant Fault

An invalid account number was used for the transaction i.e. an MTN number was used instead of a valid VOD number.

{
  "id": "5ba941b5-eb5c-4618-b7ce-4d1419fb2d38",
  "fee": 120.52,
  "type": "CREDIT",
  "amount": 6026,
  "reason": "CREDIT_MOMO",
  "status": "FAILED",
  "channel": "MOMO",
  "network": "VOD",
  "bear_fee": "business",
  "currency": "GHS",
  "customer": {
    "accountName": "Bernard Danso",
    "accountNumber": "0249123456"
  },
  "metadata": {
    "transactionAmount": 6026, //for payouts
    "smsFee": 0 //for collections
  },
  "created_at": "2023-07-06T13:35:41.308Z",
  "updated_at": "2023-07-06T13:40:41.308Z",
  "checkout_url": null,
  "error_message": "5200 | Merchant | Invalid account number",
  "telco_response": "Receiver invalid.",
  "virtual_account": null,
  "provider_message": "Failed",
  "reference_business": "d20d4d8df51712345432"
}