Quickstart
A complete, copy‑paste path from zero to a working order. Build against the sandbox base URL first (see Sandbox &
production).
BASE_URL="https://api-sandbox.palcards.ps" # production: https://api.palcards.ps
API_KEY="sk_prod_your_key_here"
1. Confirm your key & check your balance
curl -H "x-api-key: $API_KEY" "$BASE_URL/user/profile"
A 200 with wallets[].balance means your key works and your IP is allowed. A 401 means the key or IP is wrong — see
Authenticating requests.
2. Find a product to sell
curl -H "x-api-key: $API_KEY" "$BASE_URL/product/catalog?ps=20"
Pick a productItems[].id — that is the productItem you'll buy.
3. (Top‑ups only) Validate the account
curl -X POST "$BASE_URL/order/top-up/preflight" \
-H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
-d '{ "productItem": 5002, "context": { "accountId": "123456789" } }'
4. Create the order
curl -X POST "$BASE_URL/order" \
-H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
-d '{ "productItem": 5001, "customer": { "phone": "+970590000000" }, "clientOrderRef": "ref-0001" }'
You get back an order with a status. Orders finalize asynchronously — a 200 means accepted, not yet fulfilled.
5. Get the result — webhook or polling
- Pass a notificationUrl on the order and PalCards POSTs you the final order when it's done (see Order webhooks), or
- Poll until the status is terminal:
curl -H "x-api-key: $API_KEY" "$BASE_URL/order/9001"
See Order status lifecycle for which statuses are final and when the voucher (soldItem) is available.
6. Go live
Switch BASE_URL to https://api.palcards.ps, use a production API key, and run the go-live checklist in Sandbox &
production.