NAV Navbar
Request and Response
  • TujengePay Monetize API Version 1
  • How TujengePay Monetize API works
  • Get Started with the API
  • API Authentication
  • OAuth 2.0 Authentication
  • TujengePay Monetize API
  • Testing on localhost
  • TujengePay Monetize API Version 1

    This documentation describes an mpesa payments API exposed by the TujengePay platform intended to be used by other developers building their own applications.

    This documentation aims to assist any developer to integrate mpesa payments to their third party application (web app or mobile app).

    The TujengePay Monetize API is designed to allow you to start receiving mpesa payments in your apps in the shortest possible time, whether you are testing your app or in production.

    TujengePay provides ready to use Mpesa Paybills for receiving payments via mpesa.

    TujengePay Monetize API Pricing

    How TujengePay Monetize API works

    Get Started with the API

    TujengePay requires a user to first create an account on the TujengePay platform in order to start using the TujengePay API. If you don't have a TujengePay account, you can create one here

    Once you have created your account and confirmed your email, you can proceed to log in to your TujengePay account where you can see the API link.

    API Authentication

    TujengePay API uses OAuth 2.0 to authenticate third parties.

    TujengePay generates a client id and a secret that can be used to authenticate your application uisng OAuth 2.0. client_credentials scheme that generates an access token to be used in authenticating subsequent payment requests.

    You can find your TujengePay Client Id and Secret here

    OAuth 2.0 Authentication

    TujengePay API uses OAuth 2.0 access tokens to to authenticate third party applications.

    Getting an access token

    To get an access token make the HTTP request below:

    POST https://api.tujengepay.com/oauth/token

    Content-type : application/json

     {
        "grant_type" : "client_credentials",
        "client_id" : "your_client_id",
        "client_secret" : "your_client_secret"
     }
    

    Response

     {
        "token_type": "Bearer",
        "expires_in": 31536000,
        "access_token": "access_token"
     }
    

    Url

    POST https://api.tujengepay.com/oauth/token

    Headers

    Key Value
    Accept application/json

    Query parameters

    Parameter Type Default
    grant_type string,required client_credentials
    client_id string,required
    client_secret string,required

    Using the access token

    With the access token acquired, an application can invoke TujengePay API endpoints by including the access token in the request header as shown below

    Authorization : Bearer your_access_token

    TujengePay Monetize API

    POST https://api.tujengepay.com/api/v1/quick/payments

    Content-type : application/json

    Authorization : Bearer your_access_token

     {
        "organizationId" : "38354510-d9ac-11e7-93ed-791b05fc25ae",
        "externalIdentifier" : "1",
        "phoneNumber"    : "07xxxxxxxx",
        "amount"         : "2500",
        "callBackUrl"    : "https://testing.com/api/test"
     }
    

    Response

     {
       "message": "Payment is being processed",
       "paymentId": "a8b1d160-db49-11e7-af59-4306a6d9dfe8",
       "accountNumber": "J4690",
       "paybill": "489753"
     }
    

    Call back URL response

      {
         "paymentId" : "a8b1d160-db49-11e7-af59-4306a6d9dfe8",
         "externalIdentifier" : "1231",
         "accountNumber" : "N5319",
         "resourceIdentifier" : "N5319",
         "transactedAmount" : 100.00,
         "transactionCost" : 1.00,
         "actualAmount" : 99.00,
         "status" : "sucess", // or "failed",
         "receiptNumber" : "RTGNS12S",
         "transactionDate"    : 2017-07-27 15:48:00,
         "phoneNumber"        : 254721566839
      }
    

    To initiate a payment, make the following HTTP request

    Url

    POST https://api.tujengepay.com/api/v1/quick/payments

    Headers

    Key Value
    Accept application/json
    Authorization Bearer your_access_token

    Query parameters

    To obtain an organizationId, open your organization's dashboard, then click the API Payments tab at the top navigation bar, there you will see the organizationId for the organization your are viewing. Click copy to copy.

    The externalIdentifier is a string you generate in your application to identify your transaction and is returned back with other data to your callback url when the payment is completed.

    Parameter Type Default
    organizationId string,required
    externalIdentifier string,required
    phoneNumber string,required
    amount string,required
    callBackUrl string,required

    Testing on localhost

    Tujenge APIs are asynchronous, responses to requests are sent back to the client that initiated the request.

    To receive responses on your callback urls, the clients should have HTTP post listeners. This is achieved by deploying an HTTP listener on a publicly accessible server.

    To test on localhost http tunneling clients like Ngrok and LocalTunnel can be used to get a public IP and make your localhost accessible over the internet.

    Run in Postman