Pay TV API Usage

Step 1: Operators Retrieval.

A request to the operator retrieval endpoint returns a list of currently supported TV operators. call API endpoint

https://api.blochq.io/v1/bills/television/operators

{
  "success": true,
  "data": [
    {
      "desc": "StarTimes Nigeria",
      "id": "op_BLVi7pAoj2LHbvNS89W8TU",
      "name": "STARTIMES",
      "sector": "Television"
    },
    {
      "desc": "GoTV Nigeria",
      "id": "op_ry32iksGwx6nQQnVAHu8N7",
      "name": "GOTV",
      "sector": "Television"
    },
    {
      "desc": "Digital Satellite Television",
      "id": "op_pspQ6hAfsNd3mfKsY9rCik",
      "name": "DSTV",
      "sector": "Television"
    }
  ],
  "message": "supported operators"
}

Description of Response Fields

Fields	Description
id	The unique ID of this operator name
name	A simple and abbreviated name for this operator
sector	An umbrella name for the sector under which this operator functions
desc	A more descriptive name/representation of this operator.

Step 2: Product Retrieval.

A request to the product retrieval endpoint returns a list of Pay TV products. call API endpoint

https://api.blochq.io/v1/bills/television/operators/{operatorID}/products

{
  "success": true,
  "data": [
    {
      "category": "pctg_mZY9WG7W8LmkHQYViSFD6k",
      "desc": null,
      "fee_type": "FIXED",
      "id": "prd_qvQJ7PkdLFZQBB7XPoCXjY",
      "meta": {
        "currency": "NGN",
        "fee": "2900.00"
      },
      "name": "HDPVR/XtraView -- 1 month",
      "operator": "op_pspQ6hAfsNd3mfKsY9rCik"
    },
    {
      "category": "pctg_mZY9WG7W8LmkHQYViSFD6k",
      "desc": null,
      "fee_type": "FIXED",
      "id": "prd_La8gJx4UoFnNd5wnivCiHs",
      "meta": {
        "currency": "NGN",
        "fee": "5800.00"
      },
      "name": "HDPVR/XtraView -- 2 month",
      "operator": "op_pspQ6hAfsNd3mfKsY9rCik"
    },
    {
      "category": "pctg_mZY9WG7W8LmkHQYViSFD6k",
      "desc": null,
      "fee_type": "FIXED",
      "id": "prd_nbuoYCKMsLxK7B6p6EVcNm",
      "meta": {
        "currency": "NGN",
        "fee": "6450.00"
      },
      "name": "DStv Padi -- 3 month",
      "operator": "op_pspQ6hAfsNd3mfKsY9rCik"
    }
    ...
  ],
  "message": "supported operators"
}

Description of Response Fields

Fields	Description
id	The unique identifier of this product. (To be submitted during payment for this product.)
name	The name of this product
desc	The description of this product
fee_type	The flexibility of the amount you can pay for this product. (One of FIXED , FLEXIBLE or RANGE ). See Payment Fee Type
category	The unique identifier of the product category.
operator	The unique identifier of the service provider, that is, the disco.
meta	Extra information about the product, if any, as supplied by the service provider.

Step 3: Customer Validation.

The customer validation endpoint must be called to verify the smart card number of the customer. Upon successful validation, this endpoint returns customer information like name, phone and minimum payable among other things. It also returns a payment_reference, which must be provided when making a subsequent call for payment. Do note that this reference has an expiration time, hence it must be used quickly. call API endpoint

Retrieve the details of a customer matching the given parameters. This must be called before initiating a payment for the customer.

https://api.blochq.io/v1/bills/television/customers/:operatorID/:productNumber

{
    "success": true,
    "data": {
        "address": null,
        "balance": null,
        "category": "prepaid",
        "current_bill": null,
        "debt": null,
        "email": null,
        "meta": {
            "account_number": "78925446",
            "account_status": "OPEN",
            "customer_type": "SUD",
            "due_date": "2022-11-17T00:00:00+01:00",
            "invoice_period": 1,
            "smartcard_number": "7022422039"
        },
        "minimum_payable": null,
        "name": "MUYIDE BLESSING",
        "payment_reference": "31e0c47090734cc4b2649f99e55453b7",
        "phone": null,
        "total_due": null,
        "unique_id": "7022422044"
    },
   "message": "customer details"
}

Description of Request Fields

Fields	Description
operatorID	The unique identifier of the television operator.
productNumber	The smart card number identifier assigned to the customer.
category	The category of the customer account. Values could be postpaid ,prepaid or smart-meter .

Description of Response Fields

Fields	Description
unique_id	The card number assigned to the customer.
name	The account name of the customer
email	The email address of the customer
phone	The phone number of the customer.
debt	The current debt of customer, if any, in nairas.
minimum_payable	The minimum amount the customer must pay on their. next payment, in nairas.
payment_reference	The reference to be presented when completing a payment for the customer, following the validation.
meta	The meta is a key-value object containing television provider-specific information. The values may vary per call and/or operation
category	The customer account category.

Step 4: Payment Fulfillments.

After successful validation of a customer, a request is made to the payment endpoint to
complete a payment transaction in favour of the validated customer. call API endpoint

For some discos, it is required that the amount paid in a transaction should surpass the minimum payable amount of the customer. The minimum payable amount is contained in the response of a Customer Validation request.

https://api.blochq.io/v1/bills/television/payment

{
    "amount": 185000,
    "product_id": "prd_cTxoTJ2QE9Lq3KKdT48kq8",
    "payment_reference": "ae4d32d2f7d940f191c0fe0ed5c2c8c4"
}

{
    "success”: true,
    "data": {
        "amount": "1850.00",
        "created": "2022-10-20T02:23:38.299650",
        "customer_category": "prepaid",
        "e_receipt": "RC-TLV/16662290191316112",
        "meta": {
            "account_number": "31179092",
            "name": "Sten Mockett",
            "smartcard_number": "7022422039"
        },
        "operator": "DSTV",
        "operator_receipt": "17442941117639542685",
        "operator_reference": "1628497982",
        "payer": {
            "name": "EppMobile"
        },
        "payment_reference": "711a667da1c54a11abda153bdf0877b9",
        "status": "ACTIVE"
    },
    "message": "make payment"
}

Description of Request Fields

Fields	Description
amount	The amount being paid ( in kobos. )
payment_reference	The payment_reference value retrieved during Customer Validation.
product_id	Product Id of the service

Description of Response Fields

Fields	Description
account_number	The customer’s account/card number.
amount	Amount paid (in naira) .
created	The date and time of the request.
e_receipt	A unique invoice number generated for this transaction.
meta	The meta is a key-value object containing operator-specific information. The values may vary per call and/or operation.
name	The name of the customer.
operator_receipt	The payment receipt, if any, provided by the operator.
payment_reference	The unique transaction identifier used for the transaction.