ZAR Payout(new encryption)

Summary

These APIs are used to initiate a ZAR payout

Before you begin!

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

Integration steps

Generate a bearer token

POST {{env_url}}/auth/account/v2/login

Passing your credentials to obtain a token.

Request Body

Name	Type	Description
username*	username
password*	password

200: OK

{
    "message": "success",
    "error": null,
    "data": {
        "token": "This is your token"
    }
}

400: Bad Request

{
    "message": "Invalid email or password.",
    "error": "wrong login details",
    "data": null
}

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/ZAR

200: OK

{
    "status": true,
    "message": "Banks retrieved",
    "data": [
        {
            "id": 140.0,
            "name": "Absa Bank Limited, South Africa",
            "slug": "absa-za",
            "code": "632005",
            "longcode": "632005",
            "gateway": null,
            "pay_with_bank": false,
            "active": true,
            "country": "South Africa",
            "currency": "ZAR",
            "type": "basa",
            "is_deleted": false,
            "createdAt": "2020-09-04T10:38:56.000Z",
            "updatedAt": null
        },
        {
            "id": 140.0,
            "name": "Absa Bank Limited, South Africa",
            "slug": "absa-za",
            "code": "632005",
            "longcode": "632005",
            "gateway": null,
            "pay_with_bank": false,
            "active": true,
            "country": "South Africa",
            "currency": "ZAR",
            "type": "basa",
            "is_deleted": false,
            "createdAt": "2020-09-04T10:38:56.000Z",
            "updatedAt": null
        }
	 ]
	}

Resolve Bank Account

Make a POST call to the resolve account API

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

Request Body

Name	Type	Description
bankCode*		430000
countryCode*		ZA
accountNumber*		Sydney Mark
accountType*		personal
documentType*	String	identityNumber
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.

Request body (encrypted):

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

Request body (non-encrypted):

Request Body

Name	Type	Description
country*		ZA
bankCode*		430000
amount*		100
accountName*		Sydney Mark
requestId*	String	kbtr-3857-011-133-166993253334816
description*	String	Payout
currency*	String	ZAR
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 GET call to the Fetch All API

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

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

The URL can be found in the Postman link well as other APIs

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

200: OK

Response
{
    "message": "success",
    "error": null,
    "data": {[
        "id": 5,
        "sourceCurrency": "NGN",
        "sourceAmount": 1000,
        "destinationCurrency": "USD",
        "destinationAmount": 575338.5,
        "narration": "School fees",
        "destinationFees": 27.5,
        "sourceFees": 15821.81,
        "rate": 575.3385,
        "klashaWireStatus": "PENDING",
        "transactionReference": "KWire-32f1d4c6-4560-4033-8cf6-713d405ec10d",
        "merchantBeneficiary": "7ed8d2e3-8709-4202-8842-7757946ee194",
        "quoteToken": "1c8eaf0d-3490-4774-ae86-7443e4f93557",
        "createdAt": "2023-10-26T12:44:37.355",
        "updatedAt": "2023-10-26T12:45:27.243"
    },
	...{
    "message": "success",
    "error": null,
    "data": {[
        "id": 5,
        "sourceCurrency": "NGN",
        "sourceAmount": 1000,
        "destinationCurrency": "USD",
        "destinationAmount": 575338.5,
        "narration": "School fees",
        "destinationFees": 27.5,
        "sourceFees": 15821.81,
        "rate": 575.3385,
        "klashaWireStatus": "PENDING",
        "transactionReference": "KWire-32f1d4c6-4560-4033-8cf6-713d405ec10d",
        "merchantBeneficiary": "7ed8d2e3-8709-4202-8842-7757946ee194",
        "quoteToken": "1c8eaf0d-3490-4774-ae86-7443e4f93557",
        "createdAt": "2023-10-26T12:44:37.355",
        "updatedAt": "2023-10-26T12:45:27.243"
    },
	...]
}]
}