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.

{
  "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

Support

For questions or issues with this API:

Email: support@finserve.africa

Account Based Settlement Payment Link as API