Webhook Methods

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

Methods

Method

Description

Return value

subscribeWebhook

Register the partner callback URL to the webhook to start receiving notifications

Acknowledgement of change

getRegisteredWebhook

Get list of currently registered webhooks and associated callback URLs

List of registered webhooks for the partner

unsubcribeWebhook

Unregister the partner callback URL from a webhook, if you no longer want to receive notifications

Acknowledgement of change

updateWebhook

Make changes to your webhook, change the callback URL or the partner code

Acknowledgement of change

getByPartnerAndMethodName

List the webhooks registered to the partner for the provided method

List of the partner's webhooks

getAvailableWebhooks

List the webhooks that are available to be subscribed to

List of webhooks, currently only "transactionStatus"

Request Headers

These headers are common across all the webhook methods

Field

Type

Request Part

Mandatory

Description

timestamp

String

Header

Yes

Timestamp (yyyy-mm-dd hh:mm:ss)

authorization

String

Header

Yes

Web 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

Field

Type

Req Part

Mandatory

Description

partnerCode

String

Body

Yes

Your Partner Code as provided by MFS Africa

referenceId

String

Body

Yes

Your platform’s unique reference id for registering the webhook (UUID)

webhookMethodName

String

Body

Yes

Valid values: TransactionStatus

callbackUrl

String

Body

Yes

Registered URL to receive final status

Response

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

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

Parameters

Field

Type

Description

Code

String

Response code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful

Message

String

Response message

responseData

String

Response object

partnerCode

String

Partner code as provided by MFS Africa

referenceId

String

Unique reference id for registering webhook (UUID)

webhookMethodName

String

Webhook method name

callbackUrl

String

Registered 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

Field

Type

Description

Code

String

Response code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful

Message

String

Response message

responseData

String

Response object

partnerCode

String

Partner code as provided by MFS Africa

referenceId

String

Unique reference id for registering webhook (UUID)

webhookMethodName

String

Webhook method name

callbackUrl

String

Registered URL to receive final status

dateLogged

String

Date 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

Field

Type

Description

code

String

Response code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful

message

String

Response 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

Field

Type

Req Part

Mandatory

Description

partnerCode

String

Body

Yes

Partner code as provided by MFS Africa

referenceId

String

Body

Yes

Unique reference id for registering webhook (UUID)

webhookMethodName

String

Body

Yes

Webhook method name

callbackUrl

String

Body

Yes

URL to receive final status

Response

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

Parameters

Field

Type

Description

code

String

Response code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful

message

String

Response message

responseData

String

Response object

partnerCode

String

Partner code as provided by MFS Africa

referenceId

String

Unique reference id for registering webhook (UUID)

webhookMethodName

String

Webhook method name

callbackUrl

String

Registered URL to receive final status

dateLogged

String

Date 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

Field

Type

Description

code

String

Response code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful

message

String

Response message

responseData

String

Response object

partnerCode

String

Partner code as provided by MFS Africa

referenceId

String

Unique reference id for registering webhook (UUID)

webhookMethodName

String

Webhook method name

callbackUrl

String

Registered URL to receive final status

dateLogged

String

Date 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

Field

Type

Description

code

String

Response code
100 - Success - Instruction successful
101 - Pending - Instruction unsuccessful

message

String

Response Message

responseData

String

Response Object

webhooks

List

List of webhooks