Express Deposit Request

===========================================================================

DISCLAIMER: Kindly note that this service will send TWO callbacks for Safaricom Requests. ONLY rely on the second callback for the final status of the transaction. DO NOT rely on the first one. Refer to Callbacks Overview Section for the structure of the second callback

============================================================================

Note: A valid token is required for authentication as it expires after every hour. Refer to Token Request to generate a new token.

This is a POST request that is responsible for initiating an Express Deposit request.

Sample Safaricom C2B Request

{
 "ShortCode" : "648732", // Shortcode will be provided by us
 "Amount" : "1",
 "TransactionDesc": ""Deposit to wallet",  // Not more than 30 characters
 "Currency" : "KES",
 "PhoneNumber" : "254719000000",  // A valid Safaricom phone number
 "AccountNo": "00860-<your unique id not more than 12 characters>",  //AccountNo will be provided by us  // Append a unique id to the account number to ensure request uniqueness.
"type": 0,  // 0 - Safaricom
 "OriginatorConversationId" : "{{$guid}}", //your unique identifier
 "CallBackUrl" : "https://eo2j2658kmohqiy.m.pipedream.net",
 "mccmnc": "63902",   // Safaricom MCCMNC Code
"successRedirectUrl": "https://guidgenerator.com/",
  "failedRedirectUrl": "https://guidgenerator.com/",
  "serviceCode": "MonexiaCollections",
"firstName": "John",
    "lastName": "Doe"
 }

NOTE: The type, SuccessRedirectUrl, FailedRedirectUrl and ServiceCode fields are mandatory for transactions made to Zambia.

Sample success response:

{
    "message": {
        "appDomainName": "LIVE",
        "remarks": "Express Deposit submission accepted",
        "originatorConversationId": "r279b231rf89238723489733ygge998121",
        "systemConversationId": "16780000-a97d-3024-2e57-08d937173800",
        "timestamp": "2021-06-24T13:51:51.3331004Z"
    }
}

Sample failed response:

{
  "appDomainName": "LIVE",
  "timestamp": "2022-02-11T10:13:11.2483928Z",
  "systemConversationId": "16780000-a97d-3024-98a9-08d9ed471bab",
  "originatorConversationId": "W93323321ei4455t40093334xxiuigggtey",
  "errors": [
    {
      "field": "OriginatorConversationId",
      "message": "duplicate originator conversation id 'W93323321ei4455t40093334xxiuigggtey'"
    }
  ]
}

The required Json body contains :

ShortCode: This is the credit party in the transaction

Amount: This is the amount to be debited

PhoneNumber: This is the debit party in the transaction

AccountNo: This is a nullable field only to be provided if it's a paybill express deposit

TransactionDesc: This is a brief description of the transaction

OriginatorConversationId: This is a unique identifier for the transaction from the client

CallBackUrl: This is your callback url

Type : This is a description of the C2B type

SuccessRedirectUrl : This is the success callback url

FailedRedirectUrl : This is the failed callback url

ServiceCode : This is the code describing the service

Currency : This is the currency of the country

FirstName: This is the first name of the debit party

LastName: This is the last name of the debit party

Data definition

Field Name	Data Type	Max Length
ShortCode	string	7
Amount	decimal	8
PhoneNumber	string	13
TransactionDesc	string	100
OriginatorConversationId	string	100
CallBackUrl	string	256
Type	string	3
SuccessRedirectUrl	string	256
FailedRedirectUrl	string	256
ServiceCode	string	6
Currency	string	6
FirstName	string	128
LastName	string	128

Sample validation errors response:

{
  "appDomainName": "LIVE",
  "status": "BadRequest",
  "timestamp": "2022-02-11T10:13:11.2483928Z",
  "systemConversationId": "16780000-a97d-3024-98a9-08d9ed471bab",
  "originatorConversationId": "W93323321ei4455t40093334xxiuigggtey",
  "errors": [
      {
        "field": "ShortCode",
        "message": "The Shortcode field is required."
      }
  ],
}

Sample success FIRST C2B callback response:

{
    "Body": {
        "StkCallback": {
            "MerchantRequestID": "59675-2838158-2",
            "CheckoutRequestID": "ws_CO_110520211915044651",
            "OriginatorConversationId": "2134568790",
            "SystemConversationId": "456575345435",
            "ResultCode": 0,
            "ResultDesc": "The service request is processed successfully.",
            "CallbackMetadata": {
                "Item": [
                    {
                        "Name": "Amount",
                        "Value": 1
                    },
                    {
                        "Name": "MpesaReceiptNumber",
                        "Value": "PEB0U5YIQ2"
                    },
                    {
                        "Name": "Balance"
                    },
                    {
                        "Name": "TransactionDate",
                        "Value": 20210511191517
                    },
                    {
                        "Name": "PhoneNumber",
                        "Value": 254799182092
                    }
                ]
            }
        }
    }
}

Sample success SECOND /FINAL C2B callback response:

{
    "Id": "51539fcd-0b8e-eb11-826b-062ab3a3eac8",
    "CollectionType": "Mpesa",
    "PrimaryAccountNumber": "9abd2ba6fa3bf4847ba638040947a0945c3a4279effc96d8a6fe0db10ec76ccd",
    "InstitutionIdentifier": "301174",
    "InvoiceNumber": null,
    "Thirdpartyreceiptnumber": "PCQ1490463",
    "PaymentAmount": "1.00",
    "ThirdPartyTransID": null,
    "Payeeaccountnumber": "1",
    "Createddate": "2021-08-06T06:43:31.97",
    "Thirdpartypayload": null,
    "Payeename": "JOHN DOE"
}

Sample failed callback response (For the First C2B Callback):

{
    "Body": {
      "StkCallback": {
        "MerchantRequestID": "14237-1707571-2",
        "CheckoutRequestID": "ws_CO_210520211255325781",
        "ResultCode": "1032",
        "ResultDesc": "Request cancelled by user",
        "OriginatorConversationId": "F1002939292022",
        "SystemConversationId": "7f520000-0e89-0ee0-ea10-08d91c3e9181",
        "CallbackMetadata": null
      }
}

Sample Safaricom C2B Request#

Sample success response:#

Sample failed response:#

Data definition#

Sample validation errors response:#

Sample success FIRST C2B callback response:#

Sample success SECOND /FINAL C2B callback response:#

Sample failed callback response (For the First C2B Callback):#

Request

Responses