SECURITY

JamboPay Aggregate API is a REST based Web API that facilitates payments in the JamboPay ecosystem. The API is built on modern internet standards to secure communication between interested parties. It relies on OpenID technology for authentication. To ensure a separation of concern, the authentication process is separated from the normal transacting processes. A specific endpoint denotes the location to which authentication happens. Once authenticated the developer is issued with a data payload containing details about the details of the logged in user, assigned roles, an authentication token which gives access to the caller, and properties of the token; like when issued and when it expires.

Developers also need to be issued with an application/ developer key (hereafter referred to as an app key) which identifies the particular application/ client that is making the call and pushing transaction requests. This is a requirement while transacting and not while getting authenticated.

For demo purposes we shall assume a few details;

  1. Default URL for the API is https://services.jambopay.co.ke/JamboPayServices. . Always ask to be provided with a more up to date URL for testing purposes.

  2. All subsequent URLs preceded with the ellipse (e.g. …/api/payments/get) denote the default URL precedes the URL e.g. https://services.jambopay.co.ke/JamboPayServices/api/payments/get.

All requests through the API are and should be in FormUrlEncoded format. Normal request/ response patterns are still maintained with GET requests being embedded on the url whereas the POST and PUT verb requests are processed within the body of the request.

By default, the responses are Json type but one can change the content type by adding a header on the request specifying the desired content type.

There are numerous development tools out there to get you up to speed on interacting with the JamboPay Middleware API. One easy to use tool is POSTMAN, a Chrome browser app.

To access these APIs, you need an access token. To get the access token, you perform an HTTP POST to the URL: https://services.jambopay.co.ke/jambopayservices/token which takes the following parameters:

Parameters

Name Type Required Description
grant_type string R Type of grant be used for login e.g. agency, etc.
Username string R Email address or phone number
Password string R Password

 

Response

On successful login, you receive a response containing the following:

Output Type Description
access_token string access_token acquired during the login process
token_type string Type of token
expire_in string Token expiry date
Username string Username
phoneNumber string Phone Number
Email string Email address
firstName string First Name
middleName string Middle Name
lastName string Last Name

Each subsequent transaction/request must be accompanied by corresponding Authorization and app_key entries in the header.

The Authorization header is a combination of the token_type and access_token parameters received during the authentication phase separated by a space.

See the below for a representation of the data formation:

Parameters

Name Type Required Description
Authorization string R This will contain ‘bearer’++ the access_token received. See header example below:
app_key string R unique key granted to the developer of the application

PHP Header Example: 

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization : bearer '.$token,
'app_key: a2868c59-67e2-e411-885-e657eaebc'));

Note:

The ‘stream’ parameter appears in every process and is mandatory for each subsequent access to the API methods.

Untitled