Products

Browse gaming and recharge products, fetch a single product with its required input fields

`GET /api/v1/topups/products`

Returns a paginated list of top-up products available to your client account. Each product represents a service (a game, a mobile operator) and exposes one or more variants (SKU-level pricing — documented separately).

Request

curl "https://api.octopuscards.io/api/v1/topups/products?type=GAMING&page=1&per_page=50" \
  -H "Authorization: Bearer <token>"

Query Parameters

Key	Type	Required	Description
`page`	integer	No	Page number (1-based). Default: `1`.
`per_page`	integer	No	Items per page. Default: `50`.
`type`	string	No	Filter by topup type. One of `GAMING`, `MOBILE`, `UTILITY`.
`search`	string	No	Case-insensitive name search.

Response

[
  {
    "id": 4218,
    "name": "PUBG Mobile UC",
    "topup_type": "GAMING",
    "country_code": "GLO",
    "currency_code": "USD",
    "image_url": "https://cdn.example.com/pubg-mobile.png"
  },
  {
    "id": 4219,
    "name": "Airtel India",
    "topup_type": "MOBILE",
    "country_code": "IND",
    "currency_code": "INR",
    "image_url": "https://cdn.example.com/airtel.png"
  }
]

Response Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total matching products
`X-Total-Pages`	Total pages
`X-Page-Size`	Items in current page
`X-Has-More`	`true` if more pages exist

Enumerations

topup_type:

Value	Meaning
`GAMING`	In-game currency, item bundles, season passes
`MOBILE`	Prepaid mobile airtime and data plans
`UTILITY`	Bill payments and other utility top-ups

Response Fields

Key	Type	Description
`id`	integer	Unique product identifier. Pass to `/topups/products/:id` and `/topups/charges`.
`name`	string	Product display name (e.g. "PUBG Mobile UC", "Airtel India").
`topup_type`	string	One of `GAMING`, `MOBILE`, `UTILITY`.
`country_code`	string	ISO 3166-1 alpha-3 code (e.g. `IND`, `GLO`).
`currency_code`	string	ISO 4217 destination currency (e.g. `INR`, `USD`).
`image_url`	string	Product image URL. May be empty.

Errors

401 Unauthorized — Missing or invalid JWT token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

`GET /api/v1/topups/products/:id`

Returns full details for a single top-up product, including the input fields the customer must provide at order time (e.g. player_id, phone_number, server_id).

Request

curl "https://api.octopuscards.io/api/v1/topups/products/4218" \
  -H "Authorization: Bearer <token>"

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Product ID (path parameter). Must be `> 0`.

Response

{
  "id": 4218,
  "name": "PUBG Mobile UC",
  "topup_type": "GAMING",
  "country_code": "GLO",
  "currency_code": "USD",
  "image_url": "https://cdn.example.com/pubg-mobile.png",
  "input_fields": [
    {
      "field_name": "player_id",
      "field_label": "Player ID",
      "field_type": "text",
      "is_required": true,
      "validation_regex": "^[0-9]{8,12}$",
      "placeholder": "e.g. 5123456789",
      "help_text": "Find this in-game under your profile."
    },
    {
      "field_name": "server",
      "field_label": "Server",
      "field_type": "select",
      "is_required": true,
      "options": [
        { "value": "asia", "label": "Asia" },
        { "value": "europe", "label": "Europe" },
        { "value": "na", "label": "North America" }
      ]
    }
  ]
}

Enumerations

field_type:

Value	Meaning
`text`	Free-text input. May have `validation_regex`.
`number`	Numeric input. Validated as a parseable float.
`phone`	Phone number. Validated as 4–15 digits, normalised to E.164 with a leading `+`.
`select`	Drop-down. Must use one of the values in `options[]`.

Response Fields

All fields from the list endpoint, plus:

Key	Type	Description
`input_fields`	array	Required customer inputs. Send them as `input_data` on the order.
`input_fields[].field_name`	string	Key to use in the `input_data` map (e.g. `player_id`).
`input_fields[].field_label`	string	Human-readable label for your UI.
`input_fields[].field_type`	string	`text`, `number`, `phone`, or `select`.
`input_fields[].is_required`	boolean	If `true`, must be present and non-empty in `input_data`.
`input_fields[].validation_regex`	string	Optional. Apply on the client; we re-validate server-side.
`input_fields[].placeholder`	string	Optional placeholder text.
`input_fields[].help_text`	string	Optional helper text below the field.
`input_fields[].options`	array	For `select` fields: the allowed `{value, label}` pairs.

Errors

400 Bad Request — id is not a valid integer.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Invalid product ID"
  }
}

On this page