Callback URL Configuration

OGateway supports separate webhook URLs for successful and failed transactions, giving you granular control over how you handle different transaction outcomes.

How It Works

You can configure two callback URLs:

URL Type	Dashboard Field	API Parameter	Description
Success Callback URL	Successful Transactions Webhook URL	`callbackURL`	Receives callbacks for COMPLETED transactions
Failure Callback URL	Failed Transactions Webhook URL	`failureCallbackURL`	Receives callbacks for FAILED transactions

Setting Callback URLs

There are two ways to configure your callback URLs:

1. Account-Level (Dashboard)

Set default callback URLs for your entire business account via the dashboard:

Successful Transactions Webhook URL: Receives all successful transaction callbacks
Failed Transactions Webhook URL: Receives all failed transaction callbacks

[NOTE] If only the Success Callback URL is set but no Failure Callback URL, failed transaction callbacks will also be sent to the Success Callback URL as a fallback.

2. Per-Request (API)

Override the account-level defaults on a per-transaction basis by passing the URLs in your API request payload:

{
  "amount": 10,
  "reason": "Payment for services",
  "accountName": "Bernard Danso",
  "accountNumber": "0249123456",
  "currency": "GHS",
  "network": "MTN",
  "reference": "unique-ref-123",
  "callbackURL": "https://your-domain.com/webhooks/success",
  "failureCallbackURL": "https://your-domain.com/webhooks/failure"
}

[IMPORTANT] If a callbackURL or failureCallbackURL is passed in the API request, it overrides the corresponding account-level default for that specific transaction.

URL Resolution Priority

The system determines which URL to send the callback to using this priority:

For Successful (COMPLETED) Transactions:

callbackURL passed in the API request payload
Success Callback URL set on the dashboard
No callback sent if neither is set

For Failed Transactions:

failureCallbackURL passed in the API request payload
Failure Callback URL set on the dashboard
Falls back to callbackURL / Success Callback URL
No callback sent if none of the above are set

[TIP] If you don't need to separate your callbacks, simply set only the Success Callback URL — it will be used for both successful and failed transactions.

Quick Reference

Scenario	COMPLETED sent to	FAILED sent to
Only `callbackURL` set	`callbackURL`	`callbackURL`
Both URLs set	`callbackURL`	`failureCallbackURL`
Neither set	No callback	No callback
Per-request override with `failureCallbackURL`	Account default	Per-request `failureCallbackURL`

Updated Fields Table Entry

Parameter	Type	Nullable	Description
`failureCallbackURL`	String	Yes	The URL to receive callbacks for failed transactions. If not set, failed callbacks fall back to `callbackURL`. Can be set per-request or at account level via dashboard.

Sample Payloads

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

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

[NOTE] The callback payloads (what OGateway sends to your URL) remain the same as documented — the only difference is which URL they are sent to.