#KongaPay-Web-SDK
The KongaPay Web Plugin is designed for use on the web. This plugin allow merchants to receive payments from a KongaPay user. This plugin will be implemented using HTML and Javascript.
####Requirements
- Merchant must be signed up as a Merchant on KongaPay. If you are yet to sign up, send an email to [email protected] to come onboard.
- KongaPay will provide the Merchant with Merchant ID and Client Secret (To be kept secretly by merchant).
- Merchant can provide a logo to be displayed alongside Merchant name. The image should be saved using merchant ID as name and should be either .jpg or .png format
- Implement web plugin on websites, android SDK on android app and iOS SDK on iOS app.
###How to Implement KongaPay Payment Web Plugin. (PART 1)
On the page where the Merchant wants to receive payment the link to the Javascript file is to be added on the page. It is preferable to have it close to the javascript object.
Sample:
Test Environment: <script src="https://sandbox.kongapay.com/plugins/web-plugin/js/kpay-sand.min.js"></script>
Production Environment: <script src="https://www.kongapay.com/plugins/web-plugin/js/kpay.min.js"></script>
Javascript object is to built for the transaction.
Sample Script:
<script>
new KongaPay({
id: "{button_container_id}" //optional
merchantId: "{merchant_id}",
merchantName: "{merchant_name}",
phone:"{customer_phone}", //optional
callBack: "{callback_url}",
amount: "{amount}",
transactionReference: “{transaction_reference}” ,
buttonSize: 140,
description : “{description}”, //optional
});
</script>
#####OPTIONS Definition: buttonSize : specifies the size, in pixels, of the KongPay button you’ll want to appear on your site. It defaults to 140px if not provided. Integer (optional).
id: id of container to show the KongaPay button (can be used if you want to create multiple buttons on one page). If you are not passing an ID, then your container ID should be "kpay-pay-component".
merchantId: Your KongaPay merchant_id provided by KongaPay. String (Maximum of 15 characters)
merchantName: Your Company Name as you want it to appear on the Popup. String (Maximum of 20 characters).
callBack: The return url that will receive response after completed payment action. String (Maximum of 100 characters).
amount: The payable amount for the transaction in naira and kobo. Example 2005.45 will be read as Two Thousand Naira Forty Five Kobo. String (Maximum of 10 characters)
transactionReference: Unique transaction reference per transaction. This should always be different for every instance. String (Maximum of 32 characters)
description: A short description of the transaction. Optional. String (Maximum of 30 characters)
Add <div id="button_container_id"></div> where you want KongaPay button to appear. This will add a ‘Pay With KongaPay button as seen in this image http://take.ms/246jD.
When a user clicks on the Pay with KongaPay button a popup is displayed where the customer enters his/her phone number linked to KongaPay. http://take.ms/yBLDD. The user will enter his phone number and click on login.
On successful login, the user will be taken to a page where he/she is to enter the One Time Password and KongaPay Pin to authorize payment. http://take.ms/CoBFJ. On click of Pay Amount, transaction will be processed.
Response is sent to the callback set on the javascript object. Parameters of the response can be fetched using GET.
status : Status of the transaction. Expected ‘success’ or ‘error’.
payment_reference: KongaPay Payment reference to be used to identify the payment. String (Maximum of 32 characters)
transaction_reference: Unique transaction reference supplied by the merchant during payment.
comment: Is returned when there is an error. Short description of why an error occurred. String.
Important Note! Before returning a success page to the user, you need to make a requery(as described in part 3) and compare amount paid with amount expected. Only return a success if this is true.
On the page where the Merchant wants the customer to link his/her KongaPay Account a Javascript file is to be added on the page. It is preferable to have it close to the javascript object.
Sample:
Test Environment: <script src="https://sandbox.kongapay.com/plugins/web-plugin/js/kpay-link-sand.min.js"></script>
Production Environment: <script src="https://www.kongapay.com/plugins/web-plugin/js/kpayLink.min.js"></script>
Create Javascript Object Javascript object is to built for the transaction.
Sample Script:
<script>
new KongaPayLink({
id: "{button_container_id}" //optional
merchantId: "{merchant_id}",
merchantName: "{merchant_name}",
phone:"{customer_phone}" //optional
callBack: "{callback_url}",
buttonSize: 140,
description : “{description}”
});
</script>
######OPTIONS Definition: buttonSize : specifies the size, in pixels, of the KongPay button you’ll want to appear on your site. It defaults to 140px if not provided. Integer (optional).
id: id of container to show the KongaPay button
merchantId: Your KongaPay merchant_id provided by KongaPay. String (Maximum of 15 characters)
merchantName: Your Company Name as you want it to appear on the Popup. String (Maximum of 20 characters).
callBack: The return url that will receive response after completed payment action. String (Maximum of 100 characters).
description: A short description of the transaction. String (Maximum of 30 characters)
Add <div id="button_container_id"></div> where you want KongaPay button to appear. This will add an “Authorize KongaPay” button as seen in this image. http://take.ms/cf81C.
When a user clicks on the Authorize KongaPay button a popup is displayed where the customer enters his/her phone number linked to KongaPay. http://take.ms/L3OmO. The user will enter his phone number and click on login.
On successful login the user will be taken to a page where he/she is to enter the One Time Password and KongaPay Pin to authorize his/her account. http://take.ms/qoKU2. On click of Authorize, transaction will be processed.
Response is sent to the callback set on the javascript object. Parameters of the response can be fetched using GET. Expected parameters from the response:
status : Status of the transaction. Expected ‘success’ or ‘error’.
token: Generated token for debiting the customer. This will be used by Merchant to debit the customer. String (Maximum of 150 characters) comment: Is returned when there is an error. Short description of why an error occurred. String.
All requests to KongaPay requires an Access Token. To generate an Access Token, KongaPay is to provide the merchant with both Merchant ID and Client Secret.
######Definition of parameters:
- merchant_id - Merchant Id provided by KongaPay. String (Maximum of 15 characters)
- client_secret - Client Secret provided by KongaPay. This should be kept securely by the Merchant. String (Maximum of 30 characters)
- access_code - Access Code is generated by a GET request to the Auth server. Access code is required to generate Access Token. It expires after 30 seconds. String (Maximum of 128 characters)
- access_token - Access Token is required to make any request to KongaPay. It expires after 6 hours. String (Maximum of 128 characters)
- refresh_token - Refresh Token can be used to get a new Access Token after the expiration of the Access Token. It expires after 14 days. String (Maximum of 128 characters)
#####OAuth 2.0 Authentication This follows the standard OAuth 2.0 flow where:
- Client requests an access code
- KongaPay returns the access code on success of step 1 request
- Client uses the access code to request access token
- KongaPay returns the access token and refresh token on success of step 3 request
- Client then uses the access token to request resources from the server.
######Base URL for OAuth:
Sandbox Environment - https://staging-auth.kongapay.com
Live Environment - https://auth.kongapay.com
Step I
To request for an access code
URL: {{oauth_base_url}}/authorize?response_type=code&client_id={merchant_id}&state=alive
Request Type: GET
Step II
Success Message:
{
"status": "success",
"data": {
"code": "{access_code}"
}
}
Error message:
{
"error": "invalid_client",
"error_description": "The client id supplied is invalid"
}
Step III
Use access code to request token
URL: {{oauth_base_url}}/token
Request Type: POST (application/json)
Parameters:
grant_type = authorization_code
code = {access_code} (the code returned from Step II)
client_id = {merchant_id}
client_secret = {client_secret}
Step IV
Success Message to Step III
{
"access_token": "{access_token}",
"expires_in": 21600,
"token_type": "Bearer",
"scope": null,
"refresh_token": “{refresh_token}”
}
Error Message
{
"error": "invalid_grant",
"error_description": "Authorization code doesn't exist or is invalid for the client"
}
Step V-a
Using refresh token to get another get another access token
URL: {{oauth_base_url}}/token
Request Type: POST
Receives a form-data post with the following parameters
grant_type = refresh_token
refresh_token = “{refresh_token}” (the refresh token returned from step 2)
client_id = “{merchant_id}”
client_secret = “{client_id}”
Step V-b
Server returns another token.
{
"access_token": “{access_token}”,
"expires_in": 21600,
"token_type": "Bearer",
"scope": null
}
######NOTE: Token/code expiration The access token expires after 6 hours. Once the access token expires, the refresh token can be used to request for another token which will last for another 6 hours. However, refresh token expires after 14 days. Once the refresh token expires, the client needs to request another access code which will kick-start the flow again from the beginning.
Access code expires 30 secs after it was requested which means the access code must have been used to request a token within 30 secs.
###Debiting a KongaPay Linked Account with a Token (PART 4)
This allows Merchants to debit a linked KongaPay Account using the Payment Token provided by KongaPay.
######Base URL for KongaPay:
SandBox Environment - https://api-sandbox.kongapay.com/v3/
Live Environment - https://api.kongapay.com
- merchant_id - Merchant Id provided by KongaPay. String (Maximum of 15).
- access_token - Access Token is required to make any request to KongaPay. It expires after 6 hours. String (Maximum of 128 characters).
- payment_reference - Unique payment reference to be provided by the Merchant. String (Maximum of 32 characters).
- token - Payment Token provided by KongaPay after successful linking of KongaPay account to Merchant’s account either via SDK or web. String (Maximum of 150 characters).
- amount - Amount to be debited in Naira.Kobo. Example 2005.45 will be read as Two Thousand Naira Forty Five Kobo. String (Maximum of 10 characters).
- currency_code - The Currency code of the transaction. Only Naira (566) accepted for now. String (Maximum of 3 characters).
- status - Status of the transaction. Expected “success” or “error”.
- transaction_reference - Transaction Reference supplied by KongaPay after a successful transaction. String (Maximum of 20 characters).
- error_message - Error message sent back from KongaPay when an error occurs. String (Maximum of 1000 characters).
- error_code - Error code sent back from KongaPay when an error occurs. String (Maximum of 5 characters).
Access token from Part 3 above is required to make payment using Payment Token.
Endpoint: {{kongapay_base_url}}/payments/wallet/merchant/{merchant_id}/pay?access_token={access_token}
Request:
Request Type: POST
Receives a JSON payload in the following format:
{
"payment_reference": "{payment_reference}",
"token": "{token}",
"amount": "{amount}",
"currency_code": "566"
}
Successful Response:
{
"status": "success",
"data": {
"transaction_reference": "{transaction_reference}"
}
}
Error response:
{
"status": "error",
"message": “{error_message}”,
"code": “{error_code}”
}
####Requerying KongaPay Payments (PART 5)
Merchants can always requery transactions made using KongaPay. This part of the documentation will help with how this can be achieved.
This allow Merchants to requery a KongaPay transaction using the payment_reference used in making payment.
######Base URL for KongaPay:
Sandbox Environment - https://api-sandbox.kongapay.com/v3
Live Environment - https://api.kongapay.com/v3
Definition of parameters:
- merchant_id - Merchant Id provided by KongaPay. String (Maximum of 15).
- access_token - Access Token is required to make any request to KongaPay. It expires after 6 hours. String (Maximum of 128 characters).
- transaction_reference - Unique transaction reference to be provided by the Merchant. String (Maximum of 32 characters).
- amount - Amount to be debited in Naira.Kobo. Example 2005.45 will be read as Two Thousand Naira Forty Five Kobo. String (Maximum of 10 characters).
- currency_code - The Currency code of the transaction. Only Naira (566) accepted for now. String (Maximum of 3 characters).
- status - Status of the transaction. Expected “success” or “error”.
- payment_reference - Payment Reference supplied by KongaPay after a successful transaction. String (Maximum of 20 characters).
- response_code - Check Response Codes and Description below.
- error_message - Error message sent back from KongaPay when an error occurs. String (Maximum of 1000 characters).
- error_code - Error code sent back from KongaPay when an error occurs. String (Maximum of 5 characters).
Access Token (access_token) from Part 3 above is required to requery Transactions.
Endpoint:
{{kongapay_base_url}}/payments/wallet/merchant/{merchant_id}/payment/{transaction_reference}?access_token={access_token}
Request:
Request Type: GET
Successful Response:
{
"status": "success",
"data": {
"payment_reference": "{payment_reference}",
"amount": "{amount}",
"response_code": "{response_code}",
"currency_code": "566",
"transaction_reference": "{transaction_reference}"
"type": "incoming",
"transaction_date": "2016-02-29 14:02:30"
}
}
#####Response Codes and Description
K00 - Success
K01 - Insufficient funds
K02 - Transaction not found
K03 - Fail
It is important to do this before returning a success page if the amount paid equals amount expected
#UPDATES
###October 10, 2016
To ensure a more secure solution we have update KongaPay Web Plugin to include a hash value as part of the payload.
Test Environment: <script src="https://sandbox.kongapay.com/plugins/web-plugin/js/v2/kpay-sand.min.js"></script>
Production Environment: <script src="https://www.kongapay.com/plugins/web-plugin/js/v2/kpay.min.js"></script>
Sample Script:
<script>
new KongaPay({
id: "{button_container_id}" //optional
merchantId: "{merchant_id}",
merchantName: "{merchant_name}",
phone:"{customer_phone}", //optional
callBack: "{callback_url}",
amount: "{amount}",
transactionReference: “{transaction_reference}” ,
buttonSize: {button_size}, //default 140
description : “{description}”, //optional
hash: {hashValue} (NEW)
});
</script>
#####NEW OPTION Definition:
hash: hash_hmac('SHA512', {amount} '#'{transactionReference}'#'{merchant_id}, {secret_key})