Payments API

Summary

This documentation page contains everything you need to know about integrating to Klasha’s Payment Gateway. Once integration is done, you can begin to process payments from anywhere in the world in seconds.

Whilst you start your integration, please remember to reach out to our Compliance team to go through the KYB process and get your business verified. This is a mandatory process before you can start using our production platform.

If you are going to be implementing the direct charge API, you would require additional verification as this is only available to businesses that are PCI-DSS certified.

Payment collection

As a business owner, here is a way we make it possible for you to collect payments from customers all over the world:

In all the following APIs, you can simply substitute the desired currency to the path variable {{gateway}}.

Before you begin

Get your API keys

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

Encryption algorithm

We are treating payment data, therefore all requests from merchant to our APIs must be encrypted in line with the industry standard. We make use of the standard 3DES technology with Padding for data encryption.

Below are code snippets for the 3DES encryption in different languages:

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);
}

public static string Encrypt3DES(string message, string secret)
{
    byte[] secretByte = Encoding.UTF8.GetBytes(secret.Trim());

    using (TripleDESCryptoServiceProvider tripleDES = new TripleDESCryptoServiceProvider())
    {
        tripleDES.Key = secretByte;
        byte[] iv = new byte[8];
        Buffer.BlockCopy(secretByte, 0, iv, 0, 8);
        tripleDES.IV = iv;
        tripleDES.Mode = CipherMode.CBC;
        tripleDES.Padding = PaddingMode.PKCS7;

        ICryptoTransform encryptor = tripleDES.CreateEncryptor(tripleDES.Key, tripleDES.IV);

        byte[] messageBytes = Encoding.UTF8.GetBytes(message);
        byte[] encryptedMessageBytes = encryptor.TransformFinalBlock(messageBytes, 0, messageBytes.Length);

        return Convert.ToBase64String(encryptedMessageBytes);
    }
}

#Ensure you have the pyDes library installed (pip install pyDes)

from pyDes import triple_des, PAD_PKCS5, CBC
import base64

def encrypt_3des(data, key):
    des = triple_des(key, CBC, pad=None, padmode=PAD_PKCS5)

    encrypted_data = des.encrypt(data)
   
    return base64.b64encode(encrypted_data).decode()

# Example usgae:
if __name__ == "__main__":
    # key (24 bytes)
    key = b'Use your 24 bytes key here'
    data = "Hello, Klasha!"
    encrypted_text = encrypt_3des(data, key)
    print("Encrypted text:", encrypted_text)

function encrypt3DES($messageToEncrypt, $secret) {
    $iv = substr($secret, 0, 8); // Get the IV (first 8 bytes of the secret key)
    $cipher = "des-ede3-cbc"; // 3DES encryption with CBC mode
    $options = OPENSSL_RAW_DATA;

    // Encrypt the message
    $encryptedMessageBytes = openssl_encrypt($messageToEncrypt, $cipher, $secret, $options, $iv);

    return base64_encode($encryptedMessageBytes);
}


// NOTE: You need crypto-js.min.js to use CryptoJS

function encrypt3DES(messageToEncrypt, secret) {
    try {
        if (secret.length < 24) {
            console.error("Secret key must be at least 24 characters long.");
            return;
        }

        // Use the first 24 characters of the secret key for 3DES
        const key = CryptoJS.enc.Utf8.parse(secret.substring(0, 24));

        // Use the first 8 characters of the secret key for the IV
        const iv = CryptoJS.enc.Utf8.parse(secret.substring(0, 8));

        // Encrypt the message
        const encrypted = CryptoJS.TripleDES.encrypt(messageToEncrypt, key, {
            iv: iv,
            mode: CryptoJS.mode.CBC,
            padding: CryptoJS.pad.Pkcs7,
        });

        // Return the Base64-encoded encrypted message
        return encrypted.toString();
    } catch (error) {
        console.error(error);
    }
}


const crypto = require('crypto');

/**
 * Encrypt a message using 3DES with CBC mode and PKCS5 padding.
 * @param {string} messageToEncrypt - The plaintext message to encrypt.
 * @param {Buffer} secret - The 24-byte secret key.
 * @returns {string} The Base64 encoded encrypted message.
 */
function encrypt3DES(messageToEncrypt, secret) {
    if (secret.length !== 24) {
        throw new Error('Secret must be exactly 24 bytes.');
    }
    // Derive the IV from the first 8 bytes of the secret key
    const iv = secret.slice(0, 8);  // First 8 bytes are used as IV

    // Create cipher
    const cipher = crypto.createCipheriv('des-ede3-cbc', secret, iv);

    // Encrypt the message
    let encrypted = cipher.update(messageToEncrypt, 'utf8', 'base64');
    encrypted += cipher.final('base64');

    return encrypted;
}

// Sample Usage
function testEncrypt3DES() {
    const jsonObject = {
        id: 1,
        name: 'John Doe',
        role: 'Senior Backend Engineer',
        skills: ['Java', 'Node.js', 'AWS']
    };

    // Convert JSON object to string
    const message = JSON.stringify(jsonObject);

    // 24-byte secret key
    const secretKey = '24-byte key'; // replace with your 24-byte encryption key

    console.log('Original JSON Object:', jsonObject);
    console.log('Secret Key (Base64):', secretKey.toString('base64'));

    // Encrypt the JSON string
    const encryptedMessage = encrypt3DES(message, secretKey);
    console.log('Encrypted Message (Base64):', encryptedMessage);
}

testEncrypt3DES();

Card payments

To accept a card payment, you need to integrate with the following flow:

First, initiate the card payment

Then charge the card

And at the end validate the payment (optional to provide OTP and/or PIN)

For all api calls here, you’d need to pass your public key as the value for x-auth-token in the request header. See guide here on how to retrieve your public key.

Parameter variables

see here for more explanation on the api parameters

Initiate card payment

POST - {{env_url}}/pay/aggregators/{{gateway}}/card/payment/v2

Headers

Name

Value

Content-Type

application/json

x-auth-token

Your merchant public key

Request Body (plain data to be encrypted)

^{must be encrypted before sending}

{
   "card_number": "507850785078507812",
   "card_holder_name": "John Doe",
   "cvv": "081",
   "expiry_month": "05",
   "expiry_year": "25",
   "currency": "NGN",
   "country": "NG",
   "amount": "200",
   "rate": 1,
   "paymentType": "woo",
   "sourceCurrency": "NGN",
   "sourceAmount": 200,
   "rememberMe": true,
   "phone_number": "080344006699",
   "email": "[email protected]",
   "fullname": "John Doe",
   "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a"
}

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Response

{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
        "data": {
           "status": "success",
            "message": "Charge authorization data required",
            "meta": {
                "authorization": {
                    "mode": "pin",
                    "fields": [
                        "pin"
                    ]
                }
            }
        }
    }
}

This is for cards that are covered by 3DS flows.
{
    "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
    "redirectUrl": "https://coreflutterwavestaging.com/flwmpgs/trxauth?hid=712b85a8542649e68c19b1c80d81aadc",
    "data": {
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://coreflutterwavestaging.com/flwmpgs/trxauth?hid=712b85a8542649e68c19b1c80d81aadc"
            }
        }
    }
}

{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
        "data": {
           "status": "success",
            "message": "Charge authorization data required",
            "meta": {
                "authorization": {
                    "mode": "avs_noauth",
                    "fields": [
                        "city",
                        "address",
                        "state",
                        "country",
                        "zipcode"
                    ]
                }
            }
        }
    }
}

Charge card

POST - {{env_url}}/pay/aggregators/{{gateway}}/charge/card/v2

Headers

Name

Value

Content-Type*

application/json

x-auth-token*

Your merchant public key

Request Body (plain data to be encrypted)

^{must be encrypted before sending}

{
    "mode": "pin",
    "pin": "1111",
    "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a"
}

{
    "mode": "avs_noauth",
    "city": "city",
    "address": "address",
    "state": "state",
    "country": "country",
    "zipcode": "zipcode",
    "tx_ref": "test910-on2007u047e-2910tytrr76"
}

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Response

{
    "message": "success",
    "error": null,
    "data": {
       "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
       "message": "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
       "status": "pending"
    }
}

Validate charge

POST - {{env_url}}/pay/aggregators/{{gateway}}/validate/card/v2

Headers

Name

Value

Content-Type

application/json

x-auth-token

Your merchant public key

Request Body (plain data to be encrypted)

^{must be encrypted before sending}

{
  "otp": "123456",
  "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
  "type": "card"
}

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Response

{
    "message": "success",
    "error": null,
    "data": {
       "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
       "amount": 200.0,
       "processor_response": "successful",
       "message": "Charge validated",
       "status": "successful"
    }
}

Bank transfer

POST - {{env_url}}/pay/aggregators/{{gateway}}/banktransfer/v3

Parameter variables

see here for more explanation on the api parameters

Headers

Name

Value

Content-Type

application/json

x-auth-token

Your merchant public key

Request Body (plain)

^{must be encrypted before sending}

{
   "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
   "amount": "500",
   "email": "[email protected]",
   "phone_number": "054709929220",
   "currency": "NGN",
   "narration": "A payment",
   "rate": 1.0,
   "paymentType": "woo",
   "productType": "COLLECTION",
   "sourceCurrency": "NGN",
   "sourceAmount": 500,
   "fullname": "Test"
}

{
   "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
   "amount": "500",
   "email": "[email protected]",
   "phone_number": "054709929220",
   "currency": "ZAR",
   "narration": "A payment",
   "rate": 1.0,
   "redirect_url": "merchant_url",
   "paymentType": "woo",
   "productType": "COLLECTION",
   "sourceCurrency": "ZAR",
   "sourceAmount": 500,
   "fullname": "Test"
}

{
   "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
   "amount": "500",
   "email": "[email protected]",
   "phone_number": "054709929220",
   "currency": "GHS",
   "narration": "A payment",
   "rate": 1.0,
   "redirect_url": "merchant_url",
   "paymentType": "woo",
   "productType": "COLLECTION",
   "sourceCurrency": "GHS",
   "sourceAmount": 500,
   "fullname": "Test"
}

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Response

{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
        "meta": {
            "authorization": {
                "mode": "banktransfer",
                "transfer_note": "Please make a bank transfer to Klasha - Collection",
                "transfer_amount": 500.0,
                "transfer_bank": "WEMA BANK",
                "account_expiration": "2024-05-23T13:55:13.105",
                "transfer_account": "8574551243"
            }
        },
        "message": "Charge initiated",
        "status": "success"
    }
}

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "tx_ref": "t67ede7fd-d8b2-4402-88e4-c3596486f3bf",
        "message": "Transaction in progress",
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://stagingpay.ozow.com/b1c1bb59-bf46-42ee-bc76-ccdf63e3f453/Secure",
                "validate_instructions": ""
            }
        }
    }
}

{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
        "message": "Charge initiated",
        "meta": {
            "authorization": {
                "transfer_account": "7003000100286",
                "transfer_bank": "Affinity",
                "account_expiration": "2025-06-11 12:12:13 PM",
                "transfer_note": "Mock note",
                "transfer_amount": "500.00",
                "mode": "banktransfer"
            }
        },
        "status": "success"
    }
}

M-Pesa

POST - {{env_url}}/pay/aggregators/{{gateway}}/card/payment/v2

Parameter variables

see here for more explanation on the api parameters

Headers

Name

Value

Content-Type

application/json

x-auth-token

Your merchant public key

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Request Body (plain)

^{must be encrypted before sending}

{
   "currency": "KES",
   "country": "KE",
   "amount": "10",
   "rate": 680,
   "paymentType": "woo",
   "sourceCurrency": "KES",
   "sourceAmount": 10,
   "rememberMe": true,
   "option": "mpesa",
   "phone_number": "+254710000000",
   "email": "[email protected]",
   "fullname": "John Doe",
   "tx_ref": "6b6164f9-8f90-481d-8d4f-d7774e9563aa"
}

Response

{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "KES",
            "customer": {
                "name": "John Doe",
                "phone_number": "+254710000000",
                "email": "[email protected]"
            },
            "status": "pending"
        },
        "message": "Transaction in progress",
        "status": "pending"
    }
}

Initiate a refund

POST {{env_url}}/nucleus/refund/initiate/v3

Headers

Name

Value

Content-Type

application/json

x-auth-token

Your merchant public key

Request Body (plain)

^{must be encrypted before sending}

{
    "txRef": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
    "amount": 500,
    "refundType": "partial"
}

Request body field description

Name

Type

Description

txRef*

String

Transaction reference

refundType*

String

Type of refund (must be either partial or full)

amount*

Double

Amount to be refunded

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Response

{
    "message": "success",
    "error": null,
    "data": {
        "txRef": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
        "refundTnxId": 12222,
        "businessId": 133,
        "refundedAmount": 500,
        "status": "pending"
    }
}

Get a refund status

GET - {{env_url}}/nucleus/refund/status/{{txRef}}/v2

Headers

Name

Value

Content-Type

application/json

x-auth-token

Your merchant public key

Response

{
    "message": "success",
    "error": null,
    "data": [
        {
            "refundType": "full",
            "txRef": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
            "refundTnxId": null,
            "businessId": 133,
            "refundedAmount": null,
            "status": "pending"
        }
    ]
}

Generate a bearer token

Authentication

Exchange rate

POST - {{env_url}}/nucleus/general/exchange/

Make a POST call to the exchange rate API.

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer "token"

Request Body

Name

Description

sourceCurrency

currency users will pay in

amount

destinationCurrency

destination currency

productType

KLASHA_PAY (static value)

businessId

your business ID

Response

{
    "message": "success",
    "error": null,
    "data": {
        "amount": 1557632.40,
        "rate": 0.000642,
        "buyingRate": 0.000676,
        "destinationCurrency": "NGN",
        "sourceCurrency": "USD",
        "cards": null
    }
}

PreviousTest Payments NextMobile money

Last updated 7 days ago