How to display products from the catalog

Use the catalog endpoint to list products, run a full sync, filter by item code or product type, and paginate results. Only active SKUs are returned.

When to use this

Call GET /catalog when you need to build a product listing, sync your store with CardPlusPay’s catalog, or look up a single product by its item code.

Live stock is not on this endpoint — always call POST /orders/check before checkout. See check availability.

Step 1: Request the catalog

Endpoint: GET https://api.cardpluspay.com/v1/catalog

Optional query parameters:

• page — Page number (default 1).
• per_page — Items per page (1–100, default 50).
• sort_by — brand, value, category, or item_code (default brand). Results always tie-break by item_code ascending for stable pagination.
• order — asc or desc (default asc).
• item_id — Filter by product item code (single SKU lookup).
• product_type — Filter by vertical slug (e.g. gift_card, game_card, direct_top_up). See product type taxonomy below.
• include_test — When true, include sandbox SKUs (product_type=test). Default: excluded.
• brand — Filter by brand name.
• q — Search in product_name, brand, or item_code (max 255 chars).
• region — Filter by region (e.g. global).
• currency — Filter by currency (e.g. USD).
• delivery_type — PHYSICAL, DIGITAL, or BOTH.
• value_min / value_max — Face value range (numeric, ≥ 0).
• country_code — Single country code; products whose country_code array contains this value.

Example: full sync (recommended)

curl -X GET "https://api.cardpluspay.com/v1/catalog?per_page=100&sort_by=item_code&order=asc&page=1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Paginate until pagination.current_page >= pagination.last_page (or follow next_page_url).

Example: get one product by item code

curl -X GET "https://api.cardpluspay.com/v1/catalog?item_id=GOOGLE-5USD-KOXx&per_page=1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Example: filter by product type

curl -X GET "https://api.cardpluspay.com/v1/catalog?product_type=direct_top_up&per_page=100" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Example: search and filters

curl -X GET "https://api.cardpluspay.com/v1/catalog?region=global¤cy=USD" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

curl -X GET "https://api.cardpluspay.com/v1/catalog?q=google&delivery_type=DIGITAL" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Step 2: Handle the response

On success, data contains products (array) and pagination:

{
  "success": true,
  "message": "Products retrieved successfully",
  "data": {
    "products": [
      {
        "item_code": "GOOGLE-5USD-KOXx",
        "brand": "Google",
        "product_name": "Google Play Gift Card",
        "face_value": 5.00,
        "value": 5.00,
        "price": 4.90,
        "charged_price": 4.90,
        "currency": "USD",
        "value_unit": null,
        "denomination_unit": "USD",
        "category": "Google Play SA",
        "product_type": "app_store",
        "product_family": null,
        "denomination_type": "fixed",
        "redemption_instructions": "Redeem on Google Play.",
        "redemption_url": null,
        "code_format": "text",
        "required_fields": [],
        "region": "Global",
        "country_code": ["GLOBAL"],
        "delivery_type": "DIGITAL",
        "image_url": "https://...",
        "description": "...",
        "terms": null,
        "is_offer": false,
        "offer_percent": null,
        "offer_expires_date": null,
        "min_quantity": 1,
        "max_quantity": 100,
        "created_at": "2026-06-01T10:15:30+00:00",
        "updated_at": "2026-06-02T11:20:45+00:00"
      }
    ],
    "pagination": {
      "total": 120,
      "per_page": 50,
      "current_page": 1,
      "last_page": 3,
      "next_page_url": "https://api.cardpluspay.com/v1/catalog?page=2&per_page=50&sort_by=item_code&order=asc",
      "prev_page_url": null
    },
    "state": "available"
  }
}

Pricing fields

• price — List price per unit (before an active offer).
• charged_price — Price per unit after an active offer (equals price when no offer). Use for catalog display and cache.
• face_value / value — Face value (denomination); value is an alias of face_value.
• POST /orders/check → data.price — Authoritative per-unit charge at purchase time.

Each product includes min_quantity and max_quantity for cart limits.

When product_type is direct_top_up, the required_fields array describes buyer inputs (player ID, etc.) your checkout must collect. Validate them with POST /orders/validate-fields and send them on POST /orders as fields.

Typical flow: GET /catalog?item_id=ITEM_CODE for display metadata and quantity bounds, then POST /orders/check with the same item_id and desired quantity for live availability and final price.

Use item_code when calling check availability or create order. Store it in your database when you link your products to CardPlusPay.

Product type vs category

Two different grouping concepts:

• category — Merchandising shelf (e.g. “PUBG MOBILE UC Vouchers”, “Google Play SA”). Used by path GET /catalog/{category}.
• product_type — Product vertical (what the buyer receives). Filter with ?product_type=.

Products by merchandising category

To list products on a specific shelf, use GET /catalog/{category}. The path segment is the category string (URL-encoded), not product_type.

Example: GET https://api.cardpluspay.com/v1/catalog/PUBG%20MOBILE%20UC%20Vouchers

Same query parameters as GET /catalog. Returns 404 when no active products match that category.

← Authentication · Integration Guide · Check availability →