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

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

Headers

KeyValue

Content-Type

application/json

Authorization

Bearer <token here>

{
    "message": "success",
    "error": null,
    "data": [
       {
            "id": 140.0,
            "name": "Absa Bank Limited, South Africa",
            "slug": "absa-za",
            "code": "632005",
            "longcode": "632005",
            "gateway": null,
            "pay_with_bank": false,
            "supports_transfer": true,
            "active": true,
            "country": "South Africa",
            "currency": "ZAR",
            "type": "basa",
            "is_deleted": false,
            "createdAt": "2020-09-04T10:38:56.000Z",
            "updatedAt": null
        },
        {
            "id": 712.0,
            "name": "Access Bank South Africa",
            "slug": "access-bank-south-africa-za",
            "code": "410506",
            "longcode": "410506",
            "gateway": "",
            "pay_with_bank": false,
            "supports_transfer": true,
            "active": true,
            "country": "South Africa",
            "currency": "ZAR",
            "type": "basa",
            "is_deleted": false,
            "createdAt": "2023-08-22T08:30:09.000Z",
            "updatedAt": "2023-08-23T08:20:47.000Z"
        } 
    ]
}

Resolve Bank Account

Make a POST call to the resolve account API

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

Headers

KeyValue

Context-Type

application/json

Authorization

Bearer <token here>

Request Body

NameTypeDescription

bankCode*

430000

countryCode*

ZA

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

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

KeyValue

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

NameTypeDescription

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

mobileNumber

String

Recipient mobile number

recipientAddress

String

Recipient address

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

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.

KeyValue

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

}

Last updated