Orders are fulfilled asynchronously. A successful POST /order means the order was accepted — not yet fulfilled. Track the order's status to know the outcome.
Statuses
| Status | Meaning | Final? | Webhook fires? | soldItem |
|---|---|---|---|---|
pending |
Accepted, not yet processing | No | No | — |
in-progress |
Being fulfilled | No | No | — |
success |
Fulfilled | Yes | Yes | Populated |
failed |
Could not be fulfilled | Yes | Yes | — |
rejected |
Rejected | Yes | Yes | — |
Terminal statuses (success, failed, rejected) never change — stop polling once you see one. pending and in-progress are transient.
Knowing an order is done
- Webhook (recommended): pass a
notificationUrlon the order; PalCards POSTs you the full order when it reaches a terminal status (success,failed, orrejected). Webhooks are unsigned and sent once — confirm by re-fetchingGET /order/{id}(see Order webhooks). - Polling: call
GET /order/{id}every few seconds untilstatusis terminal.
On success
For a voucher (chargingCard), the delivered card is in soldItem:
"soldItem": { "id": 7001, "voucher": { "code": "XXXX-XXXX", "pin": "123456" } }
Top‑up (topUp) orders also reach success (the target account is charged), but generally carry no voucher payload.
On failure
failed / rejected orders do not leave a net charge on your wallet — the charge is rolled back. Inspect the order for the reason and, if appropriate, submit a new order (there is no automatic retry, and re-using the same clientOrderRef does not prevent a duplicate — see Create an order).