Webhooks

Generally, webhooks are used to pass information to users triggered by certain events.

At interswitch, we use webhooks to send your application real time notification of event changes. Webhooks are very useful for asynchronous events and it enables you receive realtime changes as they happen on your payments, and you can use this to efficiently track transactions, but you can also use it to build interesting payments initiated directly by the customer.

You can set up webhooks on your Quickteller Business dashboard, under Developer tools. You can enable webhooks for the different event types we have and also configure your webhook URL.

Webhook Events

We currently support the following Event types:

TRANSACTION: Transaction state changes when the customer is paying
SUBSCRIPTION: Subscription payments
PAYMENT LINKS: Payments on a payment link
INVOICES: Invoice Payments

Each Event has a set of actions that explain what type of event has just happened.
e.g TRANSACTION.COMPLETED - means that a transaction has just been completed, it means it has either been successfully paid for, or it has failed and cannot be retried.

TRANSACTION Event Types

Action	Notification Event	Description
CREATED	TRANSACTION.CREATED	A transaction has been created for you (A customer has attempted to make a payment)
UPDATED	TRANSACTION.UPDATED	A transaction previously created for you has been updated(Various stages in the process of payment processing)
COMPLETED	TRANSACTION.COMPLETED	A transaction previously created for you has been completed(Such a transaction may or may not be successful). NOTE: Do note that it is possible to get a completed transaction webhook without previously receiving any of the preceding statuses

SUBSCRIPTION Event Types

Action	Notification Event	Description
Created subscription	SUBSCRIPTION.CREATED	When a customer successfully subscribes to one of your subscription schedule
SUCCESSFUL PAYMENT	SUBSCRIPTION. TRANSACTION_SUCCESSFUL	A successful attempt to charge a subscribed customer
FAILED PAYMENT	SUBSCRIPTION.TRANSACTION_FAILURE	A failed attempt to charge a subscribed customer
Cancelled Subscription	SUBSCRIPTION.CANCELLED	When a customer cancels his subscription to your subscription schedule

PAYMENT LINK Event Types

Action	Notification Event	Description
SUCCESSFUL PAYMENT	LINK.TRANSACTION_SUCCESSFUL	A successful payment link payment by a customer
FAILED PAYMENT	LINK.TRANSACTION_FAILURE	A failed attempt of payment for payment link by a customer

INVOICE Event Types

Action	Notification Event	Description
SUCCESSFUL PAYMENT	INVOICE.TRANSACTION_SUCCESSFUL	A successful payment by a customer
FAILED PAYMENT	INVOICE.TRANSACTION_FAILURE	A failed attempt of payment by a customer

Sample Message
All webhook messages you receive from us will follow this general format

{
 "event": "TRANSACTION.COMPLETED",
 "uuid": "2Xdf35faAyX2Sk5Dalu405rUD",
 "timestamp": 1594646111460,
 "data": {
 "remittanceAmount": 0,
 "bankCode": "011",
 "amount": 12000,
 "paymentReference": "FBN|WEB|MX6072|13-07-2020|3481032|762672",
 "channel": "WEB",
 "splitAccounts": [],
 "retrievalReferenceNumber": "000106923853",
 "transactionDate": 1594646111460,
 "accountNumber": null,
 "responseCode": "00",
 "token": null,
 "responseDescription": "Approved by Financial Institution",
 "paymentId": 3481032,
 "merchantCustomerId": "[email protected]",
 "escrow": false,
 "merchantReference": "2Xdf35faAyX2Sk5Dalu405rUD",
 "currencyCode": "566",
 "merchantCustomerName": "yee tod",
 "cardNumber": "561233*********0865"
 }
}

Field Descriptions

Field	Description
uuid	Unique id for the Event(transaction reference, invoice reference, etc)
timestamp	Time event action occurred
event	Event that occurred that triggered the notification
data	Actual object that is relevant (Payment Object)

Sending Back Response

You are expected to send back a 200 HTTP response to every message received. This is to confirm that you received the message. If you return any HTTP response code other than 200, it is assumed that you did not receive any message and a retry is made up to a total of 5 times.

Do not bother sending any response body with the response code. Any response body you send with the HTTP 200 will be discarded.

Also, once you receive a message, respond with a 200 immediately, before starting any other long process. This is because if it takes time for your application to respond, a retry is made. This can lead to you having duplicate data.

Message Security

All web hook messages we send to you are hashed with HmacSHA512 Algorithm. The hash is generated using the entire object received in the current
notification
The secret key used to hash the message is the unique one generated for you in the configuration.
The generated hash is Hex encoded, then passed in the header with the parameter field X-Interswitch-Signature.
This enables you to verify any message you receive on your configured url is genuinely from us.
To verify every message, you will need to do the following.
You will generate another hash using the same algorithm we use (Hmacsha512), your secret key and the raw Json object received as a string.
Compare the hash generated. ensure its the same as the one passed in the X-Interswitch-Signature header.

I.e

If the request body we send to you is

{"event": "TRANSACTION.UPDATED", "uuid": "2Xdf35faAyX2Sk5Dalu405rUD", "timestamp":1594646111460,"data":{ "bankCode":"011"}}

The hash is going to be hex encoded with your secret key
HmacSHA512 ( {"event": "TRANSACTION.UPDATED", "uuid": "2Xdf35faAyX2Sk5Dalu405rUD", "timestamp":1594646111460,"data":{ "bankCode":"011"}} )

If the hash you generate does not match the hash you receive in the X-Interswitch-Signature header, the request was not from us.

Any request that you receive without the X-Interswitch-Signature is also not from us.