Bill Payment

Bill payment endpoints for Switch

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

Get vendor's plan

GET 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

{
    "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"
            }
        }
    ]
}

Make Payment

POST 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

Bills Payment Categories

GET 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 token_string

{
    "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"
        }
    ]
}

Get vendors in a category

GET 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

{
    "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"
        }
    ]
}

Bill Payment Vendors

GET 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

{
    "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
        }
    ]
}

Saved Bill Payment Information

GET 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

{
    "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",
        }
    ]
}

Delete a saved bill

DELETE 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

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

PreviousAudit LogsNextBudget

Last updated

Was this helpful?