Goods & Services API documentation

Goods & Services API documentation
4. Products


Products

Depending on the operator, DT One Goods & Services API offers different products.

This section presents the different methods used to get the list of products available per operator.

Note that an object product is defined by different properties, and is organized by type depending on its application (voucher or recharge).

DT One Goods & Services API categorizes the products into 3 types depending on their application:

  • VOUCHERS: the beneficiary receives a voucher or PIN code on his mobile usually via SMS
  • RECHARGES: the account of the beneficiary is recharged in real time
  • PAYMENTS: a payment corresponding to a bill of the beneficiary is issued in real time

There are 4 distinct categories depending on the nature of the product: “fixed value vouchers, “fixed value recharges”, “variable value payments” or “variable value recharges”:

  • FIXED VALUE VOUCHERS: a product of this category is based on a denomination or pre-defined face value and a PIN number is sent to the user
  • FIXED VALUE RECHARGES: a product of this category is more flexible than the previous category, the value is within a pre-defined range and can be selected by the user
  • VARIABLE VALUE PAYMENTS: a product of this category requires a request to retrieve the amount to pay. There is only 1 variable value payment product per operator, only full amount payment is allowed.
  • VARIABLE VALUE RECHARGES: a product of this category allows a recharge of any valid amount to the operator. There is only 1 variable value recharge product per operator.

Each call to a product discovery function will return the list of products per product type along with the category (“fixed_value_vouchers”, “fixed_value_recharges”, “variable_value_payments”, “variable_value_recharges”)

A fixed value product is defined as follows:

{
    "product_id":          => NUMERIC,
    "product_name":        => VARCHAR,
    "product_short_desc":  => VARCHAR,
    "operator_id":         => NUMERIC,
    "operator":            => VARCHAR,
    "country_id":          => NUMERIC,
    "country":             => VARCHAR,
    "service_id":          => NUMERIC,
    "service":             => VARCHAR,
    "product_value"        => NUMERIC,
    "product_currency"     => VARCHAR,
    "local_value"          => NUMERIC,
    "local_currency"       => VARCHAR,
    "account_currency":    => VARCHAR,
    "wholesale_price":     => NUMERIC,
    "retail_price":        => NUMERIC,
    "fee":                 => NUMERIC,
}

1- List of products for an operator - Sample Request/Response

GET /operators/{operator_id}/products - List of products proposed by an operator

Response :

HTTP Code: 200

Body:

{
    "fixed_value_vouchers":[],
    "fixed_value_recharges":
        [
            {
                "product_id":64,
                "product_name":"$14 Basic",
                "product_short_desc":"14 USD Basic",
                "operator_id":1959,
                "operator":"Claro TV Guatemala USD",
                "country_id":756,
                "country":"Guatemala",
                "service_id":1,
                "service":"television",
                "product_value":14,
                "product_currency":"USD",
                "local_value":14,
                "local_currency":"USD",
                "account_currency":"USD",
                "wholesale_price":12.5,
                "retail_price":13.5,
                "fee":0
            },
            {
                "product_id":65,
                "product_name":"$20 Advanced",
                "product_short_desc":"20 USD Advanced",
                "operator_id":1959,
                "operator":"Claro TV Guatemala USD",
                "country_id":756,
                "country":"Guatemala",
                "service_id":1,
                "service":"television",
                "product_value":20,
                "product_currency":"USD",
                "local_value":20,
                "local_currency":"USD",
                "account_currency":"USD",
                "wholesale_price":18,
                "retail_price":19.3,
                "fee":0
            }
        ],
    "fixed_value_payments":[],
    "variable_value_vouchers":[],
    "variable_value_recharges":[],
    "variable_value_payments":[]
}

2- List of products available in one country - Sample Request/Response

GET /countries/{country_id}/products[?operator_id=XXX&service_id=YYY] - List of products available in one country which can be filtered by operator and/or service

Response :

HTTP Code: 200

Body:

{
    "fixed_value_vouchers":[],
    "fixed_value_recharges":
        [
            {
                "product_id":64,
                "product_name":"$14 Basic",
                "product_short_desc":"14 USD Baisc",
                "operator_id":1959,
                "operator":"Claro TV Guatemala USD",
                "country_id":756,
                "country":"Guatemala",
                "service_id":1,
                "service":"television",
                "product_value":14,
                "product_currency":"USD",
                "local_value":14,
                "local_currency":"USD",
                "account_currency":"USD",
                "wholesale_price":12.5,
                "retail_price":13.5,
                "fee":0
            }
        ],
    "fixed_value_payments":[],
    "variable_value_vouchers":[],
    "variable_value_recharges":[],
    "variable_value_payments":[],
}

3- List of products for one service type - Sample Request/Response

GET /services/{service_id}/products[?operator_id=XXX&country_id=YYY] - List of products available for a service which can be filtered by operator and/or country

Response :

HTTP Code: 200

Body:

{
    "fixed_value_vouchers":[],
    "fixed_value_recharges":
        [
            {
                "product_id":64,
                "product_name":"$14 Basic",
                "product_short_desc":"14 USD Baisc",
                "operator_id":1959,
                "operator":"Claro TV Guatemala USD",
                "country_id":756,
                "country":"Guatemala",
                "service_id":1,
                "service":"television",
                "product_value":14,
                "product_currency":"USD",
                "local_value":14,
                "local_currency":"USD",
                "account_currency":"USD",
                "wholesale_price":12.5,
                "retail_price":13.5,
                "fee":0
            }
        ],
    "fixed_value_payments":[],
    "variable_value_vouchers":[],
    "variable_value_recharges":[],
    "variable_value_payments":[]
}

4- List of suggested values for variable value recharge products - Sample Request/Response

GET /product/variable_value_recharges/{product_id}/suggested_values - List of suggested values available for a variable value product

Response :

HTTP Code: 200

Body:

{
    "suggested_values":
        [
            {
                "local_value":9,
                "local_currency":"INR",
                "name":"50 MB of 2G Plan for 1 Day",
                "description":"AIRT / UPE / 9INR / 2G Plan / 50 MB / 1 Day",
                "additional_info_1":"type:2G Plan",
                "additional_info_2":"validity:1 Day",
                "additional_info_3":"data_amount:50 MB",
                "wholesale_price":"0.14",
                "retail_price":"0.06",
                "fee":0
            },
            {
                "local_value":19,
                "local_currency":"INR",
                "name":"110 MB of 2G Plan for 3 Days",
                "description":"AIRT / UPE / 19INR / 2G Plan / 110 MB / 3 Days",
                "additional_info_1":"type:2G Plan",
                "additional_info_2":"validity:3 Days",
                "additional_info_3":"data_amount:110 MB",
                "wholesale_price":"0.3",
                "retail_price":"0.14",
                "fee":0
              }
        ]
}

5- Verification of an account for a specific product

Some products allow the API consumer to check if an account_number is valid for that specific product.
To check if an account_number is valid for a specific product, you can use the following request:

Request :

GET /products/{product_id}/account_number/{account_number}/status

Response :

  • If the functionality is available for a specific product, you will get the following response:

HTTP Code: 200

Body:

{
    "verified":1
}

If the account number is valid, verified will contain value 1, if not valid, value will be 0.

  • If the functionality is not available for a product, you will get the following response:

HTTP Code: 400

Body:

    {
        "errors":[
            {
                "code":1000304,
                "message":"Account verification not available for this product"
            }]
    }