Webhooks

We use webhooks to provide updates on various events. Events will be sent to the webhook URL provided by the client. To acknowledge a webhook event, the client’s webhook URL should return HTTP status code 200 - OK. In the event that any code other than 200 - OK is returned, the event will be resent a maximum of 10 times, after which the event will no longer be sent.

Update Webhook URL

To update the webhook URL,

1. Click the 'Settings' menu in the Sidebar under the 'Developer' section.
2. Scroll to 'Test Webhook URL' field and click 'Edit'.
3. Fill in the field and click 'Update'.

Note

Webhook for test and live environment need to be updated separately. Every occurrence of Test will be replaced with Live when environment is toggled.

Transfer Status Event

POST {WEBHOOK_URL}

A Transfer Status event will be sent for only when the transfer endpoint returns a ‘PROCESSING’ status in the response.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
Signature	Yes	Header	String	HMAC(SHA-256) of the request body, hashed with the SECRET_KEY and should be encoded in Base64 string format
eventId	Yes	Body	String	ID of the webhook event
eventType	Yes	Body	String	The type of the webhook event
data	Yes	Body	Object	The object containing the reference and status of the transfer
data.requestReference	Yes	Body	String	The unique identifier of the transfer request generated by the client
data.status	Yes	Body	String	The final status of the transfer

Sample Event

{
  "eventId": "ca5c3963-0b4d-4964-a207-94c82dff419c",
  "eventType": "transfer_response",
  "data": {
    "requestReference": "00000007",
    "sessionId": "999999240226070016257381097481",
    "status": "Success"
  }
}

New Transaction Event

POST {WEBHOOK_URL}

Transaction notifications will be sent for every credit and debit transaction that occurs on all of a client’s transient and permanent virtual accounts.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
Signature	Yes	Header	String	HMAC(SHA-256) of the request body, hashed with the SECRET_KEY and should be encoded in Base64 string format
eventId	Yes	Body	String	ID of the webhook event
eventType	Yes	Body	String	The type of the webhook event
data	Yes	Body	Object	The object containing the transaction details
data.id	Yes	Body	String	The unique identifier of the transaction
data.transactionReference	Yes	Body	String	The transaction reference (also serves as the session ID for inflows from other banks)
data.accountNumber	Yes	Body	String	The account on which the transaction occurred
data.accountName	Yes	Body	String	The account name on which the transaction occurred
data.accountRequestReference	Yes	Body	String	The request reference provided during account creation
data.amount	Yes	Body	Numeric	The amount (in Kobo) of the transaction
data.balance	Yes	Body	Numeric	The balance (in Kobo) of the account after the transaction
data.senderName	Yes	Body	String	The name of the sender
data.senderAccountNumber	Yes	Body	String	The account number of the sender
data.senderBank	No	Body	String	The sender bank
data.senderBankCode	No	Body	String	The sender bank code
data.narration	Yes	Body	String	The narration of the transaction
data.transactionType	Yes	Body	String	The type of the transaction - “Debit” or “Credit”
data.transactionDate	Yes	Body	DateTime	Date and time that the transaction occurred

Sample Event

{
  "eventId": "7cb4dc1b-dace-4e1a-95a7-e27cc34c54bf",
  "eventType": "new_transaction",
  "data": {
    "id": "f97996a9-3241-476d-a4e1-2422ac436d4a",
    "transactionReference": "100004240220210739126986960617",
    "accountNumber": "9000002140",
    "accountName": "TOBI ADELAJA 29",
    "accountRequestReference": "00000001"
    "amount": 101000,
    "balance": 9798000,
    "senderName": "Michael Onyirimba",
    "senderAccountNumber": "2000011041",
    "senderBank": "9jaPay",
    "senderBankCode": "090629",
    "narration": "TRF: Michael Onyirimba|test transfer",
    "transactionType": "Credit",
    "transactionDate": "2024-02-20T21:07:39.775Z"
  }
}