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
Encryption algorithm
Since we are treating payment data, the communication from merchant to APIs must be encrypted. We are using a standard 3DES technology with Padding. Please find some code snippets below for the 3DES encryption:
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);
}
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 provide 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
Content-Type
application/json
x-auth-token
Your merchant public key
Request Body (encrypted)
{
"message": "encrypted-body"
}
Request Body (plain)
{
"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": "test910-on2007u047e-2910tytrr76"
}
Response
{
"message": "success",
"error": null,
"data": {
"tx_ref": null,
"data": {
"status": "success",
"message": "Charge authorization data required",
"meta": {
"authorization": {
"mode": "pin",
"fields": [
"pin"
]
}
}
}
}
}
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
Content-Type
application/json
x-auth-token
Your merchant public key
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": "1111",
"tx_ref": "test910-on2007u047e-2910tytrr76"
}
Response
{
"message": "success",
"error": null,
"data": {
"tx_ref": "test910-on2007u047e-2910tytrr76",
"message": "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
"status": "pending"
}
}
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
Content-Type
application/json
x-auth-token
Your merchant public key
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
{
"message": "success",
"error": null,
"data": {
"tx_ref": "test910-on2007u047e-291076",
"amount": 200.0,
"processor_response": "successful",
"message": "Charge validated",
"status": "successful"
}
}
Bank transfer
POST
{{env_url}}/pay/aggregators/{{gateway}}/banktransfer/v3
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.
Parameter Variables
{{gateway}}
NGN, ZAR or GHS
Headers
Content-Type
application/json
x-auth-token
Your merchant public key
Request Body (encrypted)
{
"message": "encrypted-body"
}
Request Body (plain) for different gateways.
{
"tx_ref": "MC-15856767458ffdgddfefhqweert",
"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"
}
Response for different gateways.
{
"message": "success",
"error": null,
"data": {
"tx_ref": "MC-15856767458ffdgddfefhqweert",
"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"
}
}
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
Content-Type
application/json
x-auth-token
Your merchant public key
Request Body (encrypted)
{
"message": "encrypted-body"
}
Request Body (plain)
{
"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": "test910-on2007u047e-291076"
}
Response
{
"message": "success",
"error": null,
"data": {
"tx_ref": "test910-on2007u047e-291076",
"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
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
Content-Type
application/json
x-auth-token
Your merchant public key
Request Body (encrypted)
{
"message": "encrypted-body"
}
Request Body (plain)
{
"txRef": "txRef",
"amount": 500,
"refundType": "partial"
}
txRef
Transaction reference
refundType
partial or full
amount
refund amount
Response
{
"message": "success",
"error": null,
"data": {
"txRef": "txRef",
"refundTnxId": 12222,
"businessId": 133,
"refundedAmount": 500,
"status": "pending"
}
}
Get a refund
GET
{{env_url}}/nucleus/refund/status/{{txRef}}/v2
Headers
Content-Type
application/json
x-auth-token
Your merchant public key
Response
{
"message": "success",
"error": null,
"data": [
{
"refundType": "full",
"txRef": "txRef",
"refundTnxId": null,
"businessId": 133,
"refundedAmount": null,
"status": "pending"
}
]
}
Generate a bearer token
Token GenerationExchange rate
POST
{{env_url}}/nucleus/general/exchange/
Make a POST call to the exchange rate API.
Headers
Content-Type
application/json
Authorization
Bearer "token"
Request Body
sourceCurrency
currency users will pay in
amount
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
}
}
Last updated