How to create an order (purchase a gift card)

When a customer completes checkout, call POST /orders to create the order. On success you receive an order ID and, when available, the gift card codes to deliver.

When to use this

Call this after the customer has paid (or your system has authorized payment). You should have already checked availability for the same item and quantity. Use the item_code from the catalog.

Step 1: Send the order request

Endpoint: POST https://api.cardpluspay.com/v1/orders

Body (JSON):

• item_code (required) — Product item code (e.g. GOOGLE-5USD-KOXx). You can also use item_id as an alias.
• quantity (optional) — Number of cards; default 1, max 100.
• email (optional) — Recipient email for delivery or records.

Example request

curl -X POST "https://api.cardpluspay.com/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"item_code": "GOOGLE-5USD-KOXx", "quantity": 1}'

Step 2: Handle the response

On success, data includes identifiers, amounts, and the gift card codes to deliver:

{
  "success": true,
  "message": "Gift card purchased successfully",
  "data": {
    "type": "bulk",
    "brand": "GOOGLE-5USD-KOXx",
    "codes": [
      {
        "code": "XXXX-XXXX-XXXX-XXXX",
        "currency": "USD",
        "item_code": "GOOGLE-5USD-KOXx",
        "denomination": "5.00",
        "charged_amount": "4.90",
        "denomination_unit": "USD"
      },
      {
        "code": "YYYY-YYYY-YYYY-YYYY",
        "currency": "USD",
        "metadata": [
          { "Pin": "7694269" }
        ],
        "item_code": "GOOGLE-5USD-KOXx",
        "denomination": "5.00",
        "charged_amount": "4.90",
        "denomination_unit": "USD"
      }
    ],
    "state": "completed",
    "amount": "14.70",
    "status": "completed",
    "order_id": 123,
    "order_no": "ORD-2026-001",
    "created_at": "2026-03-07T21:42:27+02:00",
    "denomination_unit": "USD",
    "total_denomination": 15
  }
}

• order_id — Use this to check order status later (e.g. GET /orders/123).
• order_no — Human-readable order reference for your records and support.
• amount — Total amount charged for this order (sum of charged_amount across all codes). Use this for your receipts and balance reconciliation.
• total_denomination — Sum of the face values for all codes (e.g. 3 × 5.00 = 15). Use this for display (what the customer gets), not for billing.
• codes — Array of gift card codes to deliver to the customer (e.g. on a thank-you page or by email). Each code includes:
  • code — The redeemable code.
  • charged_amount — Amount you are charged for this specific code (can be less than denomination when discounted).
  • denomination and denomination_unit — Face value to show to the customer (e.g. “5.00 USD”).
  • metadata (optional) — Extra data such as a separate PIN, when provided.

Store order_id in your database so you can look up the order or fetch updated codes if delivery is asynchronous.

Error handling

Common responses:

• 400 — Bad request: invalid item, insufficient balance, or out of stock. Check message and ensure you validated stock with POST /orders/check before checkout.
• 401 — Invalid or missing API key.
• 422 — Validation error (e.g. missing item_code or invalid format).

← Check availability · Integration Guide · Order status →