Express Deposit Request

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

**DISCLAIMER: Kindly note that this service will send TWO callbacks for Safaricom Requests.

Callback #1 – Final Transaction Status
Callback #1 contains the final status of the Express Deposit request, including the relevant transaction details and parameters from the original request. Integrators MUST rely on this callback to finalize the transaction and complete the checkout flow.

Callback #2 – Reconciliation and Transaction Logging
Callback #2 is intended for reconciliation and transaction logging. It may arrive later or may not be received at all. It is not required to complete the transaction.
Important: Receiving only Callback #1 is expected behavior. Integrators MUST NOT wait for Callback #2 to complete a transaction. Refer to the C2B Callback Overview section for the structure of both callbacks.

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

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

Sample Safaricom C2B Request

{
 "OriginatorConversationId" : "{{$guid}}",   // Mandatory  - Must be unique with each request
 "ShortCode" : "648732",   //Mandatory- Shortcode will be provided by us
 "Amount" : "1",   //Mandatory  
 "PhoneNumber" : "254719000000",   //Mandatory - A valid Safaricom phone number
 "TransactionDesc": "Deposit to wallet",   //  Mandatory - Not more than 30 characters
 "Currency" : "KES",   //  Mandatory
 "AccountNo": "00324-{unique reference not more than 12 characters}" // Mandatory  eg. "00324-XC7UL3JKJNO",   AccountNo will be provided by us 
"type": 0,  // Mandatory   - use 0 for  Safaricom
 "CallBackUrl" : "https://eo2j2658kmohqiy.m.pipedream.net",   // Mandatory
 "mccmnc": "63902",   // Optional-  Safaricom MCCMNC Code if Safaricom request
"successRedirectUrl": "https://guidgenerator.com/",  // Optional
  "failedRedirectUrl": "https://guidgenerator.com/",  //Optional 
  "serviceCode": "ZAMUPAYCOLLECTIONS", //optional
"firstName": "John",  //Optional
    "lastName": "Doe"  //Optional
 }

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'"
    }
  ]
}

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."
      }
  ],
}

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 Safaricom C2B Request#

Sample success response:#

Sample failed response:#

Sample validation errors response:#

Data definition#

Request

Responses

Sample Safaricom C2B Request

Sample success response:

Sample failed response:

Sample validation errors response:

Data definition