API Reference

Airtime Purchase

POST /utilityPayment/v2/airtimePayment

<Use this endpoint to purchase Airtime>

Parameters

Parameters	Type	Description	Is Required
accountId	string	The ID of the account that is to make the payment	TRUE
mobileNumber	string	The number of the mobile that is to purchase airtime for	TRUE
networkProvider	int	0 - SAFARICOM 1 - AIRTEL 2 - TELKOM	TRUE
amount	decimal	Top up amount	TRUE

Response

00000

{
  "txId": "",
  "paymentId": ""
}

Airtime Purchase - Bulk

POST /utilityPayment/v2/airtimeBulkPayment

<Use this endpoint to purchase Airtime for a batch of mobile numbers>

Parameters

Parameters	Type	Description	Is Required
accountId	string	The ID of the account that is to make the payment	TRUE
mobileDetails	array	The mobile numbers that are to be purchased airtime for.	TRUE
>>mobileNumber	string	Mobile number	TRUE
>>networkProvider	int	0 - SAFARICOM 1 - AIRTEL 2 - TELKOM	TRUE
>>amount	decimal	Top up amount	TRUE

Response

00000

{
  "bulkPaymentOrderId": ""
}

Query Utility Bill

POST /utilityPayment/billQuery

<Use this endpoint to query the due day and due amount of a utility bill>

Parameters

Parameters	Type	Description	Is Required
billType	int	0 - DSTV 1 - GOTV 3 - STARTIMES 6 - WATER	TRUE
mobile	string	The mobile number that is linked to the bill	FALSE
billOrderNumber	string	Bill order number	TRUE

Response

00000

{
  "dueDate": "",
  "dueAmount": "",
  "currency": "",
}

Utility Bill Payment

POST /utilityPayment/v2/billPayment

<Use this endpoint to pay the utility bill>

Parameters

Parameters	Type	Description	Is Required
accountId	string	The number of the account that is to make the payment	TRUE
billType	int	0 - DSTV 1 - GOTV 3 - STARTIMES 6 - WATER	TRUE
billOrderNumber	string	Bill order number	TRUE
amount	decimal	Payment amount; If it's not given, it will be populated with the due amount of that bill.	FALSE

Response

00000

{
  "txId": "",
  "paymentId": ""
}

Query Utility Payment Details

POST /utilityPayment/paymentQuery

<Use this endpoint to pay the utility payment details>

Parameters

Parameters	Type	Description	Is Required
paymentId	string	The unique string that generated by Choice to identify a utility payment/airtime purchase request	TRUE

Response

00000

{
  "paymentId": "",
  "payServiceCategory": "", //0 - Airtime Purchase; 3 - Utility Bill
  "subType": "", //For airtime purchase, 0-SAFARICOM; 1-AIRTEL; 2-TELKOM
  //For utility bill, 0-DSTV; 1-GOTV; 3-STARTIMES; 6-WATER
  "orderNo": "",
  "txId": "",
  "refundTxId": "",
  "amount": "",
  "status": "", //-1 - Cancelled; 0 - Init; 1 - Submitted; 2 - Processing; 
  //4 - Failed; 8 - Completed
  "errorCode": "",
  "errorMsg": "",
}

Query Bulk Payment Details

POST /utilityPayment/bulkPaymentQuery

<Use this endpoint to pay the bulk utility payment/airtime purchase details>

Parameters

Parameters	Type	Description	Is Required
bulkPaymentOrderId	string	The unique string that generated by Choice to identify a batch of utility payment/airtime purchase requests	TRUE
pageNo	int	page number	TRUE
pageSize	int	page size	TRUE

Response

00000

{
  "bulkPaymentOrderId": "",
  "total": "", //total number of payment requests
  "resultArray": [
    {
      "paymentId": "",
      "payServiceCategory": "", //0 - Airtime Purchase; 3 - Utility Bill
      "subType": "", //For airtime purchase, 0-SAFARICOM; 1-AIRTEL; 2-TELKOM
      //For utility bill, 0-DSTV; 1-GOTV; 3-STARTIMES; 6-WATER
      "orderNo": "",
      "txId": "",
      "refundTxId": "",
      "amount": "",
      "status": "", //-1 - Cancelled; 0 - Init; 1 - Submitted; 2 - Processing; 
      //4 - Failed; 8 - Completed
      "errorCode": "",
      "errorMsg": "",
    }, {}
  ]
}