Quidpay allows merchants to re-sell bill payment services such as airtime payments in Nigeria, Ghana and the US and DSTV payment in Nigeria and Ghana.

Merchants get to make a 3% commission on successful Airtime sales, and a 70 naira flat commission on other bill services.

To get started with our bill payment APIs you would need to follow the prerequisites below.

Prerequisites for getting started with Quidpay bill payments.

Sign-up for a test account here, and for a live account here .
Navigate to the Transfers page on your dashboard and top up your balance using the Top up balance option. [Can we reference the support document showing how to do this?]
Ensure your available balance is funded before making use of the APIs.

We would be showing you how to make successful requests below.

Bill payment endpoint

Staging: https://ravesandboxapi.flutterwave.com/v2/services/confluence

Live: https://api.ravepay.co/v2/services/confluence

Request Structure

{
  "secret_key": "<YOUR SECRET KEY>",
  "service": "bills_categories",
  "service_method": "get",
  "service_version": "v1",
  "service_channel": "quidpay",
  "service_payload": ""
}

What do these parameters mean?

Parameter	Required	Description
`secret_key`	True	This is your merchant secret key, please see our section on API Keys to learn how to retrieve your secret key.
`service`	True	This is the bill payment services available please see a list below with explanation of the services. e.g. `fly_buy` , `fly_recurring`
`service_method`	True	This is the HTTP Method for the required service.
`service_version`	True	This is the version for the APIs ... please set to `v1`, when a new version is available you would be able to put your required version.
`service_channel`	True `Expected value: quidpay`	This is the channel for the service, always use `quidpay` as the value.
`service_payload`	False	This is the request to be sent for the service.

Bill Payment Services

fly_buy [POST]: This allows you to buy Airtime, DSTV bill services. When you pass this as your service in the request you would need to pass a service_payload as well.
fly_buy_bulk [POST]: This allows you to buy bulk Airtime and DSTV bill services.
fly_recurring [GET]: This allows you to retrieve active recurring Airtime and DSTV bill services.
fly_recurring_cancel [POST]: This allows you to cancel recurring Airtime and DSTV bill services.
fly_history [POST]: This allows you to retrieve a history of all purchased bill services including commission earned.
fly_requery [GET]: This allows you get the status of a bill purchase.
bill_categories [GET]: This allows you to get a list of individual bill categories.
bills_validate [GET]: This allows you to validate services like DSTV smartcard no etc.

Please see below for what you would need to pass as your service payload.

Sample requests

{
  "secret_key": "<YOUR SECRET KEY>",
  "service": "fly_buy",
  "service_method": "post",
  "service_version": "v1",
  "service_channel": "quidpay",
  "service_payload": {
    "Country": "NG",
    "CustomerId": "+23490803840303",
    "Reference": "9300049404444",
    "Amount": 500,
    "RecurringType": 0,
    "IsAirtime": true,
    "BillerName": "AIRTIME"
  }
}

{
  "secret_key": "<YOUR SECRET KEY>",
  "service": "fly_buy_bulk",
  "service_method": "post",
  "service_version": "v1",
  "service_channel": "quidpay",
  "service_payload": {
    "BatchReference": "batch-quidpay-150928302799933922",
    "CallBackUrl": "https://quidpay-webhook.herokuapp.com/newregistration",
    "Requests": [
      {
        "Country": "NG",
        "CustomerId": "+23490803840303",
        "Amount": 500,
        "RecurringType": 0,
        "IsAirtime": true,
        "BillerName": "AIRTIME",
        "Reference": "9300049404444"
      },
      {
        "Country": "GH",
        "CustomerId": "+233276081163",
        "Amount": 10,
        "RecurringType": 0,
        "IsAirtime": true,
        "BillerName": "AIRTIME",
        "Reference": "9300049405555"
      },
      {
        "Country": "US",
        "CustomerId": "+190830030",
        "Amount": 20,
        "RecurringType": 0,
        "IsAirtime": true,
        "BillerName": "AIRTIME",
        "Reference": "9300049406666"
      }
    ]
  }
}

{
  "secret_key": "FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X",
  "service": "fly_recurring",
  "service_method": "get",
  "service_version": "v1",
  "service_channel": "quidpay"
}

{
  "secret_key": "FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X",
  "service": "fly_history",
  "service_method": "post",
  "service_version": "v1",
  "service_channel": "quidpay",
  "service_payload": {
    "FromDate": "2018-08-01",
    "ToDate": "2018-08-27",
    "PageSize": 20,
    "PageIndex": 0
  }
}

{
  "secret_key": "FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X",
  "service": "fly_requery_9300049404444",
  "service_method": "get",
  "service_version": "v1",
  "service_channel": "quidpay"
}

{
  "secret_key": "FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X",
  "service": "bills_categories",
  "service_method": "get",
  "service_version": "v1",
  "service_channel": "quidpay"
}

{
  "secret_key": "FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X",
  "service": "bills_validate_CB140_BIL119_1025401152",
  "service_method": "get",
  "service_version": "v1",
  "service_channel": "quidpay"
}

fly_buy Service payload parameters.

Parameter	Required	Description
`Country`	True	This is the country attached to the service being bought e.g. if Service is Airtime and country is NG it means you are buying airtime in Nigeria. Country can be any of these `NG`, `GH`, `US`
`CustomerId`	True	This is the customer identifier For airtime, the value must be the customer's phone number. For DSTV, it must be the customer's smartcard number.
`Amount`	True	This is the amount for the service you would like to buy.
`RecurringType`	True	This determines if you are buying a service recurrently or not. When value is: `0` - This is a one time payment. `1` - This is an hourly payment. `2` - This is a daily payment. `3` - This is a weekly payment. `4` - This is a monthly payment.
`IsAirtime`	True	Set this flag to `true` for airtime payments and `false` for dstv and non airtime payments.
`BillerName`	True	Pass the following possible values based on the service being bought. `AIRTIME`, `DSTV`, `DSTV BOX OFFICE`.
`Reference`	False	This is a unique reference passed by the developer to identify transactions on their end.

fly_buy_bulk Service payload parameters.

Parameter	Required	Description
`BatchReference`	True	This is a reference that identifies the batch request being made for bulk requests.
`CallBackUrl`	True	This is an endpoint supplied by you the developer/merchant so we can send a response when each request in the bulk is completed.
`Requests`	True	This is an array containing each individual requests in the batch.
`Country`	True	This is the country attached to the service being bought e.g. if Service is Airtime and country is NG it means you are buying airtime in Nigeria. Country can be these set of options `NG`, `GH`, `US`
`CustomerId`	True	This is the customer detail, for airtime the value must be the customer's phone number for DSTV it must be the customer's smartcard number.
`Amount`	True	This is the amount for the service you would like to buy.
`RecurringType`	True	This determines if you are buying a service recurrently or not. When value is: `0` - This is a one time payment. `1` - This is an hourly payment. `2` - This is a daily payment. `3` - This is a weekly payment. `4` - This is a monthly payment.
`IsAirtime`	True	Set this flag to `true` for airtime payments and `false` for dstv and non airtime payments.
`BillerName`	True	Pass the following possible values based on the service being bought. `AIRTIME`, `DSTV`, `DSTV BOX OFFICE`.
`Reference`	False	This is a unique reference passed by the developer to identify transactions on their end.

Sample callback Response.

The callback returns a response for each individual transaction in the batch.

{
  "MobileNumber": "+2349082930030",
  "Amount": 500,
  "Network": "9MOBILE",
  "TransactionReference": "CF-FLYAPI-201808240106311799470372",
  "PaymentReference": "BPUSSD1535069199348655",
  "BatchReference": null,
  "Status": "success",
  "Message": "Bill Payment was completed successfully",
  "Reference": null
}

{
  "Status": "fail",
  "Message": "Invalid customer id",
  "Code": "903",
  "CustomerReference": "+2339026420185"
}

{
  "Status": "fail",
  "Message": "Invalid Phone",
  "Code": "905",
  "CustomerReference": "+190830030"
}

fly_history service payload parameters.

Parameter	Required	Description
`FromDate`	True	This is the start date it can be in formats: `YYYY-MM-DDTHH:MM:SSZ` or `YYYY-MM-DD`
`ToDate`	True	This is the end date, it can be in formats: `YYYY-MM-DDTHH:MM:SSZ` or `YYYY-MM-DD`
`PageSize`	True	This is the number of items you want returned per page.
`PageIndex`	True	This is the page you want to start from.

Sample responses

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "MobileNumber": "+2349082930030",
        "Amount": 500,
        "Network": "9MOBILE",
        "TransactionReference": "CF-FLYAPI-201808230455490136043978",
        "PaymentReference": "BPUSSD1535043354638870",
        "BatchReference": null,
        "Status": "success",
        "Message": "Bill Payment was completed successfully",
        "Reference": null
    }
}

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "MobileNumber": null,
        "Amount": 0,
        "Network": null,
        "TransactionReference": null,
        "PaymentReference": null,
        "BatchReference": "CF-BATCH-FLY-API-201808241206220204935114",
        "Status": "success",
        "Message": "Bill Payment was queued for processing",
        "Reference": null
    }
}

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "RecurringPayments": [
            {
                "Id": 5,
                "UniqueReference": "+2349082930030",
                "Amount": 500,
                "DateStarted": "2018-08-24T05:35:18.587Z",
                "DateStopped": null,
                "NextRun": "2018-08-24T06:35:18.587Z",
                "RecurringType": "Hourly"
            }
        ],
        "Status": "success",
        "Message": "successful",
        "Reference": null
    }
}

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "Summary": [
            {
                "Currency": "NGN",
                "SumBills": 3500,
                "SumCommission": 40,
                "SumDstv": 0,
                "SumAirtime": 2000,
                "CountDstv": 0,
                "CountAirtime": 4
            },
            {
                "Currency": "KES",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "GHS",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "USD",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "EUR",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "ZAR",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "GBP",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "TZS",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            },
            {
                "Currency": "UGX",
                "SumBills": 0,
                "SumCommission": 0,
                "SumDstv": 0,
                "SumAirtime": 0,
                "CountDstv": 0,
                "CountAirtime": 0
            }
        ],
        "Transactions": [
            {
                "Currency": "NGN",
                "CustomerId": "+2349082930030",
                "Frequency": "Hourly",
                "Amount": "500.0000",
                "Product": "AIRTIME",
                "ProductName": "FLY-API-NG-AIRTIME-9MOBILE",
                "Commission": 10,
                "TransactionDate": "2018-08-24T05:35:07.213Z",
                "TransactionId": 7895
            },
            {
                "Currency": "NGN",
                "CustomerId": "+2349082930030",
                "Frequency": "One Time",
                "Amount": "500.0000",
                "Product": "AIRTIME",
                "ProductName": "FLY-API-NG-AIRTIME-9MOBILE",
                "Commission": 10,
                "TransactionDate": "2018-08-24T01:06:31.55Z",
                "TransactionId": 7891
            },
            {
                "Currency": "NGN",
                "CustomerId": "+2349082930030",
                "Frequency": "One Time",
                "Amount": "500.0000",
                "Product": "AIRTIME",
                "ProductName": "FLY-API-NG-AIRTIME-9MOBILE",
                "Commission": 10,
                "TransactionDate": "2018-08-23T16:56:07.193Z",
                "TransactionId": 7868
            },
            {
                "Currency": "NGN",
                "CustomerId": "+2349082930030",
                "Frequency": "One Time",
                "Amount": "500.0000",
                "Product": "AIRTIME",
                "ProductName": "FLY-API-NG-AIRTIME-9MOBILE",
                "Commission": 10,
                "TransactionDate": "2018-08-23T16:55:49.413Z",
                "TransactionId": 7867
            }
        ],
        "Total": 4,
        "Status": "success",
        "Message": "Successful",
        "Reference": null
    }
}

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "TransactionReference": "CF-FLYAPI-201808240106311799470372",
        "TransactionAmount": 500,
        "Fee": 0,
        "Currency": null,
        "Extra": null,
        "PaymentReference": null,
        "Token": null,
        "Status": "success",
        "Message": "Successful",
        "Data": null
    }
}

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "Status": "success",
        "Message": "Successful",
        "Data": [
            {
                "Id": 1,
                "BillerCode": "BIL099",
                "Name": "MTN NIgeria",
                "DefaultCommission": 0.02,
                "DateAdded": "2018-07-03T00:00:00Z",
                "Country": "NG",
                "IsAirtime": true,
                "BillerName": "AIRTIME",
                "ItemCode": "AT099",
                "ShortName": "MTN",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[+]{1}[0-9]+$",
                "LabelName": "Mobile Number"
            },
            {
                "Id": 2,
                "BillerCode": "BIL099",
                "Name": "GLO Nigeria",
                "DefaultCommission": 0.025,
                "DateAdded": "2018-07-03T00:00:00Z",
                "Country": "NG",
                "IsAirtime": true,
                "BillerName": "AIRTIME",
                "ItemCode": "AT099",
                "ShortName": "GLO",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[+]{1}[0-9]+$",
                "LabelName": "Mobile Number"
            },
            {
                "Id": 3,
                "BillerCode": "BIL099",
                "Name": "9Mobile",
                "DefaultCommission": 0.025,
                "DateAdded": "2018-07-03T00:00:00Z",
                "Country": "NG",
                "IsAirtime": true,
                "BillerName": "AIRTIME",
                "ItemCode": "AT099",
                "ShortName": "9mobile",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[+]{1}[0-9]+$",
                "LabelName": "Mobile Number"
            },
            {
                "Id": 4,
                "BillerCode": "BIL099",
                "Name": "Airtel Nigeria",
                "DefaultCommission": 0.025,
                "DateAdded": "2018-07-03T00:00:00Z",
                "Country": "NG",
                "IsAirtime": true,
                "BillerName": "AIRTIME",
                "ItemCode": "AT099",
                "ShortName": "Airtel",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[+]{1}[0-9]+$",
                "LabelName": "Mobile Number"
            },
            {
                "Id": 5,
                "BillerCode": "BIL132",
                "Name": "Airtime",
                "DefaultCommission": 0.025,
                "DateAdded": "2018-08-17T00:00:00Z",
                "Country": "GH",
                "IsAirtime": true,
                "BillerName": "AIRTIME",
                "ItemCode": "AT217",
                "ShortName": "Airtime",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[+]{1}[0-9]+$",
                "LabelName": "Mobile Number"
            },
            {
                "Id": 6,
                "BillerCode": "BIL135",
                "Name": "Airtime",
                "DefaultCommission": 0.025,
                "DateAdded": "2018-08-17T00:00:00Z",
                "Country": "US",
                "IsAirtime": true,
                "BillerName": "AIRTIME",
                "ItemCode": "AT219",
                "ShortName": "Airtime",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[+]{1}[0-9]+$",
                "LabelName": "Mobile Number"
            },
            {
                "Id": 7,
                "BillerCode": "BIL119",
                "Name": "DSTV Payment",
                "DefaultCommission": 0.3,
                "DateAdded": "2018-08-17T00:00:00Z",
                "Country": "NG",
                "IsAirtime": false,
                "BillerName": "DSTV",
                "ItemCode": "CB140",
                "ShortName": "DSTV",
                "Fee": 100,
                "CommissionOnFee": true,
                "RegExpression": "^[0-9]+$",
                "LabelName": "Smart Card Number"
            },
            {
                "Id": 8,
                "BillerCode": "BIL137",
                "Name": "DSTV Payment",
                "DefaultCommission": 0,
                "DateAdded": "2018-08-17T00:00:00Z",
                "Country": "GH",
                "IsAirtime": false,
                "BillerName": "DSTV",
                "ItemCode": "CB226",
                "ShortName": "DSTV",
                "Fee": 0,
                "CommissionOnFee": false,
                "RegExpression": "^[0-9]+$",
                "LabelName": "Smart card Number"
            },
            {
                "Id": 9,
                "BillerCode": "BIL119",
                "Name": "DSTV BoxOffice",
                "DefaultCommission": 0.3,
                "DateAdded": "2018-08-17T00:00:00Z",
                "Country": "NG",
                "IsAirtime": false,
                "BillerName": "DSTV BOX OFFICE",
                "ItemCode": "CB140",
                "ShortName": "Box Office",
                "Fee": 100,
                "CommissionOnFee": true,
                "RegExpression": "^[0-9]+$",
                "LabelName": "Smart Card Number"
            }
        ]
    }
}