DEV Community

Sospeter Mong'are
Sospeter Mong'are

Posted on

M-Pesa Transaction Status API

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.

Transaction Status API response


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"
  }
Enter fullscreen mode Exit fullscreen mode

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."
}
Enter fullscreen mode Exit fullscreen mode

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"
   }
}
Enter fullscreen mode Exit fullscreen mode

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:

  1. Payment Confirmation: Businesses can use this API to confirm the successful completion of payments made by customers.
  2. Error Handling: In case of failed transactions, developers can identify issues promptly and take corrective actions.
  3. Transaction Auditing: Keeping track of all transactions for auditing purposes ensures compliance and accountability.
  4. 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.

Top comments (0)