Mpesa Stk Push Query Order Status

Merchant Query Order Status

Test URL

GEThttps://uat.finserve.africa/api-checkout/mpesa-stk-push/v3.0/status/order/{orderReference}

Live URL

GEThttps://api.finserve.africa/api-checkout/mpesa-stk-push/v3.0/status/order/{orderReference}

This web service allows merchants to query the real-time status of orders made through the Mpesa STK (Push) service.It allows an application to retrieve the status of an order.

Example Request

⚠️

In the example below, please replace {orderReference} with the actual order reference number.

URL Parameters

Parameter	Description	Format	Required
`orderReference`	The reference number of the order	`string`	Yes

Example Request

curl -X GET \
	-H 'Authorization: Bearer {{token}}' \
	-L 'https://uat.finserve.africa/api-checkout/mpesa-stk-push/v3.0/status/order/OR28922980077'

200 Success Response Schema

Field Name	Type	Description
`status`	boolean	Indicates if the request was successful.
`code`	number	Response code indicating status.
`message`	string	Description of the response status.
`data.order.orderAmount`	double	Request amount.
`data.order.amountPaid`	double	Amount paid by customer including service charge
`data.order.orderReference`	string	Order Reference .
`data.order.orderStatus`	string	This is the status of an order. Paid, Pending
`data.order.createdOn`	number	Creation date of the order in EPOC time
`data.invoices[0].amount`	double	Invoice Amount
`data.invoices[0].amountDebited`	double	Amount paid by the customer
`data.invoices[0].charge`	double	Service charge
`data.invoices[0].invoiceStatus`	string	This can be Pending, Paid, Cancelled or Expired
`data.invoices[0].orderReference`	string	Order Reference
`data.invoices[0].externalReference`	string	Mpesa Reference
`data.invoices[0].createdOn`	string	Date invoice was generated
`data.invoices[0].completedOn`	string	Date Payment was completed

Example Response

Example Sucessful Response

   {
    "status": true,
    "code": "0",
    "message": "Order found",
    "data": {
        "order": {
            "orderAmount": 2.0,
            "amountPaid": 2.0,
            "orderReference": "OR28922980077",
            "orderStatus": "Paid",
            "createdOn": 1723209757300
        },
        "invoices": [
            {
                "amount": 2.0,
                "amountDebited": 2.0,
                "charge": 1.0,
                "invoiceStatus": "Paid",
                "orderReference": "OR28922980077",
                "externalReference": "SH90HU7FO2",
                "createdOn": "2024-08-09 16:22:37.907",
                "completedOn": "2024-08-09 16:22:50.197"
            }
        ]
    }
}

Example Sucessful Response - Pending Order

```json filename="Example Sucessful Response" copy
{
    "status": true,
    "code": "0",
    "message": "Order found",
    "data": {
        "order": {
            "orderAmount": 2.0,
            "amountPaid": 0.0,
            "orderReference": "OR28922980079",
            "orderStatus": "Pending",
            "createdOn": 1723212145140
        },
        "invoices": [
            {
                "amount": 2.0,
                "amountDebited": 2.0,
                "charge": 1.0,
                "invoiceStatus": "Pending",
                "orderReference": "OR28922980079",
                "externalReference": null,
                "createdOn": "2024-08-09 17:02:25.847",
                "completedOn": null
            }
        ]
    }
}


## Error Responses

### 400 Bad Request
Missing or invalid parameters in the request body.

```json
{
  "status": false,
  "code": 400,
  "message": "Invalid request parameters",
  "error_code": "INVALID_REQUEST"
}

401 Unauthorized

Invalid or expired access token.

{
  "status": false,
  "code": 401,
  "message": "Invalid or expired access token",
  "error_code": "UNAUTHORIZED"
}


### 404 Not Found
Account not found or invalid account number.

```json
{
  "status": false,
  "code": 404,
  "message": "Source or destination account not found",
  "error_code": "ACCOUNT_NOT_FOUND"
}

Transaction Status Errors

Response Status	Response Code	Response Message
false	111102	Transaction with the passed reference cannot be found

📖 Step-by-Step Guide

Step 1: 🔑 Set Up Security Keys

Generate your private and public key pair and share your public key with Finserve. See the Security & Signatures Documentation (opens in a new tab) for detailed instructions.

Step 2: 🎫 Authenticate

Obtain an access token using the authentication endpoint. See the Authentication API documentation (opens in a new tab) for details.

Step 3: 📋 Prepare Transaction Details

Gather all required information:

Source account details (country code, name, account number)
Destination account details (country code, name, account number)
Transfer details (amount, currency, reference, date, description)

Sign this string using your private key, then Base64 encode the result.

Step 4: 📝 Set Up Headers

Include the following headers in your request:

Content-Type: application/json
Authorization: Bearer [your_access_token]

Step 5: 🔧 Construct Request Body

Create a JSON object with all required fields following the structure shown in the example request.

Step 6: 🚀 Send POST Request

Make a POST request to the internal bank transfer endpoint with your headers and body.

🌍 Supported Countries & Currencies

Country	Country Code	Common Currency Codes
Kenya	KE	KES
Uganda	UG	UGX
Tanzania	TZ	TZS
Rwanda	RW	RWF
South Sudan	SS	USD
DRC	DRC	USD

Best Practices

** Transaction Reference**
- Use unique reference numbers for each transaction
- Implement a reference generation system to avoid duplicates
- Store reference numbers for reconciliation and audit purposes
- Never reuse reference numbers, even for failed transactions
Data Validation
- Validate all account numbers match the expected format
- Verify country codes are valid and supported
- Ensure transfer dates are in the correct format (YYYY-MM-DD)
- Validate currency codes match the destination country

Support

For questions or issues with this API:

Email: support@finserve.africa

Initiate Request Equitel Stk Ussd Push