Gateway API Usage Guide

This is the documentation page for the M-pesa Payment Gateway API. The API is used to facilitate payments between clients and businesses. The API is built using JSON Web Tokens (JWT) and the OAuth2 library.

The gateway empowers developers to seamlessly integrate Mpesa payments into their applications, utilizing a single Pay Bill number across various platforms.

Before you can interact with our APIs you should first register a new client. The client ID and client secret are used to authenticate the client and generate an access token. The access token is used to authenticate the client when making requests to the API. You can register here >> Register to start making payments

1. Generate Access Token

To authenticate with the Mpesa Payment Gateway API, developers need to obtain an access token by sending a POST request to the following endpoint: https://payment.skilledessays.com/api/v1/auth/generate-access-token

The request should contain the following parameters: grant_type, client_id and client_secret. The client ID and client secret are generated when you register a new client. The client ID and client secret are used to authenticate the client and generate an access token.

Request Body:

                    
{
    "grant_type": "client_credentials",
    "client_id": "137661812332_ce959651b65d833dbc0e.apps.mpesapaymentgateway.com",
    "client_secret": "31cd0c8eddf4d5a2c318a8020b9d432f0263410f"
}

Response Body:

                    
{
    "token_dat": {
        "access_token": "795cce0c1dbba2fafe116cf441965693e962d6a4",
        "expires_in": 3600,
        "token_type": "Bearer",
        "scope": "payment"
    },
    "status_code": 200,
    "error": null,
    "message": "Access token generated successfully"
}

2. Get JWT Token with Client Account Details

To authenticate with the Mpesa Payment Gateway API, developers need to obtain a JWT token by sending a POST request to the following endpoint: https://payment.skilledessays.com/api/v1/users/generate-jwt-token

The request should contain the following parameters: client_secret. The client secret is generated when you register a new client. The client secret is used to authenticate the client and generate a JWT token.

The JWT token will contain encrypted information about the client and the client's account details. The JWT token is used to authenticate the client when making requests to the API. The JWT token is valid for 1 hour.

Request Body:

                    
{
    "client_secret": "31cd0c8eddf4d5a2c318a8020b9d432f0263410f"
}

Response Body:

                    
{
    "status_code": 200,
    "jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
            eyJpc3MiOiJodHRwOi8vbXBlc2EuZ2F0ZXdheS5jb20iLCJhdWQiOiJodHRwOi8vbXBlc2EuZ2F0ZXdheS5vcmciLCJpYXQiOjE3MTIyMjM3MDcsIm5iZiI6MTcxMjIyMzcwNywiZGF0YSI6eyJhcHBfaWQiOiI3Nzg4IiwiYXBwX25hbWUiOiJUZXN0IEFwcCIsInBhcnRuZXJfaWQiOiIyODQ0IiwiY2xpZW50X25hbWUiOiJHZW9yZ2UgT21vbmRpIn0sImV4cCI6MTcxMjIyNzMwN30.
            TSRl-h1ozbqpAnM-hQwgCpp_U62Do8oGT4vdhGgT3ms",
    "message": "JWT Token generated successfully"
}

3. Make Payment

To make a payment with the Mpesa Payment Gateway API, developers need to send a POST request to the following endpoint: https://payment.skilledessays.com/api/v1/payments/make-payment

The request should contain the following parameters: amount, phone_number, and jwt_token. The client ID and access token are generated when you register a new client. The client ID and access token are used to authenticate the client and make a payment.

After the payment has been prosessed, the API will return a response containing the status code, error message, checkout request ID and a message indicating the payment has been initiated successfully. Use the checkout request ID to track the payment status.

Request Body:

                    
{
    "phone": "0725134449",
    "amount": "100",
    "jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
            eyJpc3MiOiJodHRwOi8vbXBlc2EuZ2F0ZXdheS5jb20iLCJhdWQiOiJodHRwOi8vbXBlc2EuZ2F0ZXdheS5vcmciLCJpYXQiOjE3MTIyMTgxNjMsIm5iZiI6MTcxMjIxODE2MywiZGF0YSI6eyJhcHBfaWQiOiI3Nzg4IiwiYXBwX25hbWUiOiJUZXN0IEFwcCIsInBhcnRuZXJfaWQiOiIyODQ0IiwiY2xpZW50X25hbWUiOiJHZW9yZ2UgT21vbmRpIn0sImV4cCI6MTcxMjIyMTc2M30.
            GrlFzrC1wWwsfFgicNqv7cRiSxRQ2hFY15O4k777sYs"
}

Response Body:

                    
{
    "status": 201,
    "error": null,
    "checkoutRequestId": "ws_CO_09062023122721047110506052",
    "message": "Payment initiated successfully"
}

4. Check Payment Status

To check the status of a payment with the Mpesa Payment Gateway API, developers need to send a GET request to the following endpoint: https://payment.skilledessays.com/api/v1/auth/check-payment-status and an access token in the header. The access token is used to authenticate the client and check the payment status.

The request should contain the following parameters: receipt_number. The receipt number is generated when a payment is initiated. The receipt number is used to track the payment status. The developer should provide the receipt number input for users to track their payment status.

Request Body:

                    
{
    "receipt_number": "SAK4J7A5VW"
}

Response Body:

                    
{
    "status": "success",
    "message": "Your payment was successful.",
    "status_code": 200
}
// OR IF PAYMENT HAS BEEN CONFIRMED
{
    "status": "error",
    "message": "Payment has already been confirmed!",
    "status_code": 403
}