Bill Payments, GiftCards & Betting Services
The Kuda bill service allows you to connect to a list of bill providers such as Airtime, Data, Sports betting and
other Value-added services.
Information
All transaction amount are in Kobo. (For example, 10020 is 100 Naira 20 Kobo)
Purchase Bill
This request lets customers purchase airtime, betting, data, electricity, and
TV subscriptions. Please refer to the ‘Get Bill Type' request to obtain
information about Bill payments.
Note
Tokens/PINs are not always returned in the purchase response, depending on the bill type. You would be required to call the TSQ service after a few seconds in order to see the PIN/Token information.
If you supplied a webhook for your bills notification, you will receive the details of the bill purchased along side the PIN/Token information.
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
PURCHASE_BILL
requestRef
|
string
|
Required
The unique reference identifier for this request
customerFirstName
|
string
|
Required
The customer’s first name
customerIdentifier
|
string
|
Required
The customer’s unique ID
phoneNumber
|
string
|
Required
The customer’s phone number
billItemIdentifier
|
string
|
Required
The Bill Item ID. see GET Bill Type to get BillItemIdentifier
amount
|
string
|
Required
Bill purchase amount in Kobo
trackingReference
|
string
|
Required
The bill purchase tracking reference id
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "PURCHASE_BILL",
"requestRef": "12211aS12",
"data": {
"CustomerFirstName":"Test",
"CustomerIdentifier":"07030000000",
"PhoneNumber":"07030000000",
"BillItemIdentifier":"KD-VTU-MTNNG",
"Amount":"10000",
"TrackingReference":"ttetedx123"
}
}Response
{
"message": "Your bill purchase request is successful",
"status": true,
"data": {
"reference": "AMZMqDjSafTsobg",
"pin": null
},
"statusCode": "00"
}Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
GET_PURCHASED_BILLS
requestRef
|
string
|
Required
The unique reference identifier for this request
trackingReference
|
string
|
Required
The bill purchase tracking reference id
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "GET_PURCHASED_BILLS",
"requestRef": "12211aS-${{$randomInt}}",
"data": {
"TrackingReference":"ttetedx123"
}
}Response
{
"message": "Operation successful!",
"status": true,
"data": {
"billPayments": [
{
"billerName": "MTN-NG",
"kudaReference": "AMZMqDjSafTsobg",
"kudaAccountNumber": "2504349511",
"transactionChannel": "OPEN_API",
"transactionAmount": 10000,
"recipientNumber": "2347030000000",
"transactionStatus": 3,
"postingStatus": 2,
"hasBeenReserved": null,
"billType": "Airtime"
},
{
"billerName": "MTN-NG",
"kudaReference": "AMW00fbpF1BljeB",
"kudaAccountNumber": "2504349511",
"transactionChannel": "OPEN_API",
"transactionAmount": 10000,
"recipientNumber": "2347030000000",
"transactionStatus": 3,
"postingStatus": 2,
"hasBeenReserved": null,
"billType": "Airtime"
}
]
},
"statusCode": "k00"
}Purchase Giftcard
This request enables customers to purchase giftcards. All giftcards are
generally purchased in dollars. See Get Giftcards to obtain the GiftCardData
for this request.
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
BUY_GIFT_CARD
requestRef
|
string
|
Required
The unique reference identifier for this request
billItemIdentifier
|
string
|
Required
The Bill Item ID. see Get Giftcards request to get BillItemIdentifier
requestingCustomerEmail
|
string
|
Required
The customer’s email address
requestingCustomerEmail
|
string
|
Required
The customer’s email address
requestingCustomerName
|
string
|
Required
The customer’s name
requestingCustomerMobile
|
string
|
Required
The customer’s phone number
clientFeeCharge
|
string
|
Required
This is the Client fee charges for purchasing giftcards
amount
|
string
|
Required
Giftcard amount in dollars
trackingReference
|
string
|
Required
The bill purchase tracking reference id
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "BUY_GIFT_CARD",
"requestRef": "12211aS13",
"data": {
"BillerIdentifier": "KUD-GFTC-CAD-020",
"RequestingCustomerEmail": "test@business.com",
"RequestingCustomerName": "Test User",
"RequestingCustomerMobile": "07030000000",
"ClientFeeCharge": 0,
"Amount": "10", //In Dollars
"TrackingReference": "ttetedx123"
}
}Response
{
"message": "Your bill purchase request is successful",
"status": true,
"data": {
"reference": "AMZMqDjSafTsobg",
"pin": null
},
"statusCode": "00"
}Purchase Bill
This request lets customers purchase airtime, betting, data, electricity, and
TV subscriptions. Please refer to the ‘Get Bill Type' request to obtain
information about Bill payments.
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
ADMIN_PURCHASE_BILL
requestRef
|
string
|
Required
The unique reference identifier for this request
customerFirstName
|
string
|
Required
The customer’s first name
customerIdentifier
|
string
|
Required
The customer’s unique ID
phoneNumber
|
string
|
Required
The customer’s phone number
billItemIdentifier
|
string
|
Required
The Bill Item ID. see GET Bill Type to get BillItemIdentifier
amount
|
string
|
Required
Bill purchase amount in Kobo
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "ADMIN_PURCHASE_BILL",
"requestRef": "12211aS{{$randomInt}}",
"data": {
"CustomerFirstName":"Test",
"CustomerIdentifier":"07030000000",
"PhoneNumber":"07030000000",
"BillItemIdentifier":"KD-VTU-MTNNG",
"Amount":"10000",
}
}Response
{
"message": "Your bill purchase request is successful",
"status": true,
"data": {
"reference": "AMZMqDjSafTsobg",
"pin": null
},
"statusCode": "00"
}Get Purchased Bill
This request retrieves a bill payment that has already been made from the
Kuda database.
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
ADMIN_GET_PURCHASED_BILLS
requestRef
|
string
|
Required
The unique reference identifier for this request
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "ADMIN_GET_PURCHASED_BILLS",
"requestRef": "12211aS-${{$randomInt}}",
"data": {
}
}Response
{
"message": "Operation successful!",
"status": true,
"data": {
"billPayments": [
{
"billerName": "MTN-NG",
"kudaReference": "AMZMqDjSafTsobg",
"kudaAccountNumber": "2504349511",
"transactionChannel": "OPEN_API",
"transactionAmount": 10000,
"recipientNumber": "2347030000000",
"transactionStatus": 3,
"postingStatus": 2,
"hasBeenReserved": null,
"billType": "Airtime"
},
{
"billerName": "MTN-NG",
"kudaReference": "AMW00fbpF1BljeB",
"kudaAccountNumber": "2504349511",
"transactionChannel": "OPEN_API",
"transactionAmount": 10000,
"recipientNumber": "2347030000000",
"transactionStatus": 3,
"postingStatus": 2,
"hasBeenReserved": null,
"billType": "Airtime"
}
]
},
"statusCode": "k00"
}Purchase Giftcard
This request enables customers to purchase giftcards. All giftcards are
generally purchased in dollars. See Get Giftcards to obtain the GiftCardData
for this request.
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
ADMIN_BUY_GIFT_CARD
requestRef
|
string
|
Required
The unique reference identifier for this request
billItemIdentifier
|
string
|
Required
The Bill Item ID. seeGet Giftcards request to get BillItemIdentifier
requestingCustomerEmail
|
string
|
Required
The customer’s email address
requestingCustomerEmail
|
string
|
Required
The customer’s email address
requestingCustomerName
|
string
|
Required
The customer’s name
requestingCustomerMobile
|
string
|
Required
The customer’s phone number
clientFeeCharge
|
string
|
Required
This is the Client fee charges for purchasing giftcards
amount
|
string
|
Required
Giftcard amount in dollars
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "ADMIN_BUY_GIFT_CARD",
"requestRef": "12211aS13",
"data": {
"BillerIdentifier": "KUD-GFTC-CAD-020",
"RequestingCustomerEmail": "test@business.com",
"RequestingCustomerName": "Test User",
"RequestingCustomerMobile": "07030000000",
"ClientFeeCharge": 0,
"Amount": "10", //In Dollars
"TrackingReference": "ttetedx123"
}
}Response
{
"message": "You just bought a gift card.",
"status": true,
"data": {
"totalDebit": 0,
"reference": "12211aS12331q",
"pin": {
"number": "KUDA-TEST",
"serial": "9582b34d-bc17-441b-8a3f-990787f98bb1",
"instructions": "Input code on the site"
}
},
"requestReference": "12211aS12331q",
"transactionResponseCode": "k00"
}Get Bill Type
This request gets all bill types that are available from Kuda. See the list
below to view all available bill types:
Airtime
MTN
Airtel
Globacom
Betting
Sportybet
Bet9ja
Nairabet
MerryBet
BetWay
BetKing
1XBet
BangBet
BetLand
MLotto
HallaBet
LivescoreBet
SureBet247
Football.com
Internet Data
Spectranet NG
Smile NG
9Mobile
Airtel
Globacom
MTN
Electricity
EKEDC
IKEDC
EEDC
PHEDC
AEDC
KEDCO
Cable TV
DSTV
STARTIMES NG
Showmax
GoTv NG
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
GET_BILLERS_BY_TYPE
requestRef
|
string
|
Required
The unique reference identifier for this request
billTypeName
|
string
|
Required
The list of available biller type are:
Airtime , Betting , Internet Data , Electricity, CableTv.
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Note
Pass biller category types to return the list of biller merchants under the category
Sample Request
JSON
Copy
{
"serviceType": "GET_BILLERS_BY_TYPE",
"requestRef": "",
"Data":{
"BillTypeName": "betting"
}
}Response
{
"Status": true,
"Message": "Completed Successfully",
"data": {
"Billers":[
{
"Id":"69d604cb-2314-4594-9f2b-77ee29afdce4",
"Name":"Thetherest",
"Description":"Test",
"BillerIconUrl":"https://kudatestblob.blob.core.windows.net/kuda-biller-mgmt/011822220405083711446315678859",
"BillTypeId":"22393d6f-e830-4a3a-b1c0-85c6dc007b98",
"BillItems":[]
},
{
"Id":"a156efb6-af1e-4cca-b8d9-efc8ce7eb77e",
"Name":"9MOBILE NG VTU",
"Description":"Airtime",
"BillerIconUrl":"https://kudatestblob.blob.core.windows.net/kuda-biller-mgmt/011458210304130749600692095567",
"BillTypeId":"22393d6f-e830-4a3a-b1c0-85c6dc007b98",
"BillItems":[]
}
]
}
}Get All Billers
This request retrieves a list of all the gift card billing services that are
currently available in the Kuda database.
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
GET_BILLERS
requestRef
|
string
|
Required
The unique reference identifier for this request
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "GET_BILLERS",
"requestRef": "12211aS-${{$randomInt}}",
"data": {
}
}Response
{
"message": "Operation successful!",
"status": true,
"data": {
"billers": [
{
"id": "9b168b76-39cf-4d37-a821-018341afee59",
"name": "Airbnb USA",
"description": "Hotels",
"billerIconUrl": "https://kudatestblob.blob.core.windows.net/kuda-biller-mgmt/011656230928090014884143677964",
"billTypeId": "d1e321d1-ec10-40e1-b02a-466ffc8e1145",
"isActive": true
},
]}}Verify Customer Before Bill Purchase
Just like an account or bank transfer, You need to verify a customer's identity
before successfully initiating a bill purchase instance. This way you reduce
the issue of theft or erroneous bill payments which are hard to retrieve.
Information
Depending on your business module, a tracking ref would be used to debit a customer collection account for the purpose of the bill purchase.
Note
You don't need to verify the customer if the bill type is airtime
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
VERIFY_BILL_CUSTOMER
requestRef
|
string
|
Required
The unique reference identifier for this request
KudaBillItemIdentifier
|
string
|
Required
The Kuda bill unique identifier
CustomerIdentification
|
string
|
Required
The customer’s unique ID
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Information
In the case of collection account top up or electricity top up, the customerName may be different from the name assigned to the trackingRef.
Sample Request
JSON
Copy
{
"serviceType": "VERIFY_BILL_CUSTOMER",
"requestref": "foobar",
"Data":{
"KudaBillItemIdentifier":"KUD-ELE-AEDC-001",
"CustomerIdentification":"46432634278"
}
}Response
{
"data": {
"StatusCode":"k00",
"Status":true,
"Message":"Operation successful!",
}
"Data":{
"CustomerName":"JohnPaul"
}
}Note
We do not control the actions on the biller's end but we can provide the status of the transaction from the biller's response.
See billing status codes here → Bill Purchase Status Codes
Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
BILL_TSQ
requestRef
|
string
|
Required
The unique reference identifier for this request
BillResponseReference
|
string
|
Required
The bill purchase response reference. Response from a biller will carry a BillResponseReference. You can use the billResponseRef to check the true status of your bill purchase
BillRequestRef
|
string
|
Required
The bill purchase request reference. You can either pass thebillresponseRef or the BillRequestRef( requestRef)but not both at the same time
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "BILL_TSQ",
"requestRef": "",
"Data":{
"BillResponseReference": "BMfoobar",
"BillRequestRef":"FooBar"
}
}Response
{
"message": "Request successful.",
"status": true,
"data": {
"finalStatus": "Successful",
"transactionStatus": 3,
"postingStatus": 2,
"billerAggregatorStatus": "00",
"pin": {
"number": "See instructions",
"serial": "",
"instructions": ""
},
"hasBeenReversed": null
},
"statusCode": "k00"
}Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
GIFT_CARD_TSQ
trackingReference
|
string
|
Required
Collection account tracking reference number
amount
|
integer
|
Required
The gift card amount to be purchased. in USD.
vendingRequestRef
|
string
|
Required
The RequestRef used in making the gift card purchase.
vendingResponseReference
|
string
|
Required
TThe reference property gotten from the gift card purchase response.
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "GIFT_CARD_TSQ",
"requestref": "",
"Data":{
"vendingRequestRef": "12211aS13qwedsa"
}
}Response
{
"message": "Operation successful!",
"status": true,
"data": {
"statusCode": null,
"transactionDetails": {
"billerName": "Best Buy Canada",
"kudaReference": "12211aS13qwedsa",
"kudaAccountNumber": "3020806687",
"transactionChannel": "OPEN_API",
"transactionAmount": 606782,
"recipientNumber": "test@business.com",
"transactionStatus": 3,
"postingStatus": 4,
"hasBeenReserved": null,
"billType": "Electronics"
},
"tsqDetails": {
"aggregatorTsqCode": null,
"reference": null,
"customerToken": null,
"pin": null,
"isSuccessful": false,
"message": null,
"statusCode": null
}
}
}Body Parameters
serviceType
|
string
|
Required
Service type for this request is:
GET_GIFT_CARD
Headers
Authorization : Bearer
|
string
|
Required
Your Access Token
Sample Request
JSON
Copy
{
"serviceType": "GET_GIFT_CARD",
"requestRef": "12211aS-${{$randomInt}}",
"data":{}
}Response
{
"message": "Request successful.",
"status": true,
"data": {
"giftCardData": {
"categories": [
"App Store",
"Apple Gift Card",
"Beauty",
"Electronics",
"Fashion",
"Film & TV",
"Food Delivery",
"Gaming",
"Home Decor",
"Hotels",
"Music",
"Restaurant",
"Shopping",
"Transport",
"Travels"
],
"giftItems": [
{
"package": "6th Street",
"image": "https://d38v990enafbk6.cloudfront.net/6th_street.png",
"category": "Fashion",
"countries": [
{
"name": "United Arab Emirates",
"image": "https://d38v990enafbk6.cloudfront.net/united_arab_emirates.png",
"packageName": "6th Street UAE",
"currency": "AED",
"items": [
{
"local_Product_Value_Min": 50,
"local_Product_Value_Max": 50,
"kuda_Identifier": "KUD-GFTC-UAE-001",
"amount_In_Naira": 11263.248,
"rate": 225.26496
},
{
"local_Product_Value_Min": 100,
"local_Product_Value_Max": 100,
"kuda_Identifier": "KUD-GFTC-UAE-002",
"amount_In_Naira": 22526.5062,
"rate": 225.265062
},
{
"local_Product_Value_Min": 200,
"local_Product_Value_Max": 200,
"kuda_Identifier": "KUD-GFTC-UAE-003",
"amount_In_Naira": 45053.0022,
"rate": 225.26501100000002
},
{
"local_Product_Value_Min": 500,
"local_Product_Value_Max": 500,
"kuda_Identifier": "KUD-GFTC-UAE-004",
"amount_In_Naira": 112632.5106,
"rate": 225.26502119999998
}
]
}
]
}
]
}
}
}Information
See Bill Purchase Status Codes to get more information on your transaction request.