Partnerships

API Documentation

The Sasa Pay API provides programmatic access to allow Merchants get paid by their customers using Sasa Pay. Authentication to the API uses Oauth2.

To use this API, you need an active Sasa Pay Account. This portal provides a platform to generate Client ID and Client Secret. To access resources, you need an Access Token which can be obtained by posting the generated Client ID and Secret to the relevant endpoint. Please contact us at info@sasapay.co.ke for more information. Remember to store your credentials securely.

This document describes in detail the payload structures for the following services:
• Authentication
• Client to Business Payment (C2B)
• Business to Client Payment (B2C)

The developer/third party needs to register on the API gateway accessible on the below link.

https://docs.skoinapp.net/guide/

Authentication

To authenticate and get an access token, you need to make a POST call to the following url:

https://sandbox.skoinapp.net/api/v1/auth/token/

Field	Type	Description
username	string	Your App's username
password	string	Your App's password
client_id	string	Your App's client id(Consumer Key)
client_secret	string	Your App's client secret (Consumer Secret).

                        REQUEST
                        
                            curl --location --request POST 'https://sandbox.skoinapp.net/api/v1/auth/token/' \
                        --header 'Content-Type: application/json' \
                        --data-raw '{
                        "username": "xxxxxx",
                        "password" : "xxxxxx",
                        "client_id": "xxxxxx",
                        "client_secret": "xxxxxx"
                        }'

                        RESPONSE
{
    "status": true,
    "detail": "Authentication successful",
    "auth_details": {
        "access_token": "1we46wtssihdhh63jjg5bVHjJ1Oafxc15rbKcIH",
        "expires_in": 36000,
        "token_type": "Bearer",
        "scope": "read write merchants",
        "refresh_token": "zUZL5ePghdhs45dFbVGIPQ3uQszPTnmf14oRDXv"
    }
}

C2B Payments

The Sasa Pay API provides programmatic access to allow Merchants get paid by their customers using Sasa Pay.

Request Payment

To request payment, you need to make a POST call to the following url:

https://sandbox.skoinapp.net/api/v1/payments/request-payment/

Field	Type	Description
bill_number	string	Your Biller Number
customer_mobile	string	Customer's mobile number as registered with Sasa Pay
transaction_ref	string	Unique transaction reference
transaction_description	string	A brief description of the transaction
currency	string	Currency
amount	integer	Transaction Amount
callback_url	string	Callback url to send results to

                        REQUEST
                        curl --location --request POST 'https://sandbox.skoinapp.net/api/v1/payments/request-payment/' \
                        --header 'Content-Type: application/json' \
                        --data-raw '{
                            "biller_number": "565656",
                            "customer_mobile": "254726XXXXXX",
                            "transaction_ref": "102052",
                            "transaction_description": "Pay for groceries",
                            "currency": "KES",
                            "amount": 200,
                            "callback_url":"http://example.com/api/v1/payments/results/"
                        }'

                        RESPONSE
{
    "status": true,
    "detail": "OTP sent. Share the code to complete transaction",
    "checkout_id": "deb4bc7e-23cb-4c59-845c-c438d315aa0d"
}

Process Payments

To conclude payment you need to make a POST call to the following url:

https://sandbox.skoinapp.net/api/v1/payments/process-payment/

Field	Type	Description
biller_number	string	Your Biller Number
checkout_id	string	The checkout id obtained in the previous step
customer_mobile	string	Customer's mobile number as registered with Sasa Pay
otp	string	The One Time Passcode code sent the Customer's mobile number

                        REQUEST
curl --location --request POST 'https://sandbox.skoinapp.net/api/v1/payments/process-payment/' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "checkout_id": "deb4bc7e-23cb-4c59-845c-c438d315aa0d",
        "biller_number": "565656",
        "customer_mobile": "25472XXXXXX",
        "otp": "123456"
    }'

                        RESPONSE
{
    "status": true,
    "detail": "Transaction submitted for processing"
}

# If merchant has provided a result URL, Callback Response Data will have the following format

{
    "PaymentGateway":"SasaPay",
    "TransactionType":"C2B",
    "TransID": "deb4bc7e-23cb-4c59-845c-c438d315aa0d",
    "TransTime":"20210919083214",
    "TransAmount":"300.00",
    "BusinessShortCode": "565656",
    "BillRefNumber":"102052",
    "InvoiceNumber":"102052",
    "OrgAccountBalance":"",
    "ThirdPartyTransID":"102052",
    "MSISDN":"25472XXXXXX",
    "FirstName":"Jane",
    "MiddleName":"Doe",
    "LastName":""
}

B2C Payments

The Sasa Pay API provides programmatic access to allow Merchants get paid by their customers using Sasa Pay.

Initiate Payment

To request payment you need to make a POST call to the following url:

https://sandbox.skoinapp.net/api/v1/payments/b2c/

Field	Type	Description
bill_number	string	Your Biller Number
recipient_mobile	string	Customer's mobile number as registered with Sasa Pay
transaction_ref	string	Unique transaction reference
transaction_type	string	The transaction type. Must be set to 'B2C'
remarks	string	A brief description of the transaction
currency	string	Currency
amount	integer	Transaction Amount
callback_url	url	Callback url to send results to

                        REQUEST
                        curl --location --request POST 'https://sandbox.skoinapp.net/api/v1/payments/b2c/' \
    --header 'Authorization: Bearer  Q9w7s6uefquQt0xVOq6UiJeu3HYYSHr' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "transaction_ref": 1020,
        "transaction_type": "B2C",
        "remarks": "Refund",
        "biller_number" : "M-001",
        "recipient_mobile": "072645xxxx",
        "amount": 300,
        "callback_url":"https://example.com/callbacks"
    }'

                        RESPONSE
{
    "status": true,
    "detail": "Transaction is being processed",
    "transaction": {
        "transaction_ref": 1020,
        "transaction_type": "B2C",
        "biller_number": "M-001",
        "recipient_mobile": "072645xxxx",
        "amount": 300.0,
        "remarks": "Refund"
    }
}