Best Practices for Filtering and Categorizing Products

Once you perform a mobile number lookup, you will receive the corresponding operator_id, making it easier to retrieve the list of products available for a specific operator or mobile number.

Parameter	Type	Format	Constraints (Regex)	Description
`type`	`string` (`ProductTypes`)			The type of product. Possible values: `FIXED_VALUE_RECHARGE`, `RANGED_VALUE_RECHARGE`, `FIXED_VALUE_PIN_PURCHASE`, `RANGED_VALUE_PIN_PURCHASE`, `RANGED_VALUE_PAYMENT`
`service_id`	`integer` (`ServiceID`)	`int32`	`>= 1`	Service identifier. See Services for more details. Required when `subservice_id` is specified.
`subservice_id`	`integer` (`SubServiceID`)	`int32`	`>= 1`	Sub-service identifier. See Services for more details.
`country_iso_code`	`string` (`X-ISO-3166-1_Alpha-3`)		`^[A-Z]{3}$` (Regex) Ensures strict adherence to the 3-letter ISO country code format.	Country code in ISO 3166-1 alpha-3 format. Note that the official list can be extended.
`operator_id`	`integer` (`OperatorID`)	`int32`	`>= 1`	Operator identifier.
`region`	`string` (`X-ISO-3166-2`)		`^[A-Z]{2,3}(?:-[A-Z0-9]{2,3}(?:-[A-Z]{2})?)?$` (Regex) Ensures adherence to the ISO subregion code format.	Country subregion code in ISO 3166-2 format. Note that the official list can be extended.
`benefit_types`	`Array of strings` (`BenefitTypes`)		`unique`	An array of benefit types to filter by. Possible values: `TALKTIME`, `DATA`, `SMS`, `PAYMENT`, `CREDITS`

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

Example Product Retrieval

For full endpoint descriptions, see:

GET: Retrieve product by ID
GET: Retrieve list of products

GET /v1/products/56876

GET /v1/products?service_id=1&subservice_id=11

{
    "availability_zones": ["INTERNATIONAL"],
    "benefits": [
        {
            "additional_information": null,
            "amount": {
                "base": 150,
                "promotion_bonus": 0,
                "total_excluding_tax": 150,
                "total_including_tax": 150
            },
            "type": "CREDITS",
            "unit": "PHP",
            "unit_type": "CURRENCY"
        }
    ],
    "description": "150 PHP",
    "destination": {
        "amount": 150,
        "unit": "PHP",
        "unit_type": "CURRENCY"
    },
    "id": 2602,
    "name": "150 PHP",
    "operator": {
        "country": {
            "iso_code": "PHL",
            "name": "Philippines",
            "regions": [
                {
                    "code": "PHL",
                    "name": "Philippines"
                }
            ]
        },
        "id": 246,
        "name": "Globe Telecom Philippines",
        "regions": null
    },
    "prices": {
        "retail": {
            "amount": 3.12,
            "fee": 0,
            "unit": "USD",
            "unit_type": "CURRENCY"
        },
        "wholesale": {
            "amount": 2.6,
            "fee": 0,
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    },
    "promotions": null,
    "rates": {
        "base": 57.6923076923077,
        "retail": 48.0769230769231,
        "wholesale": 57.6923076923077
    },
    "regions": null,
    "required_additional_identifier_fields": null,
    "required_beneficiary_fields": null,
    "required_credit_party_identifier_fields": [["mobile_number"]],
    "required_debit_party_identifier_fields": null,
    "required_sender_fields": null,
    "required_statement_identifier_fields": null,
    "service": {
        "id": 1,
        "name": "Mobile",
        "subservice": {
            "id": 11,
            "name": "Airtime"
        }
    },
    "source": {
        "amount": 2.6,
        "unit": "USD",
        "unit_type": "CURRENCY"
    },
    "tags": ["AIRTIME"],
    "type": "FIXED_VALUE_RECHARGE",
    "validity": {
        "quantity": 365,
        "unit": "DAY"
    }
}

Required Fields - Pay Close Attention

The "required_*" fields indicate the additional data elements beyond the standard minimum payload that you must include in POST transaction requests for each corresponding party or identifier. These fields specify the necessary information for a particular product. If a field is listed as required, your transaction request will likely be unsuccessful if it is not included.

❗️
Warning
The example shown is for a particular product type delivered by a specific operator. Always, always check the "required_*" configuration for the exact product and operator you are integrating with. When the value of a "required_*" field is null, it means that no additional fields are necessary for that specific section beyond the base requirements for this product. Don't assume based on this one provided example that the field or fields listed are the only possibilities!


{
  "required_additional_identifier_fields": null,
  "required_beneficiary_fields": null,
  "required_credit_party_identifier_fields": [
    [
      "mobile_number"
    ]
  ],
  "required_debit_party_identifier_fields": null,
  "required_sender_fields": null,
  "required_statement_identifier_fields": null
}

{
  // ... other necessary fields from the minimum payload ...
  "credit_party_identifier": {
    "mobile_number": "+639173143100"
  },
  // ... other fields ...
}