Webhook Methods

The webhook methods below enable a partner to register and manage callback URLs that can receive async payments API notifications.

Methods

MethodDescriptionReturn value
subscribeWebhookRegister the partner callback URL to the webhook to start receiving notificationsAcknowledgement of change
getRegisteredWebhookGet list of currently registered webhooks and associated callback URLsList of registered webhooks for the partner
unsubcribeWebhookUnregister the partner callback URL from a webhook, if you no longer want to receive notificationsAcknowledgement of change
updateWebhookMake changes to your webhook, change the callback URL or the partner codeAcknowledgement of change
getByPartnerAndMethodNameList the webhooks registered to the partner for the provided methodList of the partner's webhooks
getAvailableWebhooksList the webhooks that are available to be subscribed toList of webhooks, currently only "transactionStatus"

Request Headers

These headers are common across all the webhook methods

FieldTypeRequest PartMandatoryDescription
timestamp

StringHeaderYesTimestamp (yyyy-mm-dd hh:mm:ss)
authorization StringHeaderYesWeb security: sha256(partnercode+ password + timestamp)

subscribeWebhook

HTTP details

Method: POST
URL: {BASE_URL) /webhook/subscribe
Content Type: application/json

Authorization : Bearer f03c0bdbfe64799e59bc0c1fe0a678c3d8eca4421c28445950f8a1716e3ac24c
timestamp : 2019-11-06 10:52:01
Content-Type : application/json

Request

{
    "partnerCode": "{sample}",
    "reference": "{sample}",
    "callbackUrl": "{URL string}",
    "webhookMethodName": "{sample}"
}

Parameters

FieldTypeReq PartMandatoryDescription
partnerCodeStringBodyYesYour Partner Code as provided by MFS Africa
referenceId StringBodyYesYour platform’s unique reference id for registering the webhook (UUID)
webhookMethodName StringBodyYesValid values: TransactionStatus
callbackUrl StringBodyYesRegistered URL to receive final status

Response

{ 
  "responseCode": "100",
  "responseMsg": "Success",
  "responseData":"

  {
    "partnerCode": "8930518447",
    "reference": "ReconM12",
    "callbackUrl":"{URL string}",
    "webhookMethodName": "TransactionStatus"
  }
}

Parameters

FieldTypeDescription
Code StringResponse code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful
Message StringResponse message
responseData StringResponse object
partnerCode StringPartner code as provided by MFS Africa
referenceId StringUnique reference id for registering webhook (UUID)
webhookMethodName StringWebhook method name
callbackUrl StringRegistered URL to receive final status

getRegisteredWebhook

HTTP details

Method: GET
URL: {BASE_URL) /webhooks/subscribed/{partnerCode}
Content Type: application/json

Authorization : Bearer f03c0bdbfe64799e59bc0c1fe0a678c3d8eca4421c28445950f8a1716e3ac24c
timestamp : 2019-11-06 10:52:01
Content-Type : application/json
{BASE_URL}[/webhook/8930518447](/webhook/8930518447)

Response

{
    “responseCode”: “100”,
    “responseMsg”: “Success”,
    “responseData”: [
        {
            “partnerCode”: “8930518447”,
            “reference”: “ReconP422”,
            “callbackUrl”:”{URL string}”,
            “webhookMethodName”: “TransactionStatus”,
            “dateLogged”: “2019-11-21 15:56:23.0”
        },
        {
            “partnerCode”: “8930518447”,
            “reference”: “ReconP4”,
            “callbackUrl”:”{URL string}”,
            “webhookMethodName”: “transactionStatus”,
            “dateLogged”: “2019-11-21 16:01:26.0”
        },
        {
            “partnerCode”: “8930518447”,
            “reference”: “ReconPP”,
            “callbackUrl”: “{URL string}”,
            "webhookMethodName": "transactionStatus",
            "dateLogged": "2019-11-21 17:21:05.0"
        }
    ]
}

Parameters

FieldTypeDescription
Code StringResponse code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful
Message StringResponse message
responseData StringResponse object
partnerCode StringPartner code as provided by MFS Africa
referenceId StringUnique reference id for registering webhook (UUID)
webhookMethodName StringWebhook method name
callbackUrl StringRegistered URL to receive final status
dateLogged StringDate when registered callback was logged

unsubcribeWebhook

HTTP details

Method: DELETE
URL: {BASE_URL) /webhook/{referenceId}
Content Type: application/json

Authorization : Bearer f03c0bdbfe64799e59bc0c1fe0a678c3d8eca4421c28445950f8a1716e3ac24c
timestamp : 2019-11-06 10:52:01
Content-Type : application/json
{BASE_URL}[/webhook/ReconM12](/webhook/ReconM12)

Response

{
"responseCode": "100",
"responseMsg": "Success"
}

Parameters

FieldTypeDescription
code StringResponse code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful
messageStringResponse message

updateWebhook

HTTP details

Method: POST
URL: {BASE_URL) /webhook/update
Content Type: application/json

Authorization   : Bearer f03c0bdbfe64799e59bc0c1fe0a678c3d8eca4421c28445950f8a1716e3ac24c
timestamp     : 2019-11-06 10:52:01
Content-Type : application/json

Request

{
  "partnerCode": "8930518447",
  "reference": "ReconP422",
  "callbackUrl": "{URL string}",
  "webhookMethodName": "transactionStatus"
}

Parameters

FieldTypeReq PartMandatoryDescription
partnerCode StringBodyYesPartner code as provided by MFS Africa
referenceId StringBodyYesUnique reference id for registering webhook (UUID)
webhookMethodName StringBodyYesWebhook method name
callbackUrl StringBodyYesURL to receive final status

Response

{
"responseCode": "100",
"responseMsg": "Success",
"responseData": {
"partnerCode": "8930518447",
  "reference": "ReconP422",
  "callbackUrl": "{URL string}",
"webhookMethodName": "transactionStatus"
}
}

Parameters

FieldTypeDescription
code StringResponse code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful
message StringResponse message
responseData StringResponse object
partnerCode StringPartner code as provided by MFS Africa
referenceIdStringUnique reference id for registering webhook (UUID)
webhookMethodName StringWebhook method name
callbackUrl StringRegistered URL to receive final status
dateLogged StringDate when registered callback was logged

getByPartnerAndMethodName

HTTP Details

Method: GET
URL: {BASE_URL)/webhook/partnerCode/{partnerCode}/methodName/{methodName}
Content Type: application/json

Authorization : Bearer f03c0bdbfe64799e59bc0c1fe0a678c3d8eca4421c28445950f8a1716e3ac24c
timestamp : 2019-11-06 10:52:01
Content-Type : application/json
{BASE_URL}[/webhook/partnerCode/8930518447/methodName/transactionStatus ](/webhook/partnerCode/8930518447/methodName/transactionStatus)

Response

{
    "responseCode": "100",
    "responseMsg": "Success",
    "responseData": {
        "partnerCode": "8930518447",
        "reference": "ReconPP",
        "callbackUrl":"{URL string}",
        "webhookMethodName": "transactionStatus",
        "dateLogged": "2019-11-21 17:21:05.0"
    }
}

Parameters

FieldTypeDescription
code StringResponse code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful
message StringResponse message
responseData StringResponse object
partnerCode StringPartner code as provided by MFS Africa
referenceId StringUnique reference id for registering webhook (UUID)
webhookMethodName StringWebhook method name
callbackUrl StringRegistered URL to receive final status
dateLogged StringDate when registered callback was logged

getAvailableWebhooks

HTTP Details

Method: GET
URL: {BASE_URL)/webhooks/partnerCode/{partnerCode}
Content Type: application/json

Authorization : Bearer f03c0bdbfe64799e59bc0c1fe0a678c3d8eca4421c28445950f8a1716e3ac24c
timestamp : 2019-11-06 10:52:01
Content-Type : application/json
{BASE_URL}[/webhooks/ available/MFSINT](/webhooks/ available/MFSINT)

Response

{
   "responseCode": "100",
   "responseMsg": "Success",
   "responseData": {
      "webhooks": [
         "TransactionStatus"
      ]
   }
}

Parameters

FieldTypeDescription
code StringResponse code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful
message StringResponse Message
responseData StringResponse Object
webhooks ListList of webhooks