# Bill Payment

```
STAGING_URL: https://switch-api-staging.herokuapp.com
LIVE_URL: https://switchapi.azurewebsites.net
```

## Get vendor's plan

<mark style="color:blue;">`GET`</mark> `https://switch-api-staging.herokuapp.com/user/bills/vendors/:id/plans`

This endpoint retrieves a particular vendor's plan

#### Path Parameters

| Name | Type   | Description          |
| ---- | ------ | -------------------- |
| id   | string | the id of the vendor |

#### Headers

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| SWI-CID | string | Client ID   |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Vendor plans retrieved successfully",
    "data": [
        {
            "mandate_id": "SWV220200401122742464584041257",
            "id": "01",
            "name": "Premium",
            "payment_code": "10401",
            "item_fee": "80",
            "vat": 4,
            "category_id": "2",
            "input_fields": [
                {
                    "key": "consumer_id_field",
                    "value": "",
                    "text": "Decoder Number"
                }
            ],
            "additions": {
                "amount": "14600.00",
                "total": "14684.00"
            }
        },
        {
            "mandate_id": "SWV220200401122742464584041257",
            "id": "28",
            "name": "Access",
            "payment_code": "10428",
            "item_fee": "80",
            "vat": 4,
            "category_id": "2",
            "input_fields": [
                {
                    "key": "consumer_id_field",
                    "value": "",
                    "text": "Decoder Number"
                }
            ],
            "additions": {
                "amount": "1800.00",
                "total": "1884.00"
            }
        },
        {
            "mandate_id": "SWV220200401122742464584041257",
            "id": "03",
            "name": "Compact",
            "payment_code": "10403",
            "item_fee": "80",
            "vat": 4,
            "category_id": "2",
            "input_fields": [
                {
                    "key": "consumer_id_field",
                    "value": "",
                    "text": "Decoder Number"
                }
            ],
            "additions": {
                "amount": "8500.00",
                "total": "8584.00"
            }
        },
        {
            "mandate_id": "SWV220200401122742464584041257",
            "id": "06",
            "name": "Family",
            "payment_code": "10406",
            "item_fee": "80",
            "vat": 4,
            "category_id": "2",
            "input_fields": [
                {
                    "key": "consumer_id_field",
                    "value": "",
                    "text": "Decoder Number"
                }
            ],
            "additions": {
                "amount": "3960.00",
                "total": "4044.00"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Make Payment

<mark style="color:green;">`POST`</mark> `https://switch-api-staging.herokuapp.com/bills/pay`

This endpoint makes payment to a particular vendor plan

#### Headers

| Name          | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| SWI-CS        | string | Payload checksum                   |
| SWI-CID       | string | Client                             |
| Authorization | string | Format is ***Bearer*** ***token*** |

#### Request Body

| Name                | Type    | Description                                                                      |
| ------------------- | ------- | -------------------------------------------------------------------------------- |
|                     | string  | Required if user's 2fa is ***pin***.                                             |
| otp                 | string  | Required if user's 2fa is ***phone*** or ***google\_authenticator***.            |
| custom\_cron        | string  | The number of days if the event\_pattern is ***custom***                         |
| event\_pattern      | string  | The repeating pattern. Values can be ***monthly***, ***weekly*** or ***custom*** |
| repeat              | boolean | Shows if a scheduled bill should be repeatable                                   |
| start\_date         | string  | This is a date time parameter. It is the start date to schedule a bill payment   |
| save\_information   | boolean | Boolean flag that determines if the bill information is to be saved              |
| category\_id        | string  | category id of the plan                                                          |
| mandate\_id         | string  | mandate\_id of the plan                                                          |
| item\_fee           | string  | item fee of vendor, used to calculate the total amount                           |
| plan\_name          | string  | name of plan                                                                     |
| plan\_id            | string  | id of the plan                                                                   |
| vendor\_id          | string  | id of the vendor                                                                 |
| consumer\_id\_field | string  | the customer's device number                                                     |
| amount              | string  | cost of plan in Naira                                                            |
| payment\_code       | string  | code for making payment                                                          |
| total               | string  | total cost in Naira                                                              |
| vat                 | string  | vat on the plan                                                                  |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Bills Payment Categories

<mark style="color:blue;">`GET`</mark> `https://switch-api-staging.herokuapp.com/user/bills/categories`

Retrieves all available categories

#### Headers

| Name          | Type   | Description                                   |
| ------------- | ------ | --------------------------------------------- |
| SWI-CID       | string | Client ID                                     |
| Authorization | string | Format is **Bearer&#x20;*****token\_string*** |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Bill payment categories retrieved successfully",
    "data": [
        {
            "id": "2",
            "name": "Cable TV Bills",
            "description": "Pay for your cable TV subscriptions here",
            "category_icon": "https://res.cloudinary.com/ushnuel/image/upload/v1586203831/Switch/tv_and-entertainment.png",
            "category_color": "#caeeff"
        },
        {
            "id": "4",
            "name": "Mobile Recharge",
            "description": "Recharge your phone",
            "category_icon": "https://res.cloudinary.com/ushnuel/image/upload/v1586203917/Switch/airtime_and_data.png",
            "category_color": "#ecedfa"
        },
        {
            "id": "6",
            "name": "Phone Bills",
            "description": "Pay all post paid phone bills",
            "category_icon": null,
            "category_color": null
        },
        {
            "id": "7",
            "name": "Subscriptions",
            "description": "Pay for your other subscriptions (like ISP) here",
            "category_icon": null,
            "category_color": null
        },
        {
            "id": "13",
            "name": "Transport",
            "description": "Transport",
            "category_icon": "https://res.cloudinary.com/ushnuel/image/upload/v1586203865/Switch/travel_and_transport.png",
            "category_color": "#d0faf2"
        },
        {
            "id": "1",
            "name": "Utility Bills",
            "description": "Pay your utility bills here",
            "category_icon": "https://res.cloudinary.com/ushnuel/image/upload/v1586203937/Switch/utility_bills.png",
            "category_color": "#e3f9bb"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get vendors in a category

<mark style="color:blue;">`GET`</mark> `https://switch-api-staging.herokuapp.com/user/bills/categories/:id/vendors`

This endpoint retrieves all the vendors in a category.

#### Path Parameters

| Name | Type   | Description                                  |
| ---- | ------ | -------------------------------------------- |
| id   | number | The id of the category to filter its vendors |

#### Query Parameters

| Name        | Type   | Description                   |
| ----------- | ------ | ----------------------------- |
| short\_name | string | The short name of the vendor. |

#### Headers

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| SWI-CID | string | Client ID   |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Vendors retrieved successfully",
    "data": [
        {
            "vendor_id": "120",
            "name": "9Mobile Prepaid",
            "short_name": "9MobileMTU",
            "narration": "Buy Etisalat recharge",
            "surcharge": null,
            "bill_payment_category_id": "4",
            "switch_short_name": null,
            "switch_category": "purchase_airtime",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/9Mobile_logo.png"
        },
        {
            "vendor_id": "901",
            "name": "Airtel Prepaid",
            "short_name": "AirtelMTU",
            "narration": "Top up your line automatically",
            "surcharge": null,
            "bill_payment_category_id": "4",
            "switch_short_name": null,
            "switch_category": "purchase_airtime",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/Airtel_logo.png"
        },
        {
            "vendor_id": "402",
            "name": "Glo Prepaid",
            "short_name": "GloMTU",
            "narration": "Mobile Top-Up",
            "surcharge": null,
            "bill_payment_category_id": "4",
            "switch_short_name": null,
            "switch_category": "purchase_airtime",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/Glo_logo.png"
        },
        {
            "vendor_id": "109",
            "name": "MTN Prepaid",
            "short_name": "MTNVTU",
            "narration": "Purchase MTN Virtual Aitime",
            "surcharge": null,
            "bill_payment_category_id": "4",
            "switch_short_name": null,
            "switch_category": "purchase_airtime",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/Mtn_logo.png"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Bill Payment Vendors

<mark style="color:blue;">`GET`</mark> `https://switch-api-staging.herokuapp.com/user/bills/vendors`

This endpoint retrieves all bill payment vendors

#### Query Parameters

| Name        | Type   | Description                   |
| ----------- | ------ | ----------------------------- |
| short\_name | string | The short name of the vendor. |

#### Headers

| Name          | Type   | Description                  |
| ------------- | ------ | ---------------------------- |
| SWI-CID       | string | Client ID                    |
| Authorization | string | Format is ***Bearer token*** |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Bill payment category vendors retrieved successfully",
    "data": [
        {
            "vendor_id": "901",
            "name": "Airtel Prepaid",
            "short_name": "AirtelMTU",
            "narration": "Top up your line automatically",
            "surcharge": null,
            "switch_short_name": null,
            "switch_category": "purchase_airtime",
            "bill_payment_category_id": "6",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/Airtel_logo.png"
        },
        {
            "vendor_id": "120",
            "name": "9Mobile Prepaid",
            "short_name": "9MobileMTU",
            "narration": "Buy Etisalat recharge",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": "purchase_airtime",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/9Mobile_logo.png"
        },
        {
            "vendor_id": "402",
            "name": "Glo Prepaid",
            "short_name": "GloMTU",
            "narration": "Mobile Top-Up",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": "purchase_airtime",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/Glo_logo.png"
        },
        {
            "vendor_id": "14319",
            "name": "IBEDC",
            "short_name": "IBEDC",
            "narration": "IBEDC Prepaid",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": null,
            "logo_url": null
        },
        {
            "vendor_id": "137",
            "name": "Ikeja Prepaid",
            "short_name": "IKEDC",
            "narration": "Ikeja Prepaid",
            "surcharge": null,
            "switch_short_name": null,
            "switch_category": null,
            "bill_payment_category_id": "6",
            "logo_url": null
        },
        {
            "vendor_id": "111",
            "name": "IPNX",
            "short_name": "IPNX",
            "narration": "Pay IPNX subscriptions",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": "internet_services",
            "logo_url": "https://storage.googleapis.com/switch/Bill_Logos/IPNX_logo.png"
        },
        {
            "vendor_id": "14235",
            "name": "Lekki Concession Company",
            "short_name": "LCCN",
            "narration": "Lekki Concession Company",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": null,
            "logo_url": null
        },
        {
            "vendor_id": "106",
            "name": "MTN VTU PLUS DATA PLAN",
            "short_name": "MTN",
            "narration": "VTU PLUS",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": null,
            "logo_url": null
        },
        {
            "vendor_id": "905",
            "name": "Phcn Prepaid",
            "short_name": "PhcnPP",
            "narration": "Buy your meter token",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": null,
            "logo_url": null
        },
        {
            "vendor_id": "14237",
            "name": "SpectraNet",
            "short_name": "SPEC",
            "narration": "SpectraNet",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": null,
            "logo_url": null
        },
        {
            "vendor_id": "102",
            "name": "Airtel Postpaid",
            "short_name": "Airtel",
            "narration": "Pay Zain bill",
            "surcharge": null,
            "switch_short_name": null,
            "bill_payment_category_id": "6",
            "switch_category": null,
            "logo_url": null
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Saved Bill Payment Information

<mark style="color:blue;">`GET`</mark> `https://switch-api-staging.herokuapp.com/user/bills/saved_bills`

This endpoint retrieves all the saved bill payment information.

#### Query Parameters

| Name      | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| per\_page | number | number of bill payment info per page |
| page      | number | page number                          |

#### Headers

| Name          | Type   | Description                  |
| ------------- | ------ | ---------------------------- |
| SWI-CID       | string | Client ID                    |
| Authorization | string | Format is ***Bearer token*** |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Saved bill payment information retrieved successfully",
    "data": [
        {
            "consumer_id_field": "08183372896",
            "vendor": {
                "vendor_id": "2",
                "name": "Vendor1",
                "narration": "",
                "short_name": "vend1",
                "surcharge": null,
                "switch_category": null,
                "switch_short_name": null
            },
            "created_at": "2019-03-27T13:35:47.160Z",
        },
        {
            "consumer_id_field": "08027194502",
            "vendor": {
                "vendor_id": "2",
                "name": "Vendor1",
                "narration": "",
                "short_name": "vend1",
                "surcharge": null,
                "switch_category": null,
                "switch_short_name": null
            },
            "created_at": "2019-03-27T13:37:22.482Z",
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Delete a saved bill

<mark style="color:red;">`DELETE`</mark> `https://switch-api-staging.herokuapp.com/user/saved_bills/:id`

This endpoint deletes a saved bill.

#### Path Parameters

| Name | Type   | Description                      |
| ---- | ------ | -------------------------------- |
| id   | number | the identifier of the saved bill |

#### Headers

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| SWI-CID | string | Client ID   |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Saved bill deleted successfully"
}
```

{% endtab %}

{% tab title="404 " %}

```
{
    "message": "saved bill with id 400 does not exist"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://switchng.gitbook.io/switch/bill-payment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.