Home API Reference Create an order

Create an order

Last updated on Jun 07, 2026

Create an order to buy a product item — a voucher (charging card) or a top‑up. The type is detected automatically from the product.

Send Content-Type: application/json. Base URL https://api.palcards.ps (or sandbox — see Sandbox & production).

1. (Top‑ups) Validate the account first — preflight

For top‑up products, validate the target account and get the account holder's nickname before charging:

curl -X POST "https://api.palcards.ps/order/top-up/preflight" \
  -H "x-api-key: sk_prod_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "productItem": 5002, "context": { "accountId": "123456789" } }'

{ "success": true, "message": "OK", "nickname": "PlayerOne" }

2. Create the order

curl -X POST "https://api.palcards.ps/order" \
  -H "x-api-key: sk_prod_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "productItem": 5001,
    "customer": { "phone": "+970590000000" },
    "orderCurrency": "USD",
    "clientOrderRef": "ref-0001",
    "notificationUrl": "https://your-server.example/webhooks/palcards"
  }'

POST /order

Body

Field Type Required Description
productItem number Yes Product item ID (from the catalog)
customer.phone string Yes Customer phone, international format, e.g. +97059…
orderCurrency string No ISO‑4217 currency code, e.g. USD. Defaults to your default wallet's currency. You must have a wallet in this currency
context object Conditional Required‑info fields for the product (e.g. accountId, serverId) — see the product's customerRequiredInfo
clientOrderRef string (≤512) No Your own reference, echoed back in responses & webhooks. Not an idempotency key — see the warning below
notificationUrl string No Your HTTPS webhook URL; receives the final order (see Order webhooks)

Response

{
  "id": 9001,
  "status": "in-progress",
  "type": "chargingCard",
  "orderCurrency": "USD",
  "clientOrderRef": "ref-0001",
  "appliedDealerPrices": { "price": 9.5, "discount": 0.5, "discountPercent": 5, "revenue": 0.5, "revenuePercent": 5 },
  "soldItem": null,
  "createdAt": "2026-06-07T12:00:00.000Z",
  "updatedAt": "2026-06-07T12:00:00.000Z"
}
  • status: pending → in-progress → success | failed | rejected. Fulfillment is asynchronous — a 200 means accepted, not fulfilled. See Order status lifecycle.
  • On success, a voucher's card is in soldItem: { "id": 7001, "voucher": { "code": "…", "pin": "…" } }.
  • Track completion with a webhook (notificationUrl) or by polling GET /order/{id} (see Retrieve orders).

⚠️ clientOrderRef is not idempotent

clientOrderRef is stored and echoed back only — it does not de‑duplicate. Two POST /order calls with the same clientOrderRef create two orders and charge you twice. To avoid accidental duplicates, treat a network timeout as unknown (not failed): before retrying, look for the order via GET /order (e.g. by date), and only retry if you received no order id.

Currency & wallets

  • The order is charged from your wallet whose currency equals orderCurrency.
  • Omitting orderCurrency uses your default wallet's currency.
  • A currency you have no wallet for → 400 "Required wallet for currency 'X' is missing."
  • A balance below the price → 400 "Insufficient balance" and no order is created (you are not charged). See Wallet & balance.

Rate limits

Order creation is not currently rate‑limited, but design your client to handle HTTP 429 on any endpoint (see Errors & rate limits) and avoid hammering the API.