jadePOS API Reference

Conventions

GET/api/v1/ping

Liveness check. The only endpoint that needs no key.

curl https://jadepos.store/api/v1/ping
→ {"ok":true,"service":"jadepos.store"}

GET/api/v1/me

The merchant who owns the key — use it to verify a key and read your ledger currency.

curl -H "Authorization: Bearer jade_..." https://jadepos.store/api/v1/me
→ {"username":"demo","business_name":"Jade Cafe","currency":"USD"}

GET/api/v1/products

Your full catalog, active and archived.

curl -H "Authorization: Bearer jade_..." https://jadepos.store/api/v1/products
→ {"products":[{"sku":"latte","name":"Latte","description":"Double shot",
     "kind":"product","price_cents":450,"currency":"USD","tax_percent":8.5,
     "requires_shipping":false,"active":true}]}

POST/api/v1/products

Create a catalog item, or update it if the SKU already exists (upsert).

curl -X POST https://jadepos.store/api/v1/products \
  -H "Authorization: Bearer jade_..." \
  -d sku=beans-1kg -d "name=Coffee Beans 1kg" -d price_cents=1899 -d requires_shipping=1
→ {"ok":true,"sku":"beans-1kg","created":true}

GET/api/v1/orders

Your orders, newest first, 50 per page. Draft carts are never included.

curl -H "Authorization: Bearer jade_..." "https://jadepos.store/api/v1/orders?status=paid&page=1"
→ {"orders":[{"ref":"JP-2524f49c22","status":"paid","total_cents":800,
     "currency":"USD","customer_name":"Lin","created_at":"2026-08-27 09:12:44",
     "paid_at":"2026-08-27 09:12:45"}]}

GET/api/v1/transactions

The money ledger: one row per charge or refund attempt, newest first, 50 per page (page param). Card rows carry only the brand and last four digits — never the full number.

curl -H "Authorization: Bearer jade_..." https://jadepos.store/api/v1/transactions
→ {"transactions":[{"tx_ref":"TX-63505a62be6f","order_ref":"JP-e4a6c4dd8d",
     "kind":"charge","method":"card","mode":"test","status":"approved",
     "amount_cents":1250,"currency":"USD","card_brand":"amex",
     "card_last4":"0005","auth_code":"F94FAC","created_at":"2026-08-26 16:04:46"}]}

POST/api/v1/charges

Validate and charge a card, or record a PayPal / Cash App payment you already received. Creates a one-line order, charges it, and returns the outcome with a public receipt URL.

Common fields

Card fields (method=card)

Wallet fields (method=paypal | cashapp)

curl -X POST https://jadepos.store/api/v1/charges \
  -H "Authorization: Bearer jade_..." \
  -d method=card -d amount_cents=1250 -d currency=USD \
  -d "description=Latte x2" \
  -d card_number=4242424242424242 -d exp_month=12 -d exp_year=2030 -d cvv=123

→ 200 {"approved":true,"order_ref":"JP-1a2b3c4d5e","auth_code":"A1B2C3",
       "card_brand":"visa","card_last4":"4242","amount_cents":1250,
       "currency":"USD","receipt_url":"https://jadepos.store/receipt?ref=JP-1a2b3c4d5e"}

→ 402 {"approved":false,"order_ref":"JP-8f54674005","card_brand":"visa",
       "error":"Card declined (test card)"}

Whether a card charge is simulated (test) or sent to your processor (live) follows the card method's mode in Payments. The receipt URL is public but unguessable; it shows no card data beyond brand + last4.

Card validation

Every card is validated before any charge is attempted. A failure answers 402 with a reason and nothing is sent to the processor.

Plus the Luhn checksum and an expiry check against the current date. Other networks are rejected.

Test cards (test mode)

Any future expiry and matching-length CVV work with these:

Live card gateway relay

In live mode jadePOS POSTs each card charge as JSON to the HTTPS relay URL configured in Payments (loopback http://127.0.0.1 is also accepted for a relay on the same machine), with your relay key in the body:

{"api_key":"...","reference":"pre-...","amount_cents":1250,"currency":"USD",
 "card_number":"...","exp_month":"12","exp_year":"2030","cvv":"..."}

The relay must answer within ~20 seconds:

{"status":"approved","auth_code":"..."}
{"status":"declined","error":"..."}

A ready-to-run relay for NMI and Authorize.net ships with the project: deploy/card_relay.py (Python stdlib, no installs) with deploy/relay_config.json choosing the processor and holding its credentials — they never enter jadePOS. It ships pointed at NMI's public sandbox until you swap in real keys; for Authorize.net, create free sandbox credentials at developer.authorize.net and set sandbox: true until go-live.

Status codes