Error Handling

Callback Codes

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

Format:

{
	//...
  "message": "Code | Fault | Message",
	//...
}

Sample output:

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

Code	Fault	Message
0000	Switch	Approved
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

Faults

There are 5 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 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.

Sample Callback Payloads

{
  "id": "579eea58-49be-485c-59de-d9881d24c4gd",
  "fee": 10,
  "type": "CREDIT",
  "amount": 133,
  "reason": "CREDIT_MOMO",
  "status": "COMPLETED",
  "channel": "MOMO",
  "network": "MTN",
  "bear_fee": "business",
  "currency": "GHS",
  "customer": {
    "accountName": "Bernard Danso",
    "accountNumber": "0249123456"
  },
  "metadata": {
    "transactionAmount": 133, //for payouts
    "smsFee": 0 //for collections
  },
  "created_at": "2023-07-06T13:35:41.308Z",
  "updated_at": "2023-07-06T13:35:41.308Z",
  "checkout_url": null,
  "message": "0000 | Switch | Approved",
  "telco_response": "APPROVED",
  "virtual_account": null,
  "provider_message": "Success",
  "reference_business": "d20d4d8df51712345432"
}

//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",
  "fee": "0",
  "type": "DEBIT",
  "amount": "22",
  "reason": "Payment for services",
  "status": "FAILED",
  "channel": "MOMO",
  "network": "MTN",
  "bear_fee": "business",
  "currency": "GHS",
  "customer": {
    "accountName": "Bernard Danso",
    "accountNumber": "0249123456"
  },
  "metadata": {
    "transactionAmount": 22, //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
  "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"
}

// 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,
  "message": "5200 | Merchant | Invalid account number",
  "telco_response": "Receiver invalid",
  "virtual_account": null,
  "provider_message": "Failed",
  "reference_business": "d20d4d8df51712345432"
}

Callback Payload Field Definition

Parameter	Type	Description
id	String	Unique system identifier for the transaction record.
fee	String	The processing fee charged for the transaction.
type	String	The direction of the transaction (e.g., DEBIT, CREDIT).
amount	String	The total amount of the transaction.
reason	String	The description or purpose of the payment.
status	String	Current state of the transaction (e.g., FAILED, COMPLETED, PENDING).
channel	String	The payment channel utilized (e.g., MOMO).
network	String	The specific telecommunications network/provider (e.g., MTN, VOD).
bear_fee	String	Indicates who bears the cost of the transaction fee (e.g., business or customer).
currency	String	The 3-letter ISO currency code (e.g., GHS).
customer	Object	An object containing the customer's account details.
customer.accountName	String	The registered name of the customer's mobile money account.
customer.accountNumber	String	The mobile number or account identifier of the customer.
metadata	Object	A key-value object containing additional context or custom data.
metadata.transactionAmount	Number	The specific transaction amount, typically provided for payouts.
metadata.smsFee	Number	The SMS fee applied, typically provided for collections.
created_at	String	ISO 8601 timestamp indicating when the transaction was initiated.
updated_at	String	ISO 8601 timestamp indicating when the transaction status was last updated.
checkout_url	String/Null	A link to the hosted checkout page, if applicable.
instructions	String	Helpful instructions (like USSD codes) to display to the user if the automatic push prompt fails.
message	String	A code, fault and message explaining the final status of the transaction (e.g., failure reasons).
telco_response	String	The raw system response message received directly from the network provider.
virtual_account	String/Null	The virtual account number, if a bank transfer method was used.
provider_message	String	A simplified status message directly from the payment provider.
reference_business	String	The unique internal reference generated by your business system for tracking.