Appendix

Glossary

Item code
Unique product identifier (e.g. GOOGLE-5USD-KOXx). Used in catalog, stock check, and order creation. Same as item_id in query/body parameters.
Envelope
Standard response shape: success (boolean), message (string), data (object). All API responses use this structure.
order_id
Numeric ID returned when you create an order. Use it with GET /orders/{id} to fetch order status and codes.
order_no
Human-readable order reference (e.g. ORD-2026-001) for display and support.
Stock check
Request to see if a product is available in a given quantity. Use POST /orders/check with item_id and quantity. Not the same as checking the status of an existing order.
category
Merchandising shelf label (e.g. “Google Play SA”). Filter with path GET /catalog/{category}.
product_type
Product vertical slug (e.g. gift_card, game_card, direct_top_up). Filter with ?product_type= on GET /catalog.
face_value / value
Denomination amount on catalog rows. value is an alias of face_value.
price / charged_price
Catalog list price (price) vs per-unit price after active offer (charged_price). Use POST /orders/check for the authoritative charge at purchase.
min_quantity / max_quantity
Per-SKU order bounds. Returned on GET /catalog and POST /orders/check. Platform maximum is 100.
available_quantity
Units CardPlusPay can fulfill now (POST /orders/check). null means unknown — keep a safe fallback in your integration.
pending
Order status while CardPlusPay is still fulfilling. HTTP 200 with status: pending is success — poll GET /orders/{id} until completed or failed. Wallet stays debited while pending.
delivery
Object on direct top-up order responses: { "mode": "direct_top_up", "status": "pending|completed|failed" }. Success for top-up is delivery.status = completed, not codes.
fields
Buyer account inputs on POST /orders for direct_top_up SKUs. Keys match catalog required_fields[].key. Not echoed back in API responses.
required_fields
Catalog schema for inputs required on direct top-up SKUs. See validate fields.
Idempotency-Key
Optional header on POST /orders. One stable value per logical purchase attempt (UUID recommended). Same key + same body replays the original result; use a new key only for a new purchase.
quantity_contract_version
Version of the quantity fields on POST /orders/check (currently 1). Bump client caches when this changes.

Resources

API versioning

The current API version is v1, with base URL https://api.cardpluspay.com/v1. Future versions (e.g. v2) may be introduced with a different path. Check the API info endpoint (GET /) or documentation for the current version and any deprecation notices.

← Troubleshooting · Integration Guide