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.