Express Deposit Request

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

DISCLAIMER: Kindly note that this service will send two callbacks. ONLY rely on the second callback for the final status of the transaction. DO NOT rely on the first one. Refer to C2B IPN 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 Request

{
    "ShortCode": "174300",
    "Amount": "8",
    "PhoneNumber": "254712365971",
    "TransactionDesc": "Test",
    "OriginatorConversationId": "{{$guid}}",
    "CallBackUrl": "https://bright-sparrow-99.webhook.cool",
    "type": 6,
    "successRedirectUrl": "https://guidgenerator.com/",
    "failedRedirectUrl": "https://guidgenerator.com/",
    "serviceCode": "Almara Pay collections",
    "currency": "KES",
    "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 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 failed callback response:

{
    "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 Request#

Sample success response:#

Sample failed response:#

Data definition#

Sample validation errors response:#

Sample success callback response:#

Sample failed callback response:#

Request