Nunua Sasa Checkout APIs Reference

Version 1.1.0


Nunua Sasa offers you a flexible payment option for your goods and services. With Nunua Sasa you can now pay in installments.

Here, we will go over the necessary details required to plug in your platform to Nunua Sasa and avail all the services required for this payment option to work.

Concept Overview

We have developed REST APIs that are accessible from any system and in any language provided the requirements are met as per each API call.

To secure our endpoints, access to our APIs is broken down into two main parts :

Part 1 - Once registered with us, you will receive your own Admin Account on Nunua Sasa. This account will be the starting point for all subsequent API calls to be made.

This account acts as the key link to all products in Nunua Sasa as well as allow us to identify the products from each platform they are sourced from. It also allows you as the account admin holder to better manage all your customers paying through us.

With this account, you also gain access to a personalized dashboard on Nunua Sasa where you can monitor all products, payment details as well as payment tracking information for all your customers.

Unless you wish to have multiple admin accounts under the same company, this part will only be done once, at the very beginning of your integration with Nunua Sasa.

Part 2 - On your admin account dashboard, you will be required to register a client. Once registered you will be availed a Client ID and Client Secret that are unchangeable. These two parameters will be used to authenticate and verify you as an authorized user of our APIs.

Once successfully verified, you will receive a token that will be placed in your Authorization Header for all subsequent API calls. Getting this API token will require the Client ID and Secret combination that was generated. More on how to get the token is explained here

You can have multiple clients under your admin account but each client will be tied to its own products.

In this case client refers to a developed system such as a mobile or web application communicating with Nunua Sasa. Customer refers to the individual making the purchase from your platform.

How to Start

Once you have contacted us via and been approved we will set you up with an admin account. Follow the steps below to set-up your configuration before calling any APIs.

Admin Login

Access the Nunua Sasa Login page and using the credentials you received proceed to login into your admin account

Create a Client

On the left navigation bar, click on API Clients. Proceed and create a New Client and give this client a name. After, you will see the new client listed on the table together with the Client ID and Secret.

Client Settings

Click on the button at the end of your newly created client record on the table. This will take you to a page where you can manage the name and register an event handler and manage other client settings.

Register a Handler

Create your first handler at the very bottom of the page. (See Events below for more on handlers).


Nunua Sasa uses Events as a way of notifying you when an action has occurred. Each event requires a callback url (the event handler registered above) that we use to send the information related to this action back to you. For example when we confirm a payment, we trigger a Payment Confirmation event.

Currently, this Payment Confirmation Event is the sole event in our platform and it is a must-handle event. Consequently, all clients created in Nunua must have a handler created for this event as this is the only way to receive payment details from us when a payment is done on our platform.


Below are the events that currently exist:

Payment Confirmation

  • Event Name : Payment Confirmation
  • Method : POST
  • Description : This event is fired everytime there is a payment transaction triggered on our end.

Sample success response
                                            'status' : "success",
                                            'message' : "Payment has successfully been made",
                                            'user' : {
                                                'phone_number' : 'customer_phone_number_goes_here',
                                            'product' : {
                                                'code' : 'source_platform_product_code_goes_here',
                                                'amount_paid' : 100,
                                                'completion_status' : false,
                                                'next_payment' : 500,
                                                'next_payment_date' : 'next_payment_date_goes_here(dd/mm/yyyy)'
                                            'payment' : {
                                                'amount' : 1000,
                                                'mpesa_confirmation_code' : 'mpesa_confirmation_code_goes_here',
                                                'confirmation_date' : 12-06-2021,
                                                'merchant_request_id' : 'mpesa_merchant_code_goes_here',
                                                'checkout_request_id' : 'mpesa_checkout_request_id_goes_here'
                                            'extra' => {}
Sample error response
                                            'status' : "failure",
                                            'message' : 'Error message goes here'


Our APIs are organized around REST and return JSON-encoded responses.


OAuth Verification

  • URL : oauth/token
  • Method : POST
  • Description : Verification endpoint to receive your token.


grant_type REQUIRED
Defines the type of credentials used for verification. Value should be client_credentials
client_id REQUIRED
The Client ID received during creation of the client.
client_secret REQUIRED
The Client Secret received during creation of the client.

Sample Success Response

                                            'token_type' : 'Bearer',
                                            'expires_in' : 3599,
                                            'access_token' : 'access_token_goes_here'

Sample Error Response

                                            "error": "invalid_client",
                                            "error_description": "Client authentication failed",
                                            "message": "Client authentication failed"

Checkout API

  • URL : api/v1.1/checkout
  • Method : POST
  • Description : Process checkout details and extract required product and plan detail


Data object containing all the information required REQUIRED
Unique mobile phone number for paying customer.
data.product REQUIRED
Product object containing all the product information.
data.product.code REQUIRED
Unique product identification code from source platform. REQUIRED
Name of the product.
data.product.amount REQUIRED
Cost of the product.
data.plan REQUIRED
Plan object containing all the payment plan information
data.plan.deposit REQUIRED
The initial deposit amount required to be made for the product.
data.plan.repayment_period REQUIRED
Period within which all installments should be completed (Value should be in months).
data.plan.installment_rate REQUIRED
Time unit for installments (Value should be daily, weekly, monthly or yearly).
data.success_url REQUIRED
Url to be redirected to upon successful payment on Nunua Sasa
data.cancel_url REQUIRED
Url to be redirected to when payment was unsuccessful and customer wishes to return to original site
data.extra NULLABLE
Extra object containing any extra information that may be required by your system when the payment confirmation event is fired.

Sample Data Object

                                            'data' : {
                                                'phone' : '0712345678',
                                                'product' : {
                                                    'code' : 'K7ttt733r',
                                                    'name' : 'iPhone',
                                                    'amount' : 100000,
                                                'plan' : {
                                                    'deposit' : 50000,
                                                    'repayment_period' : 12,
                                                    'installment_rate' : 'daily',
                                                'success_url' : '',
                                                'cancel_url' : '',
                                                'extra' : {},

Sample Success Response

                                            "status": "success",
                                            "message": "Required details successfully obtained.",
                                            "data": []

Sample Error Response

                                        'data' :
                                            "status": "failure",
                                            "message": "Details not obtained",
                                            "data": {}

Support Desk

Feel free to reach out to us if you have any questions through our Contact Us page or send an email to us at

Version History

                                Version 1.0.0 - July 1st, 2021

                                - New Checkout API to process product purchases from other platforms
                                - Creation of the security protocols to ensure data security in transit
                                - Addition of the verification endpoints
                                - Set token expiry to 1 hour

                                Version 1.1.0 - August 20th, 2021

                                - Included 'cancel_url' in the body of the Checkout API request.
                                - Introduction of more options in the client settings:
                                    - You can now determine interest to be applied to the product price straight from your administrative dashboard
                                    - Ability to opt in/out at any time from application on inflation rate on the calculation of total amount to be paid by customers


Copyright and License

Copyright © 2021 All rights reserved | Powered by Revolution Analytics Limited