Back to home
INTEGRATION
PAYMENT FEATURES
AFTER PAYMENT
Receiving Settlements
Anytime an event happens on your account, your application can be notified by SeerBit. This is where webhooks come in, it is useful for events that are not triggered by direct API request, but when the response from that request needs to be known (for instance, in cases when there is an update to a transaction status), it is necessary only for behind-the-scenes transactions. SeerBit webhooks are HTTP calls that are triggered by specific events. SeerBit webhooks replace regular API calls with instant, real-time notifications. It can be set up on your dashboard by specifying a URL we would send POST requests to you whenever an event that might be of interest happens. Each webhook notification contains an eventType that specifies which type of event triggered the webhook notification.
Failed Transactions
Expose an endpoint on an open server
We can send notifications as HTTP callbacks (webhooks) to an endpoint on a server that must be open. To receive webhooks, you must have a server that:
- Has an endpoint that can receive JSON requests
- Depending on your network and security requirements, you might also need to add our IP address to your firewall whitelist
Subscribe to webhook notifications
To configure webhooks notifications:
- Login to your dashboard
- Navigate to Account Settings > Webhook
- Enter your notification URL
- Click on Subscribe
Accept Nofications
To ensure that your server is properly accepting notifications, we require you to acknowledge every notification with an HTTP 200 response code. If we don't receive this response within 10 seconds, for example because your server is down, all notifications to your endpoint will be queued and retried. For more information, refer to queued notifications. When your server receives notification:
- Save the notification in your database
- Acknowledge the notification with the following HTTP response status code 200
- Apply your business logic
Make sure that you acknowledge the notification before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system.
Webhook Integration
A seerbit integration includes the following :
- Events: This is an action that triggers notifications. Webhooks can be used to create alerts that trigger for these events.
- Subscriptions: This is set-up in the portal to subscribe to notifications associated with a specific event. There is a configurable service in the application to which alerts are sent.
- Notification Body: Details about the event that generated the alert, such as the time it happened.
Webhook Event Types
refund
dispute
transaction
transaction.recurrent
transaction.wallet
transaction.recurring.debit
dispute
transaction
transaction.recurrent
transaction.wallet
transaction.recurring.debit
Queued Notifications
It is expected that you respond to an event notification with a status response code of 200 (OK). This code will be used by us to acknowledge that you received the notification. Any status response code outside of the 2xx series will be considered a failed response and we will continue to retry regularly for up to 7 days, at increasing time intervals as follows:
2 Minutes
5 Minutes
10 Minutes
15 Minutes
30 Minutes
1 hour
2 hours
4 hours
5 Minutes
10 Minutes
15 Minutes
30 Minutes
1 hour
2 hours
4 hours
After that, retries happen every 8 hours for the following 7 days. If we do not receive a response within the 2XX series, all notifications to this endpoint will be queued. Subsequently, we will attempt to retry sending the notification to your endpoint until it is accepted. Once accepted, you will receive all queued notifications as well.
Refund Event Sample
The refund event notification body is structured thus:
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "refund",
6 "eventDate": "2020-05-01 12:55:57",
7 "eventId": "0be677f841254a3eb92fab0d0b6ba232",
8 "data": {
9 "amount": "10",
10 "createdAt": "2019-10-24 07:47:49",
11 "transactionRef": "IHrE1571828556059",
12 "description": "I need my money",
13 "type": "FULL_REFUND",
14 "mode": "TEST",
15 "updatedAt": "2019-10-24 07:47:49"
16 }
17 }
18 }
19 ]
20 }Dispute Event Sample
The dispute event notification body is structured thus:
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "dispute",
6 "eventDate": "2020-05-01 12:56:07",
7 "eventId": "da28df9ea5dd4807b59e5761afd7231b",
8 "data": {
9 "evidence": [
10 {
11 "images": [
12 {
13 "image": ""
14 }
15 ],
16 }
17 ]
18 },
19 }
20 }
21 ]
22 }Transaction Event
The transaction event notification body is structured thus
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "transaction",
6 "eventDate": "2024-07-01 08:56:16",
7 "eventId": "e1c98e0ba9364843b7fa8bd8df0e3bc1",
8 "data": {
9 "amount": 922.63,
10 "mobile": "404",
11 "reference": "SBT-T19824129237",
12 "gatewayMessage": "Successful",
13 "publicKey": "SBTESTPUBK_vtI76q2HWA7QHPbqC1M88HC89gllHKfE",
14 "businessName": "opeyemi test",
15 "fee": "13.63",
16 "productId": "",
17 "channelType": "MASTERCARD",
18 "maskedPan": "5123-45xx-xxxx-0008",
19 "sourceIP": "154.113.161.130",
20 "deviceType": "Desktop",
21 "fullname": "ope seun",
22 "email": "seunopeyemi16@gmail.com",
23 "gatewayReference": "SEERLFN8WWTSILB7ZG7",
24 "country": "NG",
25 "currency": "NGN",
26 "narration": "",
27 "createdAt": "2024-07-01T08:56:07",
28 "updatedAt": "2024-07-01T08:56:13.574",
29 "lastFourDigits": "0008",
30 "cardBin": "512345",
31 "reason": "Successful",
32 "paymentType": "CARD",
33 "gatewayCode": "00",
34 "code": "00"
35 }
36 }
37 }
38 ]
39}Wallet Transaction Event
The wallet transaction event notification body is structured thus
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "transaction.wallet",
6 "eventDate": "2020-05-01 12:52:28",
7 "eventId": "c472deceabf44924901b104523af14df",
8 "data": {
9 "amount": "100.00",
10 "mobile": "08033456500",
11 "reference": "shh3332hwhwhh22hjjjwj",
12 "gatewayMessage": "APPROVED",
13 "publicKey": "hhw33y2x",
14 "bankCode": "000016",
15 "description": "wallet transaction",
16 "fee": "2.00",
17 "type": "Transfer",
18 "fullname": "John Doe",
19 "email": "peter.diei@centricgateway.com",
20 "country": "NG",
21 "currency": "NGN",
22 "origin": "string",
23 "internalRef": "string",
24 "creditAccountName": "Test Account",
25 "creditAccountNumber": "23221122321",
26 "originatorAccountnumber": "1929383828392",
27 "originatorName": "CGW",
28 "narration": "my narration here",
29 "sessionId": "00002999299388837772828883778",
30 "externalReference": "2203000002992910219",
31 "createdAt": "2019-12-12 16:20:59",
32 "updatedAt": "2019-12-12 16:20:59"
33 }
34 }
35 }
36 ]
37 }Recurrent Transaction Event
The recurrent transaction event notification body is structured thus
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "transaction.recurrent",
6 "eventDate": "2020-05-01 12:50:33",
7 "eventId": "30a33df05b0c465c8c38f4113621685a",
8 "data": {
9 "amount": "150",
10 "mobile": "08033456500",
11 "reference": "TESTPilotR251218123PPOIU149",
12 "publicKey": "SBTESTPUBK_dhrpzbRpR34l6VmqkCFOKA94L5E1jSTu",
13 "description": "Pilot Test Subscription",
14 "productId": "Terrain",
15 "maskedPan": "5123-45xx-xxxx-0008",
16 "email": "akintoyekolawole@gmail.com",
17 "gatewayReference": "F325090871582705056234",
18 "country": "NG",
19 "narration": "Reccurrent",
20 "createdAt": "2020-02-26T09:17:30",
21 "updatedAt": "2020-02-26T09:18:26.496",
22 "lastFourDigits": "0008",
23 "cardBin": "512345"
24 }
25 }
26 }
27 ]
28 }Recurring Debit Transaction
The code snippet below shows an example response for verifying a subscription
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "transaction.recurring.debit",
6 "eventDate": "2020-05-01 12:55:32",
7 "eventId": "799f8cad23bc4bc389280f996d81ea55",
8 "data": {
9 "amount": "2000",
10 "reference": "PILOT76558370651618723659",
11 "gatewayMessage": "Successful",
12 "publicKey": "SBTESTPUBK_dhrpzbRpR34l6VmqkCFOKA94L5E1jSTu",
13 "description": "Authorised charge",
14 "channelType": "Recurring Debit",
15 "maskedPan": "5123--4xx-xxxx-xx-0",
16 "type": "TOKEN",
17 "fullname": "Frank Gboyega",
18 "email": "gboyega@fcmb.com",
19 "gatewayReference": "F786046901582644089560",
20 "country": "NG",
21 "currency": "NGN",
22 "narration": "Authorised charge",
23 "createdAt": "2020-02-25T16:21:23",
24 "updatedAt": "2020-02-25T16:21:31.319",
25 "paymentType": "card"
26 }
27 }
28 }
29 ]
30}Virtual Account Transaction
The virtual account transaction event notification body is structured thus
1{
2 "notificationItems": [
3 {
4 "notificationRequestItem": {
5 "eventType": "transaction",
6 "eventDate": "2023-10-06 12:56:47",
7 "eventId": "88bf9852405143bd99502c378b316fdd",
8 "data": {
9 "amount": 100,
10 "country": "NG",
11 "creditAccountName": "BusinessName(Customer Name)",
12 "creditAccountNumber": "4018013418",
13 "currency": "NGN",
14 "email": "xyx@email.com",
15 "externalReference": "GT-012",
16 "fullname": "Adamu Bola Ciroma",
17 "gatewayCode": "00",
18 "code": "00",
19 "internalRef": "",
20 "gatewayMessage": "Successful",
21 "mobile": "404",
22 "narration": "",
23 "origin": "",
24 "originatorAccountnumber": "<Account Number>",
25 "originatorName": "<Account Name>",
26 "publicKey": "<PublicKey>",
27 "reference": "GT-012_SBT_9ADPCIV269",
28 "reason": "Successful"
29 }
30 }
31 }
32 ]
33}Need something else?
If you have any questions or need general help, visit our support page
Signup for developer update
You can unsubscribe at any time. Read our privacy policy.