Get Started

Nunua Sasa has android app endpoints organized around REST. The APIs have predictable resource-oriented URLs, accept form-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes, authentication, and verbs.

Basic Authentication

Authentication and authorization to the API is performed via HTTP OAuth 2.0. Access Tokens are provided after logging in and are used to gain the authorization needed to access all protected endpoints. Once logged out the token can no longer be used.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

User Auth

This section details the process of registration. There are multiple endpoints created for each of the steps that are required to complete the registration of a user on the Nunua Sasa app

Send OTP

A POST request responsible for sending a One Time Password (OTP) to verify the mobile phone number

Endpoint URL: /api/v1.1/otp/send

Request

A request is sent that contains the patameters listed below:

Parameter Type Position # Description
phone string Body Required Phone Number of the customer

Success Response

{
    "status": success,
    "message": "OTP sent!"
}

Verify OTP

A POST request responsible for Verifying the OTP sent

Endpoint URL: /api/v1.1/otp/verify

Request

A request is sent that contains the patameters listed below:

Parameter Type Position # Description
phone string Body Required Phone Number of the customer
otp int Body Required OTP sent to the customer

Success Response

{
    "status": success,
    "message": "OTP Verified!"
}

Upload Photos

A POST request responsible for collecting customer bio data and picture

Endpoint URL: /api/v1.1/upload

Request

A request is sent that contains the patameters listed below:

Parameter Type Position # Description
phone string Body Required Phone Number of the customer
photo image Body Required Profile photo of the customer
id_front image Body Required Front side of the customer's ID
id_back image Body Required Back side of the customer's ID

Success Response

{
    "status": "success",
    "message": "Required details successfully obtained",
    "data": {
        "customer" : {
            "name": "John Doe",
            "id_number": "11122234",
            "dob": {
                "date": "1900-01-01 14:23:32.000000",
                "timezone_type": 3,
                "timezone": "Africa/Nairobi"
            },
            "photo": "path_to_image",
            "id_front": "path_to_image",
            "id_back": "path_to_image",
            "user_id": 26,
            "updated_at": "2021-11-17T11:23:32.000000Z",
            "created_at": "2021-11-17T11:23:32.000000Z",
            "id": 1
        }
    }
}

Create Account

A POST request responsible for creating a thew new user account tied to all the customer data collected

Endpoint URL: /api/v1.1/create

Request

A request is sent that contains the patameters listed below:

Parameter Type Position # Description
email string, email Body Required Email of the customer
name string Body Required Name of the customer
id_number int Body Required ID number of the customer
dob date Body Required Date of birth of the customer

Success Response

{
    "status": "success",
    "message": "User registered successfully",
    "data": {
        "user": {
            "id": 26,
            "email": "johndoe@gmail.com",
            "phone": "0712333444",
            "phone_verified_at": "2021-11-17 14:18:14",
            "password_updated_at": null,
            "created_at": "2021-11-17T11:17:14.000000Z",
            "updated_at": "2021-11-17T11:40:48.000000Z",
            "customer": {
                "id": 5,
                "name": "John Doe",
                "id_number": "11122234",
                "dob": "1900-01-01",
                "photo": "path_to_file",
                "id_front": "path_to_file",
                "id_back": "path_to_file",
                "score": null,
                "verified": 0,
                "verified_by": null,
                "installment_payment": 1,
                "savings_account": 0,
                "user_id": 26,
                "created_at": "2021-11-17T11:23:32.000000Z",
                "updated_at": "2021-11-17T11:40:48.000000Z"
            }
        }
    }
}

Log In

A POST request responsible for customer log in

Endpoint URL: /api/v1.1/login

Request

A request is sent that contains the patameters listed below:

Parameter Type Position # Description
email string, email Body Required Email of the customer
password string Body Required Password of the customer

Success Response

{
    "access_token": "access_token_goes_here",
    "token_type": "Bearer",
    "expires_at": "2021-11-23 16:41:03"
}

Log Out

A POST request responsible for logging the customer out

Endpoint URL: /api/v1.1/logout

Request

A request is sent to action the logout process

Success Response

{
    'status' : 'success',
    'message' : 'Successfully logged out'
}

User Details

A GET Request responsible for getting the currently logged in user

Endpoint URL: /api/v1.1/user

Request

A request is sent to obtain the user information

Success Response

{
    "status": "success",
    "message": "User details retrieved.",
    "data": {
        "user": {
            "id": 21,
            "email": "johndoe@gmail.com",
            "phone": "0712333444",
            "phone_verified_at": "2021-10-06 18:41:27",
            "password_updated_at": "2021-10-06T15:46:59.000000Z",
            "created_at": "2021-10-06T15:41:27.000000Z",
            "updated_at": "2021-10-06T15:46:59.000000Z",
            "customer": {
                "id": 4,
                "name": "Test Customer",
                "id_number": 7112332,
                "dob": "1900-01-01",
                "photo": "path_to_image",
                "id_front": "path_to_image",
                "id_back": "path_to_image",
                "score": 988,
                "verified": 1,
                "verified_by": 1,
                "installment_payment": 1,
                "savings_account": 1,
                "user_id": 21,
                "created_at": "2021-10-06T15:46:59.000000Z",
                "updated_at": "2021-11-04T12:00:05.000000Z"
            }
        }
    }
}

Fetch Statement

A POST Request responsible for Fetching MPESA Statement

Endpoint URL: /statement/download

Request

A Fetch request is sent with the following paramters

Parameter Type Position # Description
phone int Body Required Phone Number of the customer
customer string Body Required Customer ID requesting to fetch statement

Success Response

                {
                    'status' : 'success',
                    'message' : ->message,
                    'data' : [
                        'statement' : ->statement
                    ]
                }

View Products

A POST request responsible for fetching a user's products

Endpoint URL: /api/v1.1/products

Request

A request is sent to obtain the products under the currently logged in user

Success Response

{
    "status": "success",
    "message": "User details retrieved.",
    "data": {
        "products": [
            {
                "id": 15,
                "code": "ettertwy",
                "name": "Table1",
                "amount": 200000,
                "amount_paid": 100000,
                "next_payment_type": "installment",
                "next_payment": 50000,
                "next_payment_date": "2022-01-14T21:00:00.000000Z",
                "date_completed": null,
                "success_url": "https://www.google.com",
                "cancel_url": "https://www.google.com",
                "extra": [],
                "customer_id": 4,
                "company_id": 1,
                "client_id": 1,
                "created_at": "2021-11-16T11:18:14.000000Z",
                "updated_at": "2021-11-16T11:23:50.000000Z"
            },
            {
                "id": 16,
                "code": "erwer234rewr",
                "name": "Seat",
                "amount": 10000,
                "amount_paid": 0,
                "next_payment_type": "deposit",
                "next_payment": 5000,
                "next_payment_date": null,
                "date_completed": null,
                "success_url": "https://www.google.com",
                "cancel_url": "https://www.google.com",
                "extra": [],
                "customer_id": 4,
                "company_id": 1,
                "client_id": 1,
                "created_at": "2021-11-16T11:23:07.000000Z",
                "updated_at": "2021-11-16T11:23:07.000000Z"
            }
        ]
    }
}

Status Codes

Nunua API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.) Codes in the 5xx range indicate an error with Nunua's servers (these are rare).

Code Meaning Description
200 Ok Everything worked as expected
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
409 Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 Server Errors Something went wrong on Nunua's end.