KES Payout(new encryption)

Summary

These APIs are used to initiate a KES payout

Before you begin!

• Find your keys on the Klasha Dashboard → Settings → Generate API Keys (here)

Integration steps

Token Generation

Encryption algorithm

Since we are treating payment data, the whole communication from merchant to APIs has to be encrypted.

If you are using any other programming language in your applications, please reach out to us, we might be able to help.

The secret , also known as the encryption key, can be found in the Klasha Dashboard → Settings → Generate API Keys (here), under the caption New encryption key.

We are using a standard 3DES technology with Padding. Please find some code snippets here:

public static String encrypt3DES(String messageToEncrypt, byte[] secret) throws NoSuchPaddingException, NoSuchAlgorithmException,
            InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
    SecretKeySpec secretKeySpec = new SecretKeySpec(secret, "TripleDES");
    byte[] iv = Arrays.copyOfRange(secret, 0, 8);
    IvParameterSpec ivSpec = new IvParameterSpec(iv);

    Cipher encryptCipher = Cipher.getInstance("TripleDES/CBC/PKCS5Padding");
    encryptCipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivSpec);

    byte[] secretMessagesBytes = messageToEncrypt.getBytes(StandardCharsets.UTF_8);
    byte[] encryptedMessageBytes = encryptCipher.doFinal(secretMessagesBytes);

    return Base64.getEncoder().encodeToString(encryptedMessageBytes);
}

Get Bank Lists

Make a GET call to the Bank List API

GET {{env_url}}/wallet/merchant/bank/transfer/request/banks/KES

Headers

Key	Value
Content-Type	application/json
Authorization	Bearer <token here>

200: OK

{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "35",
            "name": "ABC Bank"
        },
        {
            "code": "03",
            "name": "Absa Bank"
        },
        {
            "code": "063903",
            "name": "AirtelMoney"
        },
        {
            "code": "19",
            "name": "Bank of Africa"
        },
        {
            "code": "36",
            "name": "Choice Microfinance Bank"
        },
        {
            "code": "16",
            "name": "Citibank"
        },
        {
            "code": "23",
            "name": "Consolidated Bank"
        },
        {
            "code": "11",
            "name": "Cooperative Bank"
        },
        {
            "code": "25",
            "name": "Credit Bank"
        },
        {
            "code": "75",
            "name": "DIB Bank"
        },
        {
            "code": "63",
            "name": "DTB"
        },
        {
            "code": "43",
            "name": "Eco Bank"
        },
        {
            "code": "68",
            "name": "Equity Bank"
        },
        {
            "code": "70",
            "name": "Family Bank"
        },
        {
            "code": "74",
            "name": "First Community Bank"
        },
        {
            "code": "53",
            "name": "Guaranty Bank"
        },
        {
            "code": "55",
            "name": "Guardian Bank"
        },
        {
            "code": "72",
            "name": "Gulf African Bank"
        },
        {
            "code": "61",
            "name": "HFC Bank"
        },
        {
            "code": "57",
            "name": "I&M Bank"
        },
        {
            "code": "01",
            "name": "KCB"
        },
        {
            "code": "51",
            "name": "Kingdom Bank"
        },
        {
            "code": "78",
            "name": "KWFT Bank"
        },
        {
            "code": "14",
            "name": "M-Oriental"
        },
        {
            "code": "65",
            "name": "Mayfair Bank"
        },
        {
            "code": "18",
            "name": "Middle East Bank"
        },
        {
            "code": "063902",
            "name": "Mpesa"
        },
        {
            "code": "12",
            "name": "National Bank"
        },
        {
            "code": "07",
            "name": "NCBA"
        },
        {
            "code": "50",
            "name": "Paramount Universal Bank"
        },
        {
            "code": "10",
            "name": "Prime Bank"
        },
        {
            "code": "00",
            "name": "SasaPay"
        },
        {
            "code": "66",
            "name": "Sidian Bank"
        },
        {
            "code": "12",
            "name": "Stanbic Bank"
        },
        {
            "code": "02",
            "name": "Standard Chartered Bank KE"
        },
        {
            "code": "89",
            "name": "Stima Sacco"
        },
        {
            "code": "063907",
            "name": "T-Kash"
        },
        {
            "code": "97",
            "name": "Telcom Kenya"
        },
        {
            "code": "76",
            "name": "UBA"
        },
        {
            "code": "54",
            "name": "Victoria Commercial Bank"
        }
    ]
}

Resolve Bank Account

Make a POST call to the resolve account API

POST {{env_url}}/wallet/merchant/bank/transfer/request/resolve/account

Headers

Key	Value
Context-Type	application/json
Authorization	Bearer <token here>

Request Body

Name	Type	Description
bankCode*		430000
countryCode*		KE
accountNumber*		Sydney Mark
accountType*		personal
documentType*	String	Customer’s mode of identity. This could be one of: [identityNumber, passportNumber, businessRegistrationNumber]
businessId*	String	133
documentNumber*	String	8801235111088

200: OK

{
    "status": true,
    "message": "Personal Account Verification attempted",
    "data": {
        "verified": true,
        "verificationMessage": "Account is verified successfully"
    }
}

400: Bad Request

This error occurs when the account number cannot be verified
{"error":"Bad request"}

400: Bad Request

This error occurs when the right "countryCode" is not passed in
{
    "message": "Operation not allowed.",
    "error": "Operation not allowed",
    "data": null
}

Merchant Payout request

Make a POST call to the Merchant payout request API

POST {{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request

You would need to pass, as a header the x-auth-token. This can be obtained from your merchant dashboard → Settings → Generate API keys → Merchant public key.

Headers

Key	Value
Content-Type	application/json
x-auth-token	Your merchant public key
Authorization	Bearer <token here>

Request body (encrypted):

{ 
  "message": "encrypted-request-body"
}

Request body (plain)

Request Body

Name	Type	Description
country*		KE
bankCode*		430000
amount*		100
accountName*		Sydney Mark
requestId*	String	kbtr-3857-011-133-166993253334816
description*	String	Payout
currency*	String	KES
bankName*	String	Ubank Ltd
accountNumber*	String	1222951828

200: OK

{
    "id": 3,
    "amount": 1000,
    "payoutStatus": "PENDING",
    "requestId": "kbtr-3857-011-133-166993253334816",
    "narration": "certification",
    "country": "SA",
    "fee": 25,
    "bankCode": "430000",
    "bankName": "Ubank Ltd",
    "accountNumber": "0690000032",
    "accountName": "Pastor Bright"
}

400: Bad Request

{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}

Query payout status

Make a call to fetch status of initiated payouts.