> For the complete documentation index, see [llms.txt](https://switchng.gitbook.io/switch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://switchng.gitbook.io/switch/bill-payment.md).

# 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 %}