Mobile Money Webhooks

SaySwitch sends webhook notifications to your configured endpoint when a payout status changes.

All webhooks are POST requests with a JSON payload. Respond with HTTP 200 to acknowledge receipt.

Notify Types

Notify Type	Trigger
`payout - successful`	Transfer completed and funds delivered to beneficiary
`payout - failed`	Transfer could not be completed

Successful Payout Webhook Payload

{
  "notify": "payout",
  "notifyType": "successful",
  "data": {
    "id": 95596,
    "reference": "a02f886f-ea04-4eba-a286-79e7d8012306",
    "sessionid": "GHJEG4462C800D0304727AD7008D8FDC7629C",
    "currency": "GHS",
    "amount": "10",
    "fee": "1",
    "stamp_duty": "0",
    "bank_code": "MTNGH",
    "bank_name": "MTNGH",
    "account_number": "233245690993",
    "account_name": "JOSHUA AKANYIFE",
    "countryCode": "GH",
    "paymentMode": "momo",
    "narration": "Test transfer",
    "sender": "SAYSWITCH",
    "domain": "live",
    "status": "success",
    "created_at": "2026-05-12T05:19:56.000000Z",
    "updated_at": "2026-05-12T05:20:02.000000Z"
  }
}

Webhook Payload Fields

Field	Type	Description
`notify`	String	Notification category. Always `payout`
`notifyType`	String	`successful` or `failed`
`data.id`	Number	Internal transaction ID
`data.reference`	String	Your unique transaction reference
`data.sessionid`	String	Payment processor session identifier
`data.currency`	String	Transaction currency
`data.amount`	String	Transfer amount
`data.fee`	String	Fee charged for the transaction
`data.bank_code` / `data.bank_name`	String	Destination bank identifiers
`data.account_number`	String	Beneficiary account or phone number
`data.account_name`	String	Verified beneficiary name
`data.paymentMode`	String	`momo` or `bank`
`data.sender`	String	Originator name, `SAYSWITCH`
`data.status`	String	`success` or `failed`
`data.created_at` / `data.updated_at`	String	ISO 8601 timestamps

Handling Webhooks

Return HTTP 200 after receiving the webhook.
Validate notify and notifyType before updating a payout record.
Use data.reference to match the webhook to your original transfer request.
Treat webhook processing as idempotent so duplicate notifications do not create duplicate fulfillment actions.

Payouts / Transfers Error Codes