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:

• Card Payments

• Bank transfer

• M-Pesa

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

Since we are treating payment data, the communication from merchant to APIs must be encrypted. Expand the section to find out more about the encryption algorithm and how to use it.

How to use

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

If you are using any other programming language asides Java in your applications, please reach out to us; we can 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.

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 (to provider OTP and/or PIN)

Initiate card payment

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

You can find more information on the Postman link as 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.

Headers

Name	Value
Content-Type	application/json

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Request Body (plain)

{
   "card_number": "5531886652141111",
   "cvv": "111",
   "expiry_month": "01",
   "expiry_year": "25",
   "currency": "NGN",
   "country": "NG",
   "amount": "200",
   "rate": 1,
   "paymentType": "woo",
   "sourceCurrency": "NGN",
   "sourceAmount": 200,
   "rememberMe": true,
   "phone_number": "080344006699",
   "email": "[e-mail]",
   "fullname": "John Doe",
   "tx_ref": "test910-on2007u047e-2910tytrr76"
}

Response

200

{
    "tx_ref": "encrypt-card-test04",
    "data": {
        "status": "success",
        "message": "Charge authorization data required",
        "meta": {
            "authorization": {
                "mode": "pin",
                "fields": [
                    "pin"
                ]
            }
        }
    }
}

200

This is for cards that are covered by 3DS flows.
{
    "tx_ref": "klasha-add-bank-card-1697954ttt947238348",
    "redirectUrl": "https://coreflutterwavestaging.com/flwmpgs/trxauth?hid=712b85a8542649e68c19b1c80d81aadc",
    "data": {
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://coreflutterwavestaging.com/flwmpgs/trxauth?hid=712b85a8542649e68c19b1c80d81aadc"
            }
        }
    }
}

400

{
    "status": "error",
    "message": "Card number is invalid",
    "data": null,
    "tx_ref": "klasha-add-bank-card-1697954ttt947238348"
}

Charge card

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

You can find more information on the Postman link as 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.

Headers

Name	Value
Content-Type	application/json

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Request Body (plain)

The tx-ref is contained in the successful response of the initiate payment call.

{
    "mode": "pin",
    "pin": "3310",
    "tx_ref": "test910-on2007u047e-2910tytrr76"
}

Response

200

{
    "tx_ref": "encrypt-card-test04",
    "message": "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
    "status": "pending"
}

400

{
    "status": "error",
    "message": "Invalid Pin",
    "data": null,
    "tx_ref": "klasha-add-bank-card-odochi_test_test11"
}

Validate card

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

You can find more information on the Postman link as well as other APIs.

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

Headers

Name	Value
Content-Type	application/json

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Request Body (plain)

The tx-ref is contained in the successful response of the initiate payment call.

{
  "otp": "123456",
  "tx_ref": "test910-on2007u047e-291076",
  "type": "card"
}

Response

200

{
    "tx_ref": "encrypt-card-test04",
    "amount": 100.0,
    "processor_response": "successful",
    "message": "Charge validated",
    "status": "successful"
}

400

{
    "status": "error",
    "message": "Invalid OTP",
    "data": null,
    "tx_ref": "klasha-add-bank-card-odochi_test_test11"
}

Bank transfer

POST {{env_url}}/pay/aggregators/{gateway}/banktransfer/v2

You can find more information on the Postman link as 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.

Headers

Name	Value
Content-Type	application/json

Request Body (plain)

{
   "tx_ref": "MC-15856767458ffdgddfefhqweert",
   "amount": "500",
   "email": "[e-mail]",
   "phone_number": "054709929220",
   "currency": "NGN",
   "narration": "A payment",
   "rate": 1.0,
   "paymentType": "woo",
   "sourceCurrency": "NGN",
   "sourceAmount": 500,
   "fullname": "Test",
   "redirect_url": "https://redirect.com"
}

Response

200

{
    "tx_ref": "test910-on2007u047e-cvercdfer",
    "meta": {
        "authorization": {
            "mode": "banktransfer",
            "transfer_note": "Please make a bank transfer to Klasha - Collection",
            "transfer_amount": 10.0,
            "transfer_bank": "WEMA BANK",
            "account_expiration": "2024-03-11T10:28:06.793",
            "transfer_account": "8575492419"
        }
    },
    "message": "Charge initiated",
    "status": "success"
}

M-Pesa

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

You can find more information on the Postman link as well as other APIs.

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

Headers

Name	Value
Content-Type	application/json

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Request Body (plain)

{
   "currency": "KES",
   "country": "KE",
   "amount": "10",
   "rate": 680,
   "paymentType": "woo",
   "sourceCurrency": "USD",
   "sourceAmount": 1,
   "rememberMe": true,
   "option": "mpesa",
   "phone_number": "080344006699",
   "email": "[e-mail]",
   "fullname": "John Doe",
   "tx_ref": "test910-on2007u047e-291076"
}

Response

200

{
    "tx_ref": "test910-on2007u047e-mcnvmlbhgmjfo",
    "data": {
        "amount": 10,
        "charged_amount": 10,
        "currency": "KES",
        "status": "pending",
        "customer": {
            "id": 1965193,
            "phone_number": "25480344006699",
            "name": "yemi desola",
            "email": "[e-mail]",
            "created_at": "2023-01-31T20:01:39.000Z"
        }
    },
    "message": "Successful",
    "status": "pending"
}

400

{
    "tx_ref": "test910-on2007u047e-mcnvmlbhgmjfo",
    "data": null,
    "message": "Invalid phone number format",
    "status": "error"
}

Get status

POST {{env_url}}/nucleus/wordpressstatus/tnxrefStatus

You would need to pass, as header an Authorization bearer token. Please check the next paragraph to see how to obtain your token.

Headers

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

Request Body

{
	"txnRef": "transaction-reference"
}

Response

200

{
    "destinationCurrency": "KES",
    "sourceAmount": 1800.0000000000,
    "sourceCurrency": "KES",
    "status": "successful",
    "destinationAmount": 1800.0000000000,
    "customer": {
        "id": 305935,
        "name": "Name",
        "email": "[e-mail]",
        "phone": "0801234567",
        "createdAt": "2022-10-26 17:21:21",
        "updatedAt": "2022-10-26 17:21:21"
    }
}

400

{
    "destinationCurrency": "KES",
    "sourceAmount": 1800.0000000000,
    "sourceCurrency": "KES",
    "status": "failed",
    "destinationAmount": 1800.0000000000,
    "customer": {
    "id": 305935,
        "name": "Name",
        "email": "[e-mail]",
        "phone": "0801234567",
        "createdAt": "2022-10-26 17:21:21",
        "updatedAt": "2022-10-26 17:21:21"
    }
}

Generate a bearer token

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

Make a POST call to the Auth Account V2 passing your credentials to obtain a token.

Headers

Name	Value
Content-Type	application/json

Request Body

Name	Description
username	username
password	password

Response

200

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

400

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