Concepts

Key ideas you need before integrating: base URL, item codes, price vs face value (charged vs denomination), the response envelope, and the difference between checking stock and checking order status.

Base URL and versioning

All API requests go to:

https://api.cardpluspay.com/v1

The path /v1 is the API version. Append the endpoint path to this base (e.g. https://api.cardpluspay.com/v1/balance, https://api.cardpluspay.com/v1/catalog). Future versions may use /v2; the current production version is v1.

Item codes

Products in the catalog are identified by an item code (sometimes referred to as item_id in query parameters). For example: GOOGLE-5USD-KOXx.

  • Use the same identifier when calling the catalog, checking stock, and creating orders.
  • Get item codes from GET /catalog or GET /catalog?item_id=...; store the code in your database or config when you link your products to CardPlusPay.

Price vs face value (charged vs denomination)

Across the API, two kinds of amounts appear. Use them correctly:

  • Amount charged — What is actually debited from your account (or what you charge the customer). In the catalog and stock-check responses this is price; in the order response it is charged_amount per code and amount for the total. Use these for balance checks, checkout totals, and receipts.
  • Face value (denomination) — The card’s nominal value for display (e.g. “$5 Google Play card”). In the catalog this is value; in the order response it is denomination per code and total_denomination for the sum. Use these only for showing what the customer gets (e.g. “$5 USD”), not for billing.

Charged amount can be less than denomination (e.g. promotional or discounted pricing). Always use the charged amount for any financial logic.

Response envelope

Every API response uses a common structure:

{
  "success": true | false,
  "message": "Human-readable message",
  "data": { ... }
}
  • success — Whether the request succeeded. Always check this before trusting data.
  • message — Short description (e.g. "Balance retrieved successfully" or an error message).
  • data — The payload. Structure depends on the endpoint (e.g. balance, products, order_id, codes).

On failure, success is false and message (and optionally data) describes the error.

Stock check vs order status

Do not confuse these two operations:

Goal Endpoint Use when
Check if a product is available (stock) POST /orders/check Before add-to-cart or checkout. Send item_id (item code) and quantity. Response tells you if that quantity is in stock.
Get status of an existing order GET /orders/{id} After creating an order. Send the order_id from the create response. Use this to show status and retrieve gift card codes.

Use POST /orders/check for “Is this product in stock?” and GET /orders/{id} for “What’s the status of order #123?”

Typical purchase flow

A common end-to-end flow for buying a gift card looks like this:

  1. Check balance — Optional but recommended. Call GET /balance to ensure you have enough funds for the planned purchase.
  2. Get product info — Use GET /catalog (or GET /catalog?item_id=...) to display products and store the item_code you want to sell.
  3. Check stock and price — Before checkout, call POST /orders/check with item_id and quantity. Use data.price as the per-unit amount you will be charged and confirm state is "in_stock".
  4. Create the order — After payment is authorized, call POST /orders with item_code and quantity. On success, use order_id, amount (total charged), total_denomination (total face value), and the codes array to fulfill the order.
  5. Track status (optional) — Call GET /orders/{id} later with order_id if you need to refresh status or re-fetch codes.

← Integration Guide · Authentication →