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>

Key

Value

Content-Type

application/json

Authorization

Bearer <token here>

{
    "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>

Key

Value

Context-Type

application/json

Authorization

Bearer <token here>

Request Body

Name Type Description

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

bankCode*

430000

countryCode*

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

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

This error occurs when the account number cannot be verified
{"error":"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>

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

Name

Type

Description

country*

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

{
    "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"
}

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

Query payout status

Make a GET call to the Fetch All API

GET {{env_url}}/wallet/wire/fetch/all

Make a GET call to the Fetch All API to retrieve all your previously initiated wire payments.

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

Key

Value

Content-Type

application/json

Authorization

Bearer <token here>

Response
{
    "message": "success",
    "error": null,
    "data": [
                {
                    "id": 1,
                    "sourceCurrency": "NGN",
                    "sourceAmount": 1000.00,
                    "destinationCurrency": "USD",
                    "destinationAmount": 575338.50,
                    "narration": "School fees",
                    "destinationFees": 27.50,
                    "sourceFees": 15821.81,
                    "rate": 575.338500,
                    "klashaWireStatus": "SUCCESSFUL",
                    "transactionReference": "KWire-66cf5990-610d-40eb-8eae-1c2839a4cd24",
                    "merchantBeneficiary": "87954c4f-736a-4e09-b588-76ab9c13bafe",
                    "quoteToken": "842dcd42-8f95-4a3b-a5f3-07a3d0416119",
                    "createdAt": "2023-10-09T13:11:29.478",
                    "updatedAt": "2023-10-09T15:06:03.076"
                },
                {
                    "id": 2,
                    "sourceCurrency": "NGN",
                    "sourceAmount": 1000.00,
                    "destinationCurrency": "USD",
                    "destinationAmount": 575338.50,
                    "narration": null,
                    "destinationFees": 27.50,
                    "sourceFees": 15821.81,
                    "rate": 575.338500,
                    "klashaWireStatus": "PENDING",
                    "transactionReference": null,
                    "merchantBeneficiary": "87954c4f-736a-4e09-b588-76ab9c13bafe",
                    "quoteToken": "acffe493-1f52-455e-93bb-b7c6bb76ea56",
                    "createdAt": "2023-10-11T13:31:46.806",
                    "updatedAt": "2023-10-11T13:31:46.806"
                }
              ]  

}

PreviousZAR Payout(new encryption)NextKlasha Wire API

Last updated 1 month ago