Telecommunication API Usage

Step 1: Operators Retrieval.

A request to the operator retrieval endpoint returns a list of currently supported operators. The operator code returned will be used for getting available products from a particular operator. call API endpoint

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

{
  "success": true,
  "data": [
    {
      "desc": "Airtel Nigeria",
      "id": "op_Q4vPwCHzKj9E8CoCLs7TaC",
      "name": "Airtel",
      "sector": "Telecommunications"
    },
    {
      "desc": "Globacom (Glo Nigeria)",
      "id": "op_P9ids5CbcsWacHPb7c2mzp",
      "name": "Glo",
      "sector": "Telecommunications"
    },
    {
      "desc": "MTN Nigeria",
      "id": "op_93FFk4Khww9rYXgK2Xtr9E",
      "name": "MTN",
      "sector": "Telecommunications"
    },
    {
      "desc": "Visafone Nigeria",
      "id": "op_K5w2yzGJJmqrRx83qHbFXv",
      "name": "Visafone",
      "sector": "Telecommunications"
    },
    {
      "desc": "9Mobile Nigeria",
      "id": "op_jwes4uVEWVHtz8aSgyQ6Vy",
      "name": "9Mobile",
      "sector": "Telecommunications"
    }
  ],
  "message": "supported operators"
}

Description of Response Fields

Fields	Description
id	Unique identifier of the telco.
name	Operator name
sector	An umbrella name for the sector under which this operator functions
desc	Description or full name of the operator.

Step 2: Product Retrieval.

Acquire the list of available Telco products. This will be used for getting available products from a particular operator. call API endpoint

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

{
  "success": true,
  "data": [

    {
      "category": "pctg_6dNCwhHijBGYQnZ4jXTRJs",
      "desc": null,
      "fee_type": "FIXED",
      "id": "prd_nHuDJve7m2ebmwPs4XY8s4",
      "meta": {
        "currency": "NGN",
        "data_expiry": "3 days",
        "data_value": "200MB",
        "fee": "220.00"
      },
      "name": "Airtel -- 200MB",
      "operator": "op_Q4vPwCHzKj9E8CoCLs7TaC"
    },
    {
      "category": "pctg_6dNCwhHijBGYQnZ4jXTRJs",
      "desc": null,
      "fee_type": "FIXED",
      "id": "prd_3rHxaEAeqfbKjYRXVHaVMT",
      "meta": {
        "currency": "NGN",
        "data_expiry": "7 days",
        "data_value": "350MB",
        "fee": "330.00"
      },
      "name": "Airtel -- 350MB",
      "operator": "op_Q4vPwCHzKj9E8CoCLs7TaC"
    },
   
    {
      "category": "pctg_XD6Zr4sUAs9vjv2QBGumbT",
      "desc": null,
      "fee_type": "RANGE",
      "id": "prd_ZhzAL5M7jXEdPSSunBpwX3",
      "meta": {
        "currency": "NGN",
        "maximum_fee": "100000.00",
        "minimum_fee": "50.00"
      },
      "name": "Airtel -- Airtime",
      "operator": "op_Q4vPwCHzKj9E8CoCLs7TaC"
    }
    ...
  ],
  "message": "supported operators"
}

Description of Request Fields

Fields	Description
operatorID	Unique identifier of the telco.

Description of Response Fields

Fields	Description
id	Unique identifier of the product. To be submitted during payment for the product.
name	Name of the product
desc	Description of the 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	Product category unique identifier.
operator	Telco unique identifier.
meta	Variable metadata determined by the product service category

Step 3: Payment Fulfillments.

Make payment for data/mobile top-up . The client is required to generate a client_reference, which would be sent along with the payment request. call API endpoint

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

{
    "amount": 10000,
    "product_id": "prd_er6f7iU6Mgd6V6hPmYmEKf",
    "operator_id": "op_Q4vPwCHzKj9E8CoCLs7TaC",
    "beneficiary_msisdn":"07082828249"
}

{
  "success": true,
  "data": {
        "amount": "10.00",
        "created": "2022-10-20T01:30:20.354986",
        "customer_category": "prepaid",
        "e_receipt": "RC-TEL/16662258210255483",
        "meta": {
            "audit_number": null,
            "confirmation_code": null
        },
        "operator": "Airtel",
        "operator_receipt": null,
        "operator_reference": null,
        "payer": {
            "name": "BlocMobile",
        },
        "payment_reference": "d351b117e99045228cffe9189db43541",
        "status": "ACTIVE"
    },
  "message": "make payment"
}

Description of Request Fields

Fields	Description
amount	The amount being paid ( in kobos. )
payment_reference	Unique alphanumeric string sent by the integrator (client) as reference for each transaction.
product_id	Unique identifier of product.
beneficiary_msisdn	Customer phone number to be credited.

Description of Response Fields

Fields	Description
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.
operator_receipt	The payment receipt, if any, provided by the operator.
payment_reference	The unique transaction identifier used for the transaction.