jadePOS API

Automatice su tienda: cree cobros, gestione productos y lea su libro mayor. Autentíquese con una clave API de su cuenta.

Authentication

Create a key under Account → API keys and send it as a bearer token:

Authorization: Bearer jade_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests use application/x-www-form-urlencoded bodies; responses are JSON. Amounts are integers in minor units (cents). Keys are stored hashed and can be revoked at any time.

Endpoints

Method	Path	Description
GET	`/api/v1/ping`	Liveness check (no auth)
GET	`/api/v1/me`	The authenticated merchant
GET	`/api/v1/products`	List your catalog
POST	`/api/v1/products`	Create or update a SKU: `sku, name, price_cents` + optional `description, kind=product\|service, currency, tax_percent`
GET	`/api/v1/orders`	List orders (`?status=paid&page=1`)
GET	`/api/v1/transactions`	List charges & refunds
POST	`/api/v1/charges`	Validate & charge a card, or record a received PayPal / Cash App payment

Charging a card

Visa, Mastercard, Discover, and American Express are detected from the number and validated (Luhn, length, expiry, CVV) before the charge. The full number and CVV are never stored.

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

Approved response:

{"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-..."}

A decline answers HTTP 402 with {"approved":false,"error":"..."}.

Recording a wallet payment you already received: method=paypal or method=cashapp with amount_cents and an optional reference.

Optional shipping address on any charge — ship_name, ship_address1, ship_address2, ship_city, ship_region, ship_postal, ship_country; when ship_address1 is present the order gets a printable label at /label?ref=... (merchant login required). Products can also carry requires_shipping=1.

Live card gateway relay

In test mode charges are simulated in-process (use the test numbers on the Payments page). In live mode jadePOS POSTs the charge as JSON to the HTTPS relay URL you configure, 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 answers {"status":"approved","auth_code":"..."} or {"status":"declined","error":"..."} — it is the component that talks to your acquirer or processor (Stripe, Adyen, an ISO gateway), keeping processor SDKs and PCI scope out of the till.

A ready-to-run relay for NMI and Authorize.net ships with the project: deploy/card_relay.py (Python stdlib, no installs). Run it on the same machine as the till, point the relay URL at http://127.0.0.1:6695/charge (loopback is accepted precisely so the card number never crosses the network), and pick the processor + credentials in deploy/relay_config.json. It ships pointed at NMI's public sandbox until you swap in your own keys; for Authorize.net, create free sandbox credentials at developer.authorize.net and set sandbox: true until go-live.