Nunua Sasa Checkout APIs Reference
Version 1.1.0
Introduction
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.
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.
How to Start
Once you have contacted us via info@revolution-analytics.co.ke 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).
Introduction
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.
Types
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.
{
'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' => {}
}
{
'status' : "failure",
'message' : 'Error message goes here'
};
Introduction
Our APIs are organized around REST and return JSON-encoded responses.
Endpoints
OAuth Verification
- URL : oauth/token
- Method : POST
- Description : Verification endpoint to receive your token.
Parameters
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
Parameters
data REQUIRED
Data object containing all the information required
data.phone 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.
data.product.name 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' : 'https://example.com',
'cancel_url' : 'https://example.com',
'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 info@revolution-analytics.co.ke
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