Overview

Live Endpoint         
=> To be shared by Kyanda Team.
                

Kyanda API merchant service is engineered to create simple APIs that perform multiple complex functions. From a single payment APIs that make payments to mobile wallets, banks and cards to single Utility Vending that allows Bill Payments across multiple Telco’s and multiple digital service providers.

Account API

Manage your API Account.

Authentication and Authorization

Standard Request Headers

The standard request headers needed when authenticating with the API:

Field
Description
Content-Type The content type of the payload: application/json
apiKey This Key is generated upon registration.

API Account

i. Check Account Balance

This Request fetches the Available Account Balances in the Payment and Billing platform.

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters:

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields with the following order: MerchantID The resulting string is then signed with the Key Provided upon registration.

Example Request:

POST /billing/v1/account-balance HTTP/1.1
 Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
"signature":"b916c162f49856f2bc897c43bcf62d48705bbe3f3397c075403f9f"
}

Sample Response:

{
"Account_Bal": 399930,
"Earnings_Bal": 1586.6
} 
        

For possible errors and solutions, refer to the Error Section.

ii. Check Transaction Status.

This is a quick way to check whether the status of the Pending transaction.

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters:

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
transactionRef This is the Merchant reference returned after a request has been posted on the payment and Billing platform.
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields with the following order:MerchantID+ transactionRef The resulting string is then signed with the Key Provided upon registration.

                Example Request:

POST /billing/v1/transaction-check HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
"transactionRef":"kyanda-API1089772",
"signature":"51d8864a2890e73e3254ddd84968d17583f7a1a0efb66ec8fe3138a893b0e253"
}

Sample Response:
{
“status”:”200”,
“details”: {
“category”: ”BankPayout”,
“source”: “PaymentWallet”,
“destination”: “2042581154”,
“MerchantID”: “kyanda”,
“details”: {},
“requestMetadata”: {},
“status”: “Success”,
“transactionDate”: “23-05-2021 10:29 pm”,
“transactionFee”: “50”,
“transactionRef”: “KYAAPI_____”,
“amount”: “1500”
},
}
            

For possible errors and solutions, refer to the Error Section

Payment API

Payment Collection, Bank & Mobile Wallet Payout.

a. Mobile Wallet Payout API

This API allows you to send payments from your Payment Wallet to mobile subscribers with the following Mobile Wallet Channels available in Kenya.
1. MPESA.
2. AIRTEL MONEY.
3. EQUITEL.

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
initiatorName The First and Last Name of the Initiator in one string. ie John Doe
initiatorCountry The country the initiator is currently based in. ie. Germany
destinationPhone Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg 0715330000
amount Amount that the recipient is expected to receive. ie 1500
channel The channel the payment will be made from. It can either be the following: MPESA, AIRTEL, EQUITEL
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields. In this case, use the following order:

amount+phone+InitiatorName+InitiatorCountry+channel+MerchantID

Example Concatenated String: 15000715330000John DoeGermanyMPESAkyanda The resulting string is then signed with the Security Key provided/generated upon registration.
Sample Signature generated from the above Concatenated String: 9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6

                Example Request:

POST /billing/v1/mobile-payout/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
"source":{
"initiatorName":"John Doe",
"initiatorCountry": "Germany"
},
"destination":{
"destinationPhone":"0715330000",
"amount": "1500",
"channel":"MPESA"
},
"signature":"9447d0ea436cdddd75614c212b9db6f57d79b6"
}

Sample Response
{
"status": "Pending",
"status_code": "200",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Request accepted for processing!"
}
            

For possible errors and solutions, refer to the Error section.

b. Bank Payout API

This API allows transfer of funds from your Payment wallet to Bank accounts within Kenya.

Request Parameter:

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters:

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
initiatorName The First and Last Name of the Initiator in one string. ie John Doe
initiatorCountry The country the initiator is currently based in. ie. Germany
name The First and Last Name of the associated with the Bank Account in one string. eg Harry Kessy
accountNumber Bank Account Number. eg 2042581154
phoneNumber Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg 0715330000
amount Amount that the recipient is expected to receive. ie 1500
bankCode 3-Digit code for the Bank, well listed in the Bank Codes Section below. eg 101
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields. In this case, use the following order:

amount+accountNumber+phoneNumber+bankCode+InitiatorName+Initiator Country+MerchantID

Example Concatenated String: 150020425811540715330000101John DoeGermanykyanda
The resulting string is then signed with the Security Key provided/generated upon registration.

Sample Signature generated from the above Concatenated String: 9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6

                Example Request

POST /billing/v1/bank-payout/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
"source":{
"initiatorName":"John Doe",
"initiatorCountry": "Germany"
},
"destination":{
"name":"Harry Kessy",
"accountNumber":"2042581154",
"phoneNumber":"0715330000",
"amount": "1500",
"bankCode":"101"
},
"signature":"d1c574dfa94e43f77f6d0c18d48c809466a8fde21fa6886ba2480d4952871d8f"
}

Sample Response
{
"status": "Pending",
"status_code": "200",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Request accepted for processing!"
}
            

For possible errors and solutions, refer to the Error Section.

c. Payment Collection API

i. Mobile Checkout

Mobile checkout API allows you to initiate a Consumer to Business transaction on a Mobile subscriber’s device. Once initiated, the Subscriber will only need to authorize the payment.

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters:

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
phoneNumber Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg 0715330000
amount Amount that the recipient is expected to receive. eg 1500
channel The channel the payment will be made from. It can either be the following: MPESA, AIRTEL, EQUITEL
metadata -A map of any metadata you would like us to associate with the request. You can use this field to pass Account details, Payment reasons, or any other details that will assist to process the payment. -It will be included in the Instant Payment Notification once the subscriber completes the mobile checkout request.
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields.In this case, use the following order:

amount+phoneNumber+channel+MerchantID

Example Concatenated String: 15000715330000MPESAkyanda
The resulting string is then signed with the Security Key provided/generated upon registration.

Sample Signature generated from the above Concatenated String: 9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6

         Example Request

POST /billing/v1/checkout/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
“phoneNumber”:”0715330000,
“amount”:”1500”,
“channel”:”MPESA”,
"metadata":{
"abc":"balloon"
},
"signature":"d1c574dfa94e43f77f6d0c18d48c809466a8fde21fa6886ba2480d4952871d8f"
}

Sample Response
{
"status": "Pending",
"status_code": "200",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Request accepted for processing!"
}
            

For possible errors and solutions, refer to the Error Section.

ii. Consumer to Business

Mobile Consumer to Business (C2B) functionality allows your application to receive payments that are initiated by the Mobile subscriber using their own Mobile Device.

To receive payments through this functionality, you will need to display the following to the Mobile subscriber:
1. Paybill Number - Kyanda will assign this paybill upon registration.
2. Account Number - The Account number will be your Merchant ID, which is mapped to your account, the same will be assigned upon registration.

Once the Mobile subscriber completes the payment, we will send you an Instant Payment Notification to your Callback URL with the Payment details.

Utility API

Vend Utility services through your Platform.

b. Airtime API

This API allows the disbursement of Pinless Airtime from your Payment Wallet to Mobile subscribers with the following networks.
1. SAFARICOM.
2. AIRTEL.
3. TELKOM.
4. EQUITEL.
5. FAIBA.
6. FAIBA BUNDLES.

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
phone Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg 0715330000
amount Amount that the recipient is expected to receive. ie 1500
telco The destination telco. It can either be the following: SAFARICOM, AIRTEL, TELKOM, EQUITEL, FAIBA & FAIBA_B
initiatorPhone This is the initiator’s Phone number attached along the transaction for record purposes.
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields.

In this case, use the following order:

amount+phone+telco+initiatorPhone+MerchantID

Example Concatenated String:
15000715330000SAFARICOM0715330000kyanda

The resulting string is then signed with the Security Key provided/generated upon registration.

Sample Signature generated from the above Concatenated String: 092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428

                Example Request

POST /billing/v1/airtime/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
"phone":"0715330000",
"amount":"1500",
"telco": "SAFARICOM",
"initiatorPhone":"0715330000",
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}

Sample Response
{
"status": "Success",
"status_code": "0000",
"transactionId": "KYAAPI165394",
"transactiontxt": "Your request has been posted successfully!"
}
            

For possible errors and solutions, refer to the Error Section.

FAIBA BUNDLES PRICING:

BUNDLE AMOUNT
Daily DataBundle 1GB 50
Weekly DataBundle 8GB 300
Weekly DataBundle 15GB 500
Monthly DataBundle 25GB 1000
Monthly DataBundle 40GB 2000
Monthly DataBundle 70GB 3000

c. Pay Bill API

This API allows supports the following Service Providers:
1. Kenya Power (Both Prepaid and Postpaid)
2. Tv Subscriptions (DSTV, GOTV, ZUKU, STARTIMES)
3. Water Service.

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters:

Field
Description
MerchantID This identifies the Merchant making use of the Payment and Billing platform.
account Account Number. Eg 0123456789
amount Amount that the recipient is expected to receive. ie 1500
telco The destination telco. The channels codes are attached below.
initiatorPhone This is the initiator’s Phone number attached along the transaction for record purposes.
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields.

In this case, use the following order:
amount+account+telco+initiatorPhone+MerchantID

Example Concatenated String:
1500012345678DSTV0715330000kyanda

The resulting string is then signed with the Security Key provided/generated upon registration.

Sample Signature generated from the above Concatenated String: 092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428

                Example Request
POST /billing/v1/bill/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
"account":"012345678",
"amount":"1500",
"telco": "DSTV",
"initiatorPhone":"0715330000",
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}

Sample Response
{
"status": "Success",
"status_code": "0000",
"transactionId": "KYAAPI165394",
"transactiontxt": "Your request has been posted successfully!"
}
            

For possible errors and solutions, refer to the Error Section.

DESTINATION CHANNEL CODES:

TELCO CHANNEL CODE
Kenya Power KPLC_PREPAID | KPLC_POSTPAID
Tv Subscription GOTV | DSTV | ZUKU | STARTIMES
Water Service NAIROBI_WTR

Instant Payment Notification

A notification is information sent to your application whenever we need to let you know that something/change has occurred. For instance, when a payment has been initiated, the request is pending. Once the payment is fully executed, we immediately send you the details of the transaction as POST variables to the callback URL you set on your Application for a given product.

The Callback URL can be registered in two ways:
1. Through API settings on the Kyanda Merchant Dashboard.
2. Through the API endpoint.

NB: Once the endpoint is registered, no further changes can be made using this endpoint. In case one needs the callback changed, engage our Support team for assistance.

Callback URL Registration.

This request enables the registration of the Callback URL

Request Parameters

In addition to the Standard request headers, the body of the request should contain the following fields:

Body Parameters:

Field
Description
MerchantID In addition to the Standard request headers, the body of the request should contain the following fields:
callbackURL HTTPS callback URL
signature A SHA-256 signature to proof that the request is coming from the Merchant. Build a string of concatenated values of the request fields with the following order: MerchantID The resulting string is then signed with the Key Provided upon registration.

                Example Request

POST /billing/v1/callback-url/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json

{
"MerchantID":"kyanda",
“callbackURL”:”https://website.com/callback”,
"signature":"d1c574dfa94e43f77f6d0c18d48c809466a8fde21fa6886ba2480d4952871d8f"
}

Sample Response
{
"status": "Success",
"status_code": "0000",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Callback Updated!"
}
            

For possible errors and solutions, refer to the Error Section.

Sample Instant Payment Notification.(IPN)
{
“category”: ”UtilityPayment”,
“source”: “PaymentWallet”,
“destination”: “0715330000”,
“MerchantID”: “kyanda”,
“details”: { biller_receiptNo: 0105781244210},
“status”: “Success”,
“status_code”:”0000”,
“message”:”Your Request has been processed successfully.”,
“transactionDate”: “20210401091002”,
“transactionRef”: “KYAAPI_______”,
“amount”: “1500”
}


            




Once you receive the IPN, you will be expected to send back a JSON response that confirms that you have received the IPN. Ensure to respond with status 200 and the below JSON body.

{
“status”:success”
}

Appendix

Errors and Possible solutions

Standard Errors across the platform.

CODE
DESCRIPTION
0000 Request processed sucessfully.
1100 Transaction created and pending processing.
1101 Invalid Merchant ID.
1102 Authentication failed.
1103 Forbidden access.
1104 Signature Mismatch.
1105 Payment services unavailable.
1106 Airtime Service unavailable.
1107 Insufficient float balance.
1108 Missing parameter.
1109 Parameter validation error.
5000 Unexpected error has occurred.

Airtime Service errors.

CODE
DESCRIPTION
9001 Invalid phone number format.
9002 Invalid transaction channel.
9003 Invalid amount format.
9004 Amount limit exceeded.
9005 Duplicate transmission

Pay Bill errors

CODE
DESCRIPTION
8001 Invalid account number format.
8002 Invalid phone number format.
8003 Invalid Telco.
8004 Invalid amount format.
8005 Amount limit exceeded.
8006 Duplicate transmission.

Callback Registration API errors

CODE
DESCRIPTION
6001 Cannot register the URL.
6002 Invalid URL format.

Account: Check Transaction.

CODE
DESCRIPTION
7001 Transaction not found.