The M-Pesa Transaction Status API is a crucial tool for developers and businesses utilizing the M-Pesa platform for transactions. This API enables users to check the status of their transactions, providing real-time insights and ensuring transparency throughout the payment process. In this article, we’ll explore how to use the Transaction Status API, including request and response formats, parameter definitions, and practical use cases.

API Endpoint

To check the status of a transaction, you will use the following endpoint:

URL:

Method: POST
Endpoint: https://sandbox.safaricom.co.ke/mpesa/transactionstatus/v1/query

Request Body

When sending a request to the Transaction Status API, the following JSON structure should be utilized:

  {
    "Initiator": "testapi",
    "SecurityCredential": "Q2wSZCN8HxC5F1HxBBXFt5J+spfkq8VkJFWDJG8oIgGiN6MCh6aXTvuddZZ+/3yApgOXobv6juUdAFNmH2Yf0/tg0irnNn/FXFb4DM4k/DIpdPS19Dh7DCl/DkXymKNID+1edIHWeva+HNH7f1VbHUmGn3XL28BNuH/pykHpJQcc6blXqJAU/L8kP9nwFdZWTn8K7azAbHt4zXNnm7l4fHrLLr/QUtaYOs1MqJK0wS++jMgEg/2QJznSHow3NItKVOXK663lvhSMm5Ei3zzgObrsTHIy2KSciMO+6iUTOm9wvpZrqxB1Zy0WMsku337lAsZ98by/2HHkHv0qV4P4RA==",
    "CommandID": "TransactionStatusQuery",
    "TransactionID": "OEI2AK4Q16",
    "PartyA": 600997,
    "IdentifierType": 1,
    "ResultURL": "https://mydomain.com/TransactionStatus/result/",
    "QueueTimeOutURL": "https://mydomain.com/TransactionStatus/queue/",
    "Remarks": "Okay",
    "Occassion": "Okay"
  }

Request Parameter Definitions

Parameter Name	Description	Type	Sample Values
CommandID	Specifies the command type; must be `TransactionStatusQuery`.	String	TransactionStatusQuery
PartyA	The organization or MSISDN receiving the transaction status query.	Numeric	Shortcode (6-9 digits) or MSISDN
IdentifierType	Indicates the type of organization receiving the transaction; `4` refers to organization shortcode.	Numeric	4
Remarks	Optional comments that accompany the transaction request.	String	A sequence up to 100 characters
Initiator	Username of the initiator for authentication.	Alpha-Numeric	testapiuser
SecurityCredential	Encrypted credential for secure access, allowing M-Pesa to authenticate the request.	String	Your encrypted security credential
QueueTimeoutURL	URL to handle timeout information if the transaction does not complete in time.	URL	https://ip:port/path
TransactionID	Unique identifier for the specific transaction being queried.	Alpha-Numeric	LXXXXXX1234
ResultURL	URL for receiving the status of the transaction after processing.	URL	https://ip:port/path
Occasion	Optional details about the occasion associated with the transaction.	String	A sequence of characters, max 100
OriginatorConversationID	Unique ID for tracking the transaction request, generated upon submission.	String	AG_20190826_00007...

Sample Response Body

Upon successfully querying the transaction status, you will receive a response structured as follows:

{
    "OriginatorConversationID": "1236-7134259-1",
    "ConversationID": "AG_20210709_1234409f86436c583e3f",
    "ResponseCode": "0",
    "ResponseDescription": "Accept the service request successfully."
}

Response Parameter Definitions

Parameter Name	Description	Type	Sample Value
OriginatorConversationID	Unique request ID for tracking the transaction.	Alpha-Numeric	1236-7134259-1
ConversationID	Unique ID assigned by M-Pesa for each transaction request.	Alpha-Numeric	AG_20210709_1234409f86436c583e3f
ResponseCode	Numeric code indicating the processing status of the transaction; `0` means success.	Number	0
ResponseDescription	Description of the transaction status.	String	Accept the service request successfully

Detailed Results Body

The results body contains comprehensive details about the transaction, including its status, amount, and any relevant parameters.

{
   "Result": {
       "ConversationID": "AG_20180223_0000493344ae97d86f75",
       "OriginatorConversationID": "3213-416199-2",
       "ReferenceData": {
           "ReferenceItem": {
               "Key": "Occasion"
           }
       },
       "ResultCode": 0,
       "ResultDesc": "The service request is processed successfully.",
       "ResultParameters": {
           "ResultParameter": [
               {
                   "Key": "DebitPartyName",
                   "Value": "600310 - Safaricom333"
               },
               {
                   "Key": "TransactionStatus",
                   "Value": "Completed"
               },
               {
                   "Key": "Amount",
                   "Value": "300"
               },
               {
                   "Key": "ReceiptNo",
                   "Value": "MBN31H462N"
               }
           ]
       },
       "ResultType": 0,
       "TransactionID": "MBN0000000"
   }
}

Result Parameter Definitions

Parameter Name	Description	Type	Sample Values
ConversationID	Unique identifier generated by M-Pesa for the request.	String	AG_20180223_0000493344ae97d86f75
OriginatorConversationID	Unique identifier for tracking the request message.	String	3213-416199-2
ResultCode	Indicates whether the request was processed successfully (`0`) or not.	String	0
ResultDesc	Description of the result code, providing context on the processing status.	String	The service request is processed successfully.
ResultParameters	Contains specific parameters related to the transaction status, including amounts and reasons.	n/a	n/a
TransactionID	Unique identifier generated for the transaction being queried.	String	MBN0000000

Use Cases

The M-Pesa Transaction Status API can be leveraged in various scenarios, including:

Payment Confirmation: Businesses can use this API to confirm the successful completion of payments made by customers.
Error Handling: In case of failed transactions, developers can identify issues promptly and take corrective actions.
Transaction Auditing: Keeping track of all transactions for auditing purposes ensures compliance and accountability.
User Notifications: By integrating the API with user interfaces, businesses can provide real-time notifications to users regarding their transaction statuses.

Conclusion

The M-Pesa Transaction Status API is an invaluable resource for businesses and developers looking to maintain transparency and reliability in their payment processes. By integrating this API into your systems, you can ensure that you and your customers are always informed about the status of transactions, leading to enhanced trust and satisfaction. For more information, developers can refer to the official M-Pesa Developer documentation for detailed technical guidance and best practices.