Login
This is the gateway to use the automated settlement service by Kuda.
Partners will be granted access through the Kuda back office channel.
Here, the user authenticates themself on the system.
POST
https://partners-uat.kudabank.com/api/Auth/authenticate
Body Parameters
secretKey
|
string
|
Required
This is your authentication password
clientID
|
string
|
Required
Your User ID sent to you by Kuda
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"secretKey": "MyPassword",
"clientID": "myUserName"
}Response
{
"isSuccessful": true,
"message": "Success",
"data": {
"auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IJtaW5hbC9D"
}
}Create a Terminal
This endpoint will give a partner the ability to add certain parameters to a
POS device to anchor routing communications between the processor and
the Kuda settlement system.
POST
https://partners-uat.kudabank.com /api/terminal/api/terminal/createterminal
Body Parameters
terminalId
|
string
|
Required
The terminal identifier
merchantId
|
string
|
Required
The merchant identifier
kudaAccountNumber
|
string
|
Required
The clients Kuda account number
serialNumber
|
string
|
Required
The serial number
isReceivingPayment
|
boolean
|
Required
Set true for receiving payment and false for not.
isActive
|
boolean
|
Required
Set true for receiving payment and false for not.
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Information
The TIDs are identifiers provided by Kuda. This must be parsed alongside other parameters to route transactions through Kuda for processing and payouts
Sample Request
JSON
Copy
{
"terminalId": "apple",
"merchantId": "Oshogbo",
"kudaAccountNumber":"2000983443",
"serialNumber":"KENDAL",
"isReceivingPayment": true,
"isActive": true
} Response
{
"status": true,
"message": "Terminal Added Successfully.",
"data": {
"id": 17
}
}Edit Terminal
From time to time, a partner will want to swap the location and user of a
POS device. We are giving them a self service option to do this on the fly.
POST
https://partners-uat.kudabank.com/api/terminal/EditTerminal
Body Parameters
id
|
string
|
Required
The terminal identifier
kudaMerchantId
|
string
|
Required
The clients Kuda merchant identifier
terminalID
|
string
|
Required
The terminal unique identifier
kudaAccountNumber
|
string
|
Required
The clients Kuda account number
kudaAccountName
|
string
|
Required
The clients account name
serialNumber
|
string
|
Required
The serial number
isReceivingPayment
|
boolean
|
Required
Set true for receiving payment and false for not.
isActive
|
boolean
|
Required
Set true for receiving payment and false for not.
feePercentage
|
string
|
Required
Fee percentage
dateCreated
|
string
|
Required
Date terminal was created
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Note
While updating your terminal, the fee charge will always remain constant and cannot be changed via the API as it is a back office operation and will require someone with privileges.
Sample Request
JSON
Copy
{
"id": "7",
"KudMerchantId": "2",
"termialID": "20452LLXD",
"kudaAccountNumber":"2000983443",
"kudaAccountName":"Ibrahim Jimoh",
"serialNumber":"KENDAL",
"isActive": true,
"isReceivingPayment": true,
"dateCreated": "2021-05-09T04:55:38:5536343"
} Response
{
"status": true,
"message": "Terminal Updated Successfully.",
"data": {
"id": 17
}
}Retrieve Merchant Terminals
This endpoint allows a user to get all merchants and the terminals assigned
to them.
When used, a user can retrieve terminals tied to agent accounts using
specific API parameters. As the size of your business grows, it is pertinent to
know how your terminals are being used. Retrieving these terminals will
help.
GET
https://partners-uat.kudabank.com/RetrieveMerchantTerminals
Body Parameters
pageSize
|
string
|
Required
Number of terminals the request should return
pageNumber
|
string
|
Required
Number of pages for result
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"pageSize": "7",
"pageNumber": "2"
} Response
{
"status": true,
"message": "successfully retrieved terminals.",
"data": [
{
"id": 11,
"kudaMerchantId": 4,
"terminalId": "20201201",
"merchantId": "009100",
"kudaAccountNumber": "1100348870",
"kudaAccountName": "OLUGBENGA GABRIEL OJE",
"serialNumber": "",
"isActive": true,
"isReceivingPayment": true,
"feePercentage": 10.00,
"dateCreated": "2021-05-09T16:45:31.5010329"
},
{
"id": 15,
"kudaMerchantId": 4,
"terminalId": "00017",
"merchantId": "12O122",
"kudaAccountNumber": "2000378756",
"kudaAccountName": "James Amadi157",
"serialNumber": "Oshey msan",
"isActive": true,
"isReceivingPayment": true,
"feePercentage": 10.00,
"dateCreated": "2021-05-09T16:54:21.6203051"
},
{
"id": 17,
"kudaMerchantId": 4,
"terminalId": "6377",
"merchantId": "6235",
"kudaAccountNumber": "2000379124",
"kudaAccountName": "James Amadi158",
"serialNumber": "20",
"isActive": true,
"isReceivingPayment": true,
"feePercentage": 20.00,
"dateCreated": "2021-05-10T08:43:44.4111139"
}
],
"totalCount": 3,
"hasNextPage": false,
"currentPage": 1
}Settlement Status
The settlement status endpoint, provides and insight on the status of a
particular/all settlements for a terminal.
Get the status of a transaction needing settlement. This is used for dispute
resolution.
GET
https://partners-uat.kudabank.com/api/terminal/settlementstatus
Body Parameters
transactionId
|
string
|
Required
The transaction reference number or unique identifier.
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"transactionId": "ikshsj-sdssd"
} Response
{
"status": true,
"message": "Successfully retrieved transaction",
"data": {
"id": 11,
"kudaTerminalId": 15,
"terminalId": "00017",
"kudaAccountNumber": "2000378756",
"amount": 10000.00,
"amountSettled": 9000.00,
"feePercentage": 10.00,
"isPaid": false,
"datePaid": "0001-01-01T00:00:00",
"transactionId": "c12345678",
"kudaRefId": "67pYmHvDQuhr",
"reason": null,
"timeReceived": "2021-05-09T17:45:10.210989",
"responseCode": null,
"responseMessage": null
}
}Log Transaction
For complete transaction fulfilment, a user will query this endpoint with the
transaction amount that needs to be fulfilled. This way, the terminal
management system is updated with the transaction status in real-time and
completes settlement to the specified user's account.
This request logs a transaction. Logging a transaction sends a notification to
Kuda which triggers instant settlement
POST
https://partners-uat.kudabank.com/api/terminal/logtransaction
Body Parameters
amount
|
string
|
Required
Transaction amount in Naira
transactionId
|
string
|
Required
The transaction reference number or unique identifier.
terminalId
|
string
|
Required
The terminal unique identifier
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"amount":"3000",
"transactionId": "ikshsj-sdssd",
"terminalId":"2044LXD"
} Response
{
"status": true,
"message": "Transaction logged Successfully.",
"data": null
}Search Transactions
This method allows a user to do back office operations while searching for
transactions disputes.
GET
https://partners-uat.kudabank.com/api/terminal/searchtransaction
Body Parameters
terminalId
|
string
|
Required
The terminal unique identifier
dateFrom
|
string
|
Required
The start date
dateTo
|
string
|
Required
The end date
pageSize
|
string
|
Required
Number of transaction items to return
pageNumber
|
string
|
Required
Number of result page
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"terminalId": "7",
"dateFrom":"2021-05-11",
"dateTo":"2021-05-11",
"pageSize": "10",
"pageNumber": "1"
} Response
{
"status": true,
"message": "successfully retrieved terminals transactions.",
"data": [
{
"id": 11,
"kudaTerminalId": 15,
"terminalId": "00017",
"kudaAccountNumber": "2000378756",
"amount": 10000.00,
"amountSettled": 9000.00,
"feePercentage": 10.00,
"isPaid": false,
"datePaid": "0001-01-01T00:00:00",
"transactionId": "c12345678",
"kudaRefId": "67pYmHvDQuhr",
"reason": null,
"timeReceived": "2021-05-09T17:45:10.210989",
"responseCode": null,
"responseMessage": null
}
],
"totalCount": 1,
"hasNextPage": false,
"currentPage": 1
}