Callbacks

Callback Handling Flow

The flow to handle callbacks from our system to your callbackURL is as follows:

Confirm source authenticity via webhook header security: Confirm that you are receiving webhooks from us. Implement the Webhook Security to validate the authenticity of our callbacks to you.
Confirm source authenticity by whitelisting OGateway IP addresses: Implement IP Whitelisting on your firewall and allow traffic between your systems and OGateway only through the whitelisted IP addresses.
Understand the final status of the transaction: The final status of the transaction is found in the status field. The status is either:
1. COMPLETED: That means the transaction was successfully processed or
2. FAILED: That means the transaction failed to process successfully.
Know the reason for the failure: If the transaction FAILED, identify the cause of the failure via Error Handling and propagate the error / failure to your client.

Fields

These are the fields to expect in the callback payloads to your callbackURL

Parameter	Type	Nullable	Description
id	String	No	Unique system identifier for the transaction.
amount	String	No	The face value of the transaction.
fee	String	No	The processing fee charged (0 in this case, as the business bears the cost).
currency	String	No	3-letter currency code (e.g., GHS).
status	String	No	Current state of the transaction (e.g., FAILED, PENDING).
channel	String	No	The platform used for the payment (e.g., MOMO).
type	String	No	The transaction category (e.g., DEBIT).
reason	String	Yes	The purpose of the payment provided during initiation.
network	String	No	The Mobile Money provider (e.g., MTN, VODAFONE).
bear_fee	String	Yes	Indicates who pays the transaction fee (e.g., business or customer).
customer	Object	No	Container for the customer's account details.
customer.accountName	String	No	The name of the mobile money account holder.
customer.accountNumber	String	No	The MSISDN/Phone number of the customer.
metadata	Object	Yes	Custom fields; defaults to transactionAmount (payouts) or smsFee (collections).
created_at	String	No	ISO 8601 timestamp of initiation.
updated_at	String	No	ISO 8601 timestamp of the final status update.
checkout_url	String/Null	Yes	A URL for the hosted checkout page if applicable.
instructions	String	Yes	USSD instructions to show the user if the STK push fails.
error_message	String	No (if transaction status is FAILED)	Detailed error code and human-readable reason for failure.
telco_response	String	Yes	The raw response message from the network provider.
virtual_account	String/Null	Yes	The virtual account number if a bank transfer was used.
provider_message	String	Yes	A simplified status message from the provider.
reference_business	String	No	The unique reference generated by your business system.

Sample Payloads

These are the payloads to expect on your callbackURL for both Successful and Failed transaction.

Request Payload Examples

These are examples of the API request payloads showing the callbackURL parameters:

Collections Request

{
  "amount": 22,
  "reason": "Payment for services",
  "accountName": "Bernard Danso",
  "accountNumber": "0249123456",
  "currency": "GHS",
  "network": "MTN",
  "reference": "d20d4d8df15712345432",
  "callbackURL": "https://your-domain.com/webhooks/success"
}

Payouts Request

{
  "recipients": [
    {
      "amount": 22,
      "network": "MTN",
      "accountName": "Bernard Danso",
      "accountNumber": "0249123456",
      "currency": "GHS"
    }
  ],
  "reference": "d20d4d8df15712345432",
  "callbackURL": "https://your-domain.com/webhooks/success"
}

Note: The callback payloads (what OGateway sends to your URL) remain the same regardless of which URL they are sent to — the only difference is which URL receives them based on the transaction status.

Callback Payload Examples

{
  "id": "5ba941b5-eb5c-4618-b8ec-4d1419fb1111",
  "amount": "22",
  "fee": "0.22",
  "currency": "GHS",
  "status": "COMPLETED",
  "channel": "MOMO",
  "type": "DEBIT",
  "reason": "Payment for services",
  "network": "MTN",
  "bear_fee": "business",
  "customer": {
    "accountName": "Bernard Danso",
    "accountNumber": "0249123456"
  },
  "metadata": {
    "transactionAmount": 132,
    "smsFee": 0
  },
  "created_at": "2023-07-06T13:35:41.308Z",
  "updated_at": "2023-07-06T13:35:46.308Z",
  "checkout_url": null,
  "error_message": null,
  "telco_response": "APPROVED",
  "virtual_account": null,
  "provider_message": "Success",
  "reference_business": "d20d4d8df15712345432"
}

{
  "id": "5ba941b5-eb5c-4618-b8ec-4d1419fb1111",
  "amount": "22",
  "fee": "0.22",
  "currency": "GHS",
  "status": "COMPLETED",
  "channel": "MOMO",
  "type": "CREDIT",
  "reason": "Payment for services",
  "network": "MTN",
  "bear_fee": "business",
  "customer": {
    "accountName": "Bernard Danso",
    "accountNumber": "0249123456"
  },
  "metadata": {
    "transactionAmount": 132,
    "smsFee": 0
  },
  "created_at": "2023-07-06T13:35:41.308Z",
  "updated_at": "2023-07-06T13:35:46.308Z",
  "checkout_url": null,
  "error_message": null,
  "telco_response": "APPROVED",
  "virtual_account": null,
  "provider_message": "Success",
  "reference_business": "d20d4d8df15712345432"
}

{
  "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,
    "smsFee": 0
  },
  "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.",
  "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"
}