# API Reference

## Airtime Purchase

<mark style="color:green;">`POST`</mark> `/utilityPayment/v2/airtimePayment`

\<Use this endpoint to purchase Airtime>

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th width="105">Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>The ID of the account that is to make the payment</td><td>TRUE</td></tr><tr><td><code>mobileNumber</code></td><td>string</td><td>The number of the mobile that is to purchase airtime for</td><td>TRUE</td></tr><tr><td><code>networkProvider</code></td><td>int</td><td><p>0 - SAFARICOM </p><p>1 - AIRTEL </p><p>2 - TELKOM</p></td><td>TRUE</td></tr><tr><td><code>amount</code></td><td>decimal</td><td>Top up amount</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}
```json
{
  "txId": "",
  "paymentId": ""
}
```
{% endtab %}
{% endtabs %}

## Airtime Purchase - Bulk

<mark style="color:green;">`POST`</mark> `/utilityPayment/v2/airtimeBulkPayment`

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

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th width="105">Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>The ID of the account that is to make the payment</td><td>TRUE</td></tr><tr><td><code>mobileDetails</code></td><td>array</td><td>The mobile numbers that are to be purchased airtime for.</td><td>TRUE</td></tr><tr><td>>><code>mobileNumber</code></td><td>string</td><td>Mobile number</td><td>TRUE</td></tr><tr><td>>><code>networkProvider</code></td><td>int</td><td><p>0 - SAFARICOM </p><p>1 - AIRTEL </p><p>2 - TELKOM</p></td><td>TRUE</td></tr><tr><td>>><code>amount</code></td><td>decimal</td><td>Top up amount</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}
```json
{
  "bulkPaymentOrderId": ""
}
```
{% endtab %}
{% endtabs %}

## Query Utility Bill&#x20;

<mark style="color:green;">`POST`</mark> `/utilityPayment/billQuery`

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

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th width="105">Is Required</th></tr></thead><tbody><tr><td><code>billType</code></td><td>int</td><td><p>0 - DSTV</p><p>1 - GOTV</p><p>3 - STARTIMES </p><p>6 - WATER</p></td><td>TRUE</td></tr><tr><td><code>mobile</code></td><td>string</td><td>The mobile number that is linked to the bill</td><td>FALSE</td></tr><tr><td><code>billOrderNumber</code></td><td>string</td><td>Bill order number</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}
```json
{
  "dueDate": "",
  "dueAmount": "",
  "currency": "",
}
```
{% endtab %}
{% endtabs %}

## Utility Bill Payment

<mark style="color:green;">`POST`</mark> `/utilityPayment/v2/billPayment`

\<Use this endpoint to pay the utility bill>

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th width="105">Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>The number of the account that is to make the payment</td><td>TRUE</td></tr><tr><td><code>billType</code></td><td>int</td><td><p>0 - DSTV</p><p>1 - GOTV</p><p>3 - STARTIMES </p><p>6 - WATER</p></td><td>TRUE</td></tr><tr><td><code>billOrderNumber</code></td><td>string</td><td>Bill order number</td><td>TRUE</td></tr><tr><td><code>amount</code></td><td>decimal</td><td><p>Payment amount; </p><p>If it's not given, it will be populated with the due amount of that bill.</p></td><td>FALSE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}
```json
{
  "txId": "",
  "paymentId": ""
}
```
{% endtab %}
{% endtabs %}

## Query Utility Payment Details

<mark style="color:green;">`POST`</mark> `/utilityPayment/paymentQuery`

\<Use this endpoint to pay the utility payment details>

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th width="105">Is Required</th></tr></thead><tbody><tr><td><code>paymentId</code></td><td>string</td><td>The unique string that generated by Choice to identify a utility payment/airtime purchase request</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}
```json
{
  "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": "",
}
```
{% endtab %}
{% endtabs %}

## Query Bulk Payment Details

<mark style="color:green;">`POST`</mark> `/utilityPayment/bulkPaymentQuery`

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

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="339">Description</th><th width="105">Is Required</th></tr></thead><tbody><tr><td><code>bulkPaymentOrderId</code></td><td>string</td><td>The unique string that generated by Choice to identify a batch of utility payment/airtime purchase requests</td><td>TRUE</td></tr><tr><td><code>pageNo</code></td><td>int</td><td>page number</td><td>TRUE</td></tr><tr><td><code>pageSize</code></td><td>int</td><td>page size</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}
```json
{
  "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": "",
    }, {}
  ]
}
```
{% endtab %}
{% endtabs %}
