Business API Documentation

Account Transactions

The NIBSS Instant Payments (NIP) is an account-number-based, online-real-time Inter-Bank payment solution
developed by the Nigerian Interbank Settlement System (NIBSS). Bank transfers via the Kuda API are routed
through this fund transfer platform.

With the Single Fund Transfer service, you can programmatically move money from a bank account you own to
another bank account via these rails. To send money to another bank account, there are four steps to follow:

Get the list of available banks you can transfer to.
Confirm the recipient of the transfer
Transfer money to the aforementioned recipient
Confirm the status of the transfer

Note

All transaction amount are in Kobo. (For example, 10020 is 100 Naira 20 Kobo)

Response Codes

KUDA transfer response codes combine the standard ISO response codes and codes unique to us. To view the
full list of ISO response codes, click HERE. (opens in a new tab)

Information

See Fund Transfer Codes for Kuda & Interbank (opens in a new tab)and response to get more information on your transaction request.

Initiate Transactions

Get bank List

This request gets all the bank list from NIPS, including all commercial banks,
Micro-Finance Banks (MFBs), and Mobile Money Operators (MMOs). The
Bank list NIP provides are for all Nigerian Financial Institutions supported by NIBSS

Note

Please note that in production, the list of banks and bank codes may change based on the responses gotten from NIBSS.

Body Parameters

serviceType

string

Required

Service type for this request is: BANK_LIST

requestRef

string

The unique reference identifier for this request

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
  "serviceType": "BANK_LIST",
  "requestRef": "36834et2ep4"
}

Response

{
    "message": "Completed Successfully",
    "status": true,
    "data": {
      "banks": [
        {
          "bankName": "9 Payment Service Bank (9PSB)",
          "bankCode": "120001",
          "bankAvailability": "100%",
          "bankStatus": "active"
        },
        {
          "bankName": "9jaPay MFB",
          "bankCode": "090629",
          "bankAvailability": "100%",
          "bankStatus": "active"
        },
      ]
    }
}

Check Admin Account Balance

This request gives you the account balance on your main account.
The service type for this request is
ADMIN_RETRIEVE_MAIN_ACCOUNT_BALANCE

Body Parameters

serviceType

string

Required

Service type for this request is:
ADMIN_RETRIEVE_MAIN_ACCOUNT_BALANCE

requestRef

string

Required

The unique reference identifier for this request

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
	 "serviceType": "ADMIN_RETRIEVE_MAIN_ACCOUNT_BALANCE",
	 "requestref": "foobar",
	 "data": {
		}
}

Response

{
	  "status": true,
		"message": "Operation successful",
		"data": {
			"LedgerBalance": 800000,
			"AvailableBalance": 800000,
			"WithdrawableBalance": 800000
		}
}

Check Collection Account Balance

The request fetches and returns your collection balance. You will need
to provide the service type RETRIEVE_COLLECTION_ACCOUNT_BALANCE and trackingReference (Collection account number).

Body Parameters

serviceType

string

Required

Service type for this request is:
RETRIEVE_COLLECTION_ACCOUNT_BALANCE

requestRef

string

Required

The unique reference identifier for this request

TrackingReference

string

Required

The tracking reference number tied to user’s static collection account

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
	 "serviceType": "RETRIEVE_COLLECTION_ACCOUNT_BALANCE",
	 "requestref": "foobar",
	 "data": {
			"TrackingReference": "1234"
		}
}

Response

{
	    "status": true,
			"message": "Operation successful",
			"data": {
				"LedgerBalance": 800000,
				"AvailableBalance": 800000,
				"WithdrawableBalance": 800000
			}
}

Confirm Transfer Recipient

(Name Enquiry)

The Name Enquiry service is a validation step that makes bank transfers
safer. By retrieving the information associated with supplied account details
both Main and collection account, the user can confirm the intended
beneficiary of the bank transfer.

Note

AccountStatus in response applies to Kuda accounts only. The field will be empty if the account is not a kuda account InActive = 1, Active = 2, Dormant = 3, Closed = 4
You should only carry out transactions on Active accounts.

Body Parameters

serviceType

string

Required

Service type for this request is: NAME_ENQUIRY

requestRef

string

Required

The unique reference identifier for this request

BeneficiaryAccountNumber

string

Required

Destination bank account number

BeneficiaryBankCode

string

Required

Destination bank code

SenderTrackingReference

string

Tracking reference of the collection account trying to do the actual transfer. Leave it empty if the intended transfer is going to be from the main account

IsRequestFromCollectionAccount

boolean

True or False value. If the intended transfer is to be made by the collection account

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
    "serviceType": "NAME_ENQUIRY",
    "requestRef": "611sad12dfw2qd2",
    "Data": {
        "BeneficiaryAccountNumber": "7000016172",
        "BeneficiaryBankCode": "999129"
    }
}

Response

{
    "message": "Request successful.",
    "status": true,
    "data": {
        "beneficiaryAccountNumber": "7000016172",
        "beneficiaryName": "Funmi Group",
        "senderAccountNumber": null,
        "senderName": null,
        "beneficiaryCustomerID": 0,
        "beneficiaryBankCode": "999129",
        "nameEnquiryID": 0,
        "responseCode": null,
        "transferCharge": 0,
        "sessionID": "NA",
        "accountStatus":"Active"
    }
}

Single Fund Transfer

The single_Fund_Transfer service programmatically sends money from your
main or collection Kuda account to another bank account.

Note

Please, do not use sensitive data while doing test transactions so as not to save it in your sandbox environment.

Body Parameters

serviceType

string

Required

Service type for this request are: SINGLE_FUND_TRANSFER

requestRef

string

Required

The unique reference identifier for this request

BeneficiaryAccount

string

Required

Destination bank account number

BeneficiaryBankCode

string

Required

Destination bank code

BeneficiaryName

string

Required

Name of the recipient

ClientAccountNumber

integer

Required

The ClientAccountNumber is the primary account of the business making the API call.

narration

string

Required

User defined reason for the transaction

NameEnquirySessionID

string

Required

Session ID generated from the nameEnquiry request

SenderName

string

You can add a custom sender name

ClientFeeCharge

integer

Add this parameter if you wish to charge customer for every transfer being carried out

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
    "serviceType": "SINGLE_FUND_TRANSFER",
     "requestRef": "{{$randomInt}}-Noll",
    "Data": {
      "BeneficiaryAccount": "2000355517",
      "beneficiaryBankCode": "999129",
      "amount": "3000",
      "ClientAccountNumber": "2504357961",
      "beneficiaryName": "DVA fund",
      "narration": "test DVA",
      "ClientFeeCharge":"20",//If you intend to charge your 
    //customers for  every transfer done with this endpoint,
    //add the charge amount here
      "SenderName" : "Custom Sender"//To add a custom
        //sender name
    }
}

Response

{
"RequestReference": "1234567890",
    "TransactionReference": "xqwerttyy",
	"ResponseCode": "00",
	"Status": true,
	"Message": "Transaction Successful.",
	"Data": null
}

Collection Account Funds Transfer

The COLLECTION_ACCOUNT_FUND_TRANSFER service programmatically sends money
from a collection account to another and any other Nigerian bank account.

Body Parameters

serviceType

string

Required

Service type for this request is:
COLLECTION_ACCOUNT_FUND_TRANSFER

requestRef

string

Required

The unique reference identifier for this request

trackingReference

string

Required

Unique identifier of the debit collection account

BeneficiaryAccount

string

Required

Destination bank account number

BeneficiaryBankCode

string

Required

Destination bank code

BeneficiaryName

string

Required

Name of the recipient

amount

integer

Required

Amount to be transferred

narration

string

Required

Transaction description

NameEnquirySessionID

string

Required

Session ID generated from the nameEnquiry request

SenderName

string

Required

Name of the person sending money

ClientFeeCharge

integer

Required

Add this parameter if you wish to charge customer for every transfer being carried out

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
    "serviceType": "COLLECTION_ACCOUNT_FUND_TRANSFER",
    "requestRef": "{{$randomInt}}-test",
    "Data": {
      "BeneficiaryAccount": "2000355517",
      "beneficiaryBankCode": "999129",
      "amount": "3000",
      "TrackingReference": "ttetedx123",// Unique Identifier
        // for the debit collection account
      "beneficiaryName": "DVA fund",
      "narration": "test DVA",
      "ClientFeeCharge": "20",// If you intend to charge
        // your customers for every transfer done with this
        // endpoint, add the charge amount here
      
      "SenderName": "Custom Sender" // To add a custom 
    // sender name
    }
}

Response

{
	"requestReference": "",
    "transactionReference": "FooBar",
    "responseCode": "00",
    "status": true,
    "message": "Transaction successful",
    "data": null
}

Fetch Transfer Instructions

This request will allow you search for transfer instructions and return the
status of the transaction.

Body Parameters

serviceType

string

Required

Service type for this request are:
SEARCH_FUND_TRANSFER_INSTRUCTION

requestRef

string

Required

The unique reference identifier for this request

AccountNumber

string

Required

The beneficiary’s account number

Reference

string

Required

This is unique identifier per record in the list

amount

integer

Required

Amount to be transferred

OriginalRequestRef

string

Required

This is the RequestRef used in logging the instruction

Status

string

Required

Options are: Pending, Processing, Successful, Failed

PageNumber

string

Required

Number of Pages

PageSize

string

Required

Number of Items per Page

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
		"serviceType":"SEARCH_FUND_TRANSFER_INSTRUCTION",
		"requestref":"FooBar",
		"data":
			{
				"AccountNumber":"2000355328", 
				"Reference":"1234568", 
				"Amount":"100", 
				"OriginalRequestRef":"2021080",
				"Status":"Pending", 
				"PageNumber":"1",
				"PageSize":"10"
			}
}

Response

{
	"Status":true,
	"Message":"Request successful.",
	"Data":{
		"Records":
			[{
			"RequestRef":"2021080",
			"AccountNumber":"2000355328",
			"AccountName":"Ajak Esit",
			"Amount":100,
			"BankCode":"999129",
			"BankName":"Kuda",
			"LongCode":"000011",
			"Reference":"1234568",
			"Narration":"Purchase of items",
			"CreationDate":"2022-06-07T11:25:13",
			"DateProcessed":"2022-06-11T07:26:00.7033333",
			"IsProcessed":false,
			"Status":"Pending",
			"Reason":"",
			"PaymentReference":""
			}],
		"RecordCount":1
	}
}

Add/Remove Money from Main Account

Fund Collection Account from Main Account

Collection account can be funded through deposits from the main account. To
fund a collection account you need to specify the trackingReference.

Body Parameters

serviceType

string

Required

Service type for this request are: COLLECTION_ACCOUNT_FUND_TRANSFER

requestRef

string

Required

The unique reference identifier for this request

amount

integer

Required

Amount to be transferred. All amounts in kobo

trackingReference

string

Required

Unique identifier of the debit collection account

narration

string

Required

Transfer description

clientFeeCharge

integer

Required

Add this parameter if you wish to charge customer for every transfer being carried out

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
  "serviceType": "FUND_COLLECTION_ACCOUNT",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "Narration": "From Main account To collection account",
    "Amount": "3000",
    "TrackingReference":"ttetedx123", 
    "narration": "test DVA",
    "ClientFeeCharge":"20" //If you intend to charge your 
    // customers for every transfer done with this,
    // endpoint add the charge amount here
  }
}

Response

{
    "requestReference": "13-test",
    "transactionReference": "231120324708",
    "instrumentNumber": null,
    "responseCode": "00",
    "status": true,
    "message": "Transaction successful",
    "data": null
}

Fund Main Account from Collection Account

This request lets you transfer funds from a collection account to the main
account. Once the process is complete, the new balance of collection account is
updated.

Body Parameters

serviceType

string

Required

Service type for this request are: WITHDRAW_COLLECTION_ACCOUNT

requestRef

string

Required

The unique reference identifier for this request

amount

integer

Required

Amount to be transferred. All amounts in kobo

trackingReference

string

Required

Unique identifier of the debit collection account

narration

string

Required

Transfer description

clientFeeCharge

integer

Required

Add this parameter if you wish to charge customer for every transfer being carried out

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
    "serviceType": "WITHDRAW_COLLECTION_ACCOUNT",
    "requestRef": "{{$randomInt}}-test",
    "Data": {
      "Narration": "To Main account from Collection account",
      "Amount": "3000",
      "TrackingReference":"ttetedx123", 
      "narration": "test DVA",
      "ClientFeeCharge":"20"  //If you intend to charge your 
    // customers for every transfer done with this,
    // endpoint add the charge amount here
    }
}

Response

{
    "requestReference": "13-test",
    "transactionReference": "231120324708",
    "instrumentNumber": null,
    "responseCode": "00",
    "status": true,
    "message": "Transaction successful",
    "data": null
}

Transaction Limit

Set Transaction Limit

This request aims to establish a limit for transactions on the collection/main
account.

Body Parameters

serviceType

string

Required

Service type for this request are:
Collection Account:
SET_COLLECTION_ACCOUNT_DAILY_INTERBANK_TRANSACTION_LIMIT
Main Account: SET_DAILY_INTERBANK_TRANSACTION_LIMIT

requestRef

string

Required

The unique reference identifier for this request

trackingReference

string

Unique identifier of the debit collection account

Limit

integer

Required

Set the transaction Limit for your main or collection account

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request: Collection Account

{
  "serviceType": "SET_COLLECTION_ACCOUNT_DAILY_INTERBANK_TRANSACTION_LIMIT",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "TrackingReference": "ttetedx123",
    "Limit":"2000000"
  }
}

Sample Request: Main Account

{
  "serviceType": "SET_DAILY_INTERBANK_TRANSACTION_LIMIT",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "Limit":"2000000"
    }
}

Response

{
  "message": "Your transfer limit has been successfully effected.",
  "status": true,
  "data": null
}

Fetch Transaction Limit

This request retrieves the current limit for transactions on the collection/main
account.

Body Parameters

serviceType

string

Required

Service type for this request are:
Collection Account:
RETRIEVE_COLLECTION_ACCOUNT_TRANSACTION_LIMIT
Main Account: RETRIEVE_TRANSACTION_LIMIT

requestRef

string

Required

The unique reference identifier for this request

trackingReference

string

Unique identifier of the debit collection account

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request: Collection Account

{
  "serviceType": "RETRIEVE_COLLECTION_ACCOUNT_TRANSACTION_LIMIT",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "TrackingReference": "ttetedx123"
  }
}

Sample Request: Main Account

{
  "serviceType": "RETRIEVE_TRANSACTION_LIMIT",
  "requestRef": "{{$randomInt}}-test",
  "Data": {}
}

Response

{
    "message": "Successful!",
    "status": true,
    "data": {
        "accountNumber": "2403465992",
        "createdOn": "0001-01-01T00:00:00",
        "lastUpdated": "0001-01-01T00:00:00",
        "totalDailyAllowedVolume": 1000000,
        "totalDailyCount": 1000,
        "totalDailyIntraTransferVolume": 1000000,
        "totalDailyInterTransferVolume": 1000000,
        "totalDailyIntraTransferCount": 1000,
        "totalDailyInterTransferCount": 1000
    }
}

Transaction History

Get Transaction Logs

You can retrieve all transactions your clients performed using this request.
In the event where you can not find a particular clients transaction, this service
fetches them from the logs.

Body Parameters

serviceType

string

Required

Service type for this request is: RETRIEVE_TRANSACTION_LOGS

requestRef

string

Required

The unique reference identifier for this request

RequestReference

string

Transaction request reference

ResponseReference

string

Transaction response reference

FetchSuccessfulRecords

boolean

If this is set to true, only successful transactions will be retrieved

TransactionDate

string

The transaction date

HasTransactionDateRangeFilter

boolean

Transaction response reference

StartDate

string

Transaction start date

EndDate

string

Transaction end date

PageSize

string

The number of listed transaction per page

PageNumber

string

The maximum number of result page

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{    
    "serviceType": "RETRIEVE_TRANSACTION_LOGS",
    "requestref": "foobar",
    "Data": {
      "RequestReference": "1234556",
      "ResponseReference": "dobj23jjsdn",
	    "TransactionDate":"2023-01-01",
      "HasTransactionDateRangeFilter": "",
      "StartDate": "2023-01-01",
      "EndDate": "2024-01-01",
      "PageSize": "10",
      "PageNumber": "1"
    }
  }

Response

{
	"Status": true,
	"Message": "Operation successful",
	"Data": {
	"TransferLogs":[
		{
			"RequestTime":"2020-10-27T09:58:23.4740446Z",
			"ResponseTime":"2020-10-27T09:58:23.4740446Z",
			"RequestRef":"1234567890",
			"ResponseRef": "dobj23jjsdn",
			"ResponseCode":"00",
			"BeneficiaryAccountNumber": "0000000000",
			"BeneficiaryBankCode": "999129",
			"Amount": 713960.0,
		    "serviceType": "RETRIEVE_TRANSACTION_LOGS",
			}
		]
	}
}

Fetch Incoming Account Transaction

This requests retrieves a list of all Kuda account incoming transactions for
the currently authenticated user.

Body Parameters

serviceType

string

Required

Service type for this request are:
Collection Account - ADMIN_COLLECTION_ACCOUNT_INFLOW
Main Account - ADMIN_ACCOUNT_INFLOW

requestRef

string

Required

The unique reference identifier for this request

TrackingReference

string

Unique Identifier for the customer’s account

StartDate

string

Transaction start date

EndDate

string

Transaction end date

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request: Collection Account

{
  "serviceType": "ADMIN_COLLECTION_ACCOUNT_INFLOW",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "TrackingReference": "ttetedx123",
    "EndDate":"2023-10-10", // Transaction End Date Field
    //Incase you are filtering for a particular date range
    "StartDate": "2023-10-10"// Transaction Start Date Field 
    // Incase you are filtering for a particular date range
  }
}

Sample Request: Main Account

{
  "serviceType": "ADMIN_ACCOUNT_INFLOW",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "EndDate":"2023-10-10", // Transaction End Date Field
    //Incase you are filtering for a particular date range
    "StartDate": "2023-10-10"// Transaction Start Date Field
    // Incase you are filtering for a particular date range
    }
}

Response

{
  "message": "Request successful.",
  "status": true,
  "data": {
    "postingsHistory": [
      {
        "entryCode": "C340-04",
        "referenceNumber": "231115297705",
        "reversalReferenceNumber": null,
        "accountNumber": "2504349511",
        "linkedAccountNumber": null,
        "realDate": "2023-11-11T09:57:41.5166667",
        "amount": 5100000,
        "openingBalance": 490000,
        "balanceAfter": 5590000,
        "narration": "Kuda Fee Transaction",
        "instrumentNumber" :   "ITR-15ce4b23-07f0-4718-b1",
        "postingRecordType": 2,
        "postedBy": "N/A",
        "financialDate": "2023-11-15T00:00:00",
        "financialDateToBackdate": null,
        "ipAddress": null,
        "merchant": null,
        "recipientName": null,
        "senderName": null,
        "recipientBank": null,
        "senderBank": null,
        "userID": null,
        "hasCOTWaiver": false,
        "forceDebit": false,
        "transactionType": "Card Settlement",
        "postingType": 1,
        "transactionMethod": 26,
        "sessionId": null,
        "charge": 0,
        "beneficiaryName": "Open API",
        "allowChangeCategory": false,
        "categoryId": 12,
        "categorySet": false,
        "tagId": 108,
        "beneficiaryReference": "7000003360",
        "goalTitle": null,
        "phoneNumberRecharged": null,
        "billId": null,
        "tier0Waiver": false,
        "detailOfClosure": null,
        "reasonForClosure": null,
        "closedBy": null,
        "metaData": null
      },
    ],
    "message": null,
    "statusCode": "k00",
    "totalRecordInStore": 2,
    "totalDebit": 6267.82,
    "totalCredit": 56100
}
}

Fetch Outgoing Account Transactions

This requests retrieves a list of all Kuda account outgoing transactions for
the currently authenticated user.

Body Parameters

serviceType

string

Required

Service type for this request are:
Collection Account - ADMIN_COLLECTION_ACCOUNT_OUTFLOW
Main Account - ADMIN_ACCOUNT_OUTFLOW

requestRef

string

Required

The unique reference identifier for this request

trackingReference

string

Unique Identifier for the customer’s account

PageSize

string

The number of listed transaction per page

PageNumber

string

The maximum number of result page

StartDate

string

Transaction start date

EndDate

string

Transaction end date

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request: Collection Account

{
  "serviceType": "ADMIN_COLLECTION_ACCOUNT_OUTFLOW",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "PageNumber": "1",
    "PageSize": "10",
    "TrackingReference": "ttetedx123",
    "EndDate":"2023-10-10", // Transaction End Date Field
    //Incase you are filtering for a particular date range
    "StartDate": "2023-10-10"// Transaction Start Date Field 
    // Incase you are filtering for a particular date range
  }
}

Sample Request: Main Account

{
  "serviceType": "ADMIN_ACCOUNT_OUTFLOW",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "PageNumber": "1",
    "PageSize": "10",
    "EndDate":"2023-10-10", // Transaction End Date Field
    //Incase you are filtering for a particular date range
    "StartDate": "2023-10-10"// Transaction Start Date Field
    // Incase you are filtering for a particular date range
    }
}

Response

{
  "message": "Request successful.",
  "status": true,
  "data": {
    "postingsHistory": [
      {
        "entryCode": "C340-04",
        "referenceNumber": "231115297705",
        "reversalReferenceNumber": null,
        "accountNumber": "2504349511",
        "linkedAccountNumber": null,
        "realDate": "2023-11-11T09:57:41.5166667",
        "amount": 5100000,
        "openingBalance": 490000,
        "balanceAfter": 5590000,
        "narration": "Kuda Fee Transaction",
        "instrumentNumber" :   "ITR-15ce4b23-07f0-4718-b1",
        "postingRecordType": 2,
        "postedBy": "N/A",
        "financialDate": "2023-11-15T00:00:00",
        "financialDateToBackdate": null,
        "ipAddress": null,
        "merchant": null,
        "recipientName": null,
        "senderName": null,
        "recipientBank": null,
        "senderBank": null,
        "userID": null,
        "hasCOTWaiver": false,
        "forceDebit": false,
        "transactionType": "Card Settlement",
        "postingType": 1,
        "transactionMethod": 26,
        "sessionId": null,
        "charge": 0,
        "beneficiaryName": "Open API",
        "allowChangeCategory": false,
        "categoryId": 12,
        "categorySet": false,
        "tagId": 108,
        "beneficiaryReference": "7000003360",
        "goalTitle": null,
        "phoneNumberRecharged": null,
        "billId": null,
        "tier0Waiver": false,
        "detailOfClosure": null,
        "reasonForClosure": null,
        "closedBy": null,
        "metaData": null
      },
    ],
    "message": null,
    "statusCode": "k00",
    "totalRecordInStore": 2,
    "totalDebit": 6267.82,
    "totalCredit": 56100
}
}

Filtered Kuda Account Transaction History

This requests filters Kuda account transactions results for the authenticated
user.

Notice

Adding a time parameter can also help you narrow your transaction better as well

Body Parameters

serviceType

string

Required

Service type for this request are:
Service type for this request is: ADMIN_MAIN_ACCOUNT_FILTERED_TRANSACTIONS

requestRef

string

Required

The unique reference identifier for this request

PageSize

string

Required

The number of listed transaction per page

PageNumber

string

Required

The maximum number of result page

StartDate

string

Transaction start date

EndDate

string

Transaction end date

ReferenceNumber

string

Account Reference number

InstrumentNumber

string

Instrument Number

TransactionDate

string

Transaction Date

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
"serviceType": "ADMIN_MAIN_ACCOUNT_FILTERED_TRANSACTIONS",
"requestRef": "{{$randomInt}}-test",
"Data": {
  "PageNumber": "1",
  "PageSize": "10",
  "EndDate":"2024-10-10",
  "StartDate": "2023-10-10",
  "TransactionDate": "2023-10-10",
  "ReferenceNumber": "test DVA",
  "InstrumentNumber": "test DVA"
  }
}

Response

{
"Data": {
	"PostingsHistory": [
		{
			"ReferenceNumber":"2009040496",
			"ReversalReferenceNumber":null,
			"AccountNumber":"2111155641",
			"LinkedAccountNumber":null,
			"RealDate":"2020-10-27T09:58:23.4740446Z",
			"Amount":40.0,
			"OpeningBalance":714000.0,
			"BalanceAfter":713960.0,
			"Narration":"Kuda Debit",
			"InstrumentNumber":"7059779",
			"PostingRecordType":1,
			"PostedBy":"N/A"
		},
	],
	"Message": null,
	"StatusCode": "k00",
	"TotalRecordInStore": 11,
	"TotalDebit": 234490,
	"TotalCredit": 0
	}
}

Filtered Collection Account Transaction History

This requests filters Kuda account transactions results for collection accounts.

Notice

Adding a time parameter can also help you narrow your transaction better as well

Body Parameters

serviceType

string

Required

Service type for this request are:
ADMIN_COLLECTION_ACCOUNT_FILTERED_TRANSACTIONS

requestRef

string

Required

The unique reference identifier for this request

PageSize

string

Required

The number of listed transaction per page

PageNumber

string

Required

The maximum number of result page

TrackingReference

string

Required

Unique Identifier for the customer’s account

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
"serviceType": "ADMIN_COLLECTION_ACCOUNT_FILTERED_TRANSACTIONS",
"requestRef": "{{$randomInt}}-test",
"Data": {
  "PageNumber": "1",
  "PageSize": "10",
  "TrackingReference": "ttetedx123"
  }
}

Response

{
  "message": "Request successful.",
  "status": true,
  "data": {
    "postingsHistory": [
      {
        "entryCode": "C340-04",
        "referenceNumber": "231115297705",
        "reversalReferenceNumber": null,
        "accountNumber": "2504349511",
        "linkedAccountNumber": null,
        "realDate": "2023-11-11T09:57:41.5166667",
        "amount": 5100000,
        "openingBalance": 490000,
        "balanceAfter": 5590000,
        "narration": "Kuda Fee Transaction",
        "instrumentNumber": "ITR-15ce4b23-07f0-4718-b1",
        "postingRecordType": 2,
        "postedBy": "N/A",
        "financialDate": "2023-11-15T00:00:00",
        "financialDateToBackdate": null,
        "ipAddress": null,
        "merchant": null,
        "recipientName": null,
        "senderName": null,
        "recipientBank": null,
        "senderBank": null,
        "userID": null,
        "hasCOTWaiver": false,
        "forceDebit": false,
        "transactionType": "Card Settlement",
        "postingType": 1,
        "transactionMethod": 26,
        "sessionId": null,
        "charge": 0,
        "beneficiaryName": "Open API",
        "allowChangeCategory": false,
        "categoryId": 12,
        "categorySet": false,
        "tagId": 108,
        "beneficiaryReference": "7000003360",
        "goalTitle": null,
        "phoneNumberRecharged": null,
        "billId": null,
        "tier0Waiver": false,
        "detailOfClosure": null,
        "reasonForClosure": null,
        "closedBy": null,
        "metaData": null
      },
    ],
      "message": null,
      "statusCode": "k00",
      "totalRecordInStore": 5,
      "totalDebit": 6267.82,
      "totalCredit": 56100
  }
}

Collection Account Transaction History

This requests retrieves a list of all collection account transactions for the
currently authenticated user.

Body Parameters

serviceType

string

Required

Service type for this request are:
ADMIN_COLLECTION_ACCOUNT_FILTERED_TRANSACTIONS

requestRef

string

Required

The unique reference identifier for this request

PageSize

string

Required

The number of listed transaction per page

PageNumber

string

Required

The maximum number of result page

StartDate

string

Required

Transaction start date

EndDate

string

Required

Transaction end date

ReferenceNumber

string

Required

The transaction reference number.

InstrumentNumber

string

Required

The transaction instrument number.

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{
  "serviceType": "ADMIN_COLLECTION_ACCOUNT_FILTERED_TRANSACTIONS",
  "requestRef": "{{$randomInt}}-test",
  "Data": {
    "PageNumber": "1",
    "PageSize": "10",
    "TrackingReference": "ttetedx123"
    }
}

Response

{
	"Status": true,
	"Message": "Operation successful",
	"Data": {
	  "PostingsHistory":[
		  {
        "ReferenceNumber":"2009040496",
        "ReversalReferenceNumber":null,
        "AccountNumber":"2111155641",
        "LinkedAccountNumber":null,
        "RealDate":"2020-10-27T09:58:23.4740446Z",
        "Amount":40.0,
        "OpeningBalance":714000.0,
        "BalanceAfter":713960.0,
        "Narration":"Kuda Debit",
        "InstrumentNumber":"7059779",
        "PostingRecordType":1,
        "PostedBy":"N/A"
		  },
	  ],
	  "Message": null,
		"StatusCode": "k00",
		"TotalRecordInStore": 11,
		"TotalDebit": 234490,
		"TotalCredit": 0
		}
}

Main Account Transaction History

This requests retrieves filtered a list of main account transactions.
You can also filter using the parameters: ReferenceNumber,

InstrumentNumber, TrackingReference , pageSize, pageNumber, StartDate
and EndDate.

Body Parameters

serviceType

string

Required

Service type for this request are:
ADMIN_COLLECTION_ACCOUNT_FILTERED_TRANSACTIONS

requestRef

string

Required

The unique reference identifier for this request

PageSize

string

Required

The number of listed transaction per page

PageNumber

string

Required

The maximum number of result page

StartDate

string

Required

Transaction start date

EndDate

string

Required

Transaction end date

ReferenceNumber

string

Required

The transaction reference number.

InstrumentNumber

string

Required

The transaction instrument number.

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{    
    "serviceType": "ADMIN_MAIN_ACCOUNT_TRANSACTIONS",
    "requestref": "",
    "Data": {
      "PageSize": "1",
      "PageNumber": "1"
    }
  }

Response

 
{
    "message": "Request successful.",
    "status": true,
    "data": {
        "postingsHistory": [
            {
                "entryCode": "D",
                "referenceNumber": "240426434577",
                "reversalReferenceNumber": null,
                "accountNumber": "3020806687",
                "linkedAccountNumber": null,
                "realDate": "2024-04-26T12:30:40.22",
                "amount": 10000.00,
                "openingBalance": 456244884.00,
                "balanceAfter": 456234884.00,
                "narration": "Collection account NIN verification charge. TRef 20240416",
                "instrumentNumber": "e1c7528f-d936-48c9-9ab3-69e82903410e",
                "postingRecordType": 1,
                "postedBy": "N/A",
                "financialDate": "2024-04-26T00:00:00",
                "financialDateToBackdate": null,
                "ipAddress": null,
                "merchant": "Kuda",
                "recipientName": null,
                "senderName": null,
                "recipientBank": null,
                "senderBank": null,
                "userID": null,
                "hasCOTWaiver": false,
                "forceDebit": false,
                "transactionType": "Intrabank Outward",
                "postingType": 1,
                "transactionMethod": 26,
                "sessionId": null,
                "charge": 0.00,
                "beneficiaryName": "",
                "allowChangeCategory": false,
                "categoryId": 0,
                "categorySet": false,
                "tagId": 999999,
                "beneficiaryReference": "10704",
                "goalTitle": null,
                "phoneNumberRecharged": null,
                "billId": null,
                "tier0Waiver": false,
                "detailOfClosure": null,
                "reasonForClosure": null,
                "closedBy": null,
                "metaData": "{\"ThirdPartyReference\":null,\"SenderAccountname\":\"Nollex Group\",\"SenderAccountNumber\":\"3020806687\"}"
            }
        ],
        "message": null,
        "statusCode": "k00",
        "totalRecordInStore": 13241,
        "totalDebit": 15440017.05,
        "totalCredit": 20002365.89
    }
}

Transaction Status Query

This requests retrieves the status of a transaction.

Body Parameters

serviceType

string

Required

Service type for this request are:
ADMIN_MAIN_ACCOUNT_TRANSACTIONS

requestRef

string

Required

The unique reference identifier for this request

IsThirdPartyBankTransfer

string

Required

if the transaction was inter-bank or intra-bank

TransactionRequestReference

string

Required

the Request Reference used when you made transaction

Headers

Authorization : Bearer

string

Required

Your Access Token

Note

Please make sure to submit all TSQ requests at least 2 minutes after the transaction has been initiated.

Sample Request

{    
  "serviceType": "TRANSACTION_STATUS_QUERY",
  "requestref": "",
  "Data": {
      "IsThirdPartyBankTransfer": false,
      "TransactionRequestReference": "310-Intra"
  }
}

Response

{
    "responseCode": "00",
    "sessionID": "240319490045",
    "status": true,
    "message": "Transaction successful.",
    "data": null
}

Retrieve Statement

This requests retrieves the a customer’s transaction statement.

Body Parameters

serviceType

string

Required

Service type for this request is: RETRIEVE_STATEMENT.

requestRef

string

Required

The unique reference identifier for this request

TrackingReference

string

The transaction statement unique tracking reference identifier.

fromDate

string

Required

The transaction start date.

toDate

string

Required

The transaction end date.

format

string

Required

TThe transaction statement file format. (e.g. PDF, CSV…)

Headers

Authorization : Bearer

string

Required

Your Access Token

Sample Request

{    
  "serviceType": "RETRIEVE_STATEMENT",
  "requestref": "",
  "Data": {
		"TrackingReference": "t1",
    "fromDate": "2023-01-01",
    "toDate": "2024-01-01",
    "format": "Pdf"
  }
}

Response

{
  "message": "Your statement is on its way to your inbox",
  "status": true,
  "data": null
}

Information

See Fund Transfer Codes for Kuda & Interbank to get more information on your transaction request.