How to display products from the catalog

Use the catalog endpoint to list gift card products and show them on your site. You can fetch all products, filter by item code or brand, and paginate results.

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.

Step 1: Request the catalog

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

Optional query parameters:

• item_id — Filter by product item code (e.g. to fetch one product).
• brand — Filter by brand name.
• q — Search string (max 255 chars). Filters products whose product_name, brand, or item_code contains the term. Can be combined with other filters.
• per_page — Number of items per page (1–100, default 10).
• sort_by — Sort by brand, value, or category.
• order — asc or desc.
• region — Filter by region (e.g. global, eu).
• currency — Filter by currency (e.g. USD, EUR).
• delivery_type — PHYSICAL, DIGITAL, or BOTH.
• value_min — Minimum face value (numeric, ≥ 0).
• value_max — Maximum face value (numeric, ≥ 0).
• country_code — Single country code (e.g. US); returns products whose country_code array contains this value.

Example: list first page of products

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

Example: get one product by item code

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

Example: filter and search

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" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

curl -X GET "https://api.cardpluspay.com/v1/catalog?delivery_type=DIGITAL&value_min=5&value_max=50&country_code=US" \
  -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": [
      {
        "id": 1,
        "brand": "Google",
        "price": "4.90",
        "value": "5.00",
        "value_unit": "USD",
        "item_code": "GOOGLE-5USD-KOXx",
        "product_name": "Google Play Gift Card",
        "image_url": "https://...",
        "description": "...",
        "currency": "USD",
        "delivery_type": "DIGITAL",
        "denomination_unit": "USD"
      }
    ],
    "pagination": {
      "total": 1,
      "per_page": 10,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Use price (amount charged) when calculating what you bill the customer and checking that your balance is sufficient. Use value together with value_unit or denomination_unit (or currency when units match) when showing the card’s face value in your UI (e.g. “5.00 USD Google Play card”).

To fetch a single product’s details and confirm it is in stock before checkout, first call GET /catalog?item_id=ITEM_CODE to get its price, value, and units, then call POST /orders/check with the same item_id and desired quantity to verify availability and per-unit charge.

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

Products by category

To list products in a specific category (type), use GET /catalog/{type}. For example: GET https://api.cardpluspay.com/v1/catalog/Digital. See the API Reference for supported types.

← Authentication · Integration Guide · Check availability →