Payments API for your website

Merchant tutorial · Charge cards from a custom site or shopping cart

Use the JuzePOS Payments API when you already have (or are building) your own online store, booking page, or cart, and you want JuzePOS to take the card, keep inventory in sync with the counter, and pay out to the same bank account as in-store sales.

1. Pick a path

2. Create an API key

1. Sign in as owner or manager.
2. Open Settings → Developer.
3. Name a key (for example “Website production”) and create it. Copy the secret jz_live_… immediately — JuzePOS shows it once.
4. Keep the secret on your server only. Never put it in browser JavaScript, a mobile app, or a public Git repo.
5. Optionally add an HTTPS webhook URL on the same screen so your site is notified when a payment succeeds, fails, or is refunded.

Send the secret on every request as Authorization: Bearer jz_live_… or X-Api-Key: jz_live_…. Production base URL: https://juzepos.com/api. Rate limit: 300 requests per minute per key.

3. Hosted checkout (recommended first)

1. Your server calls POST /v1/checkouts with either a dollar amount or catalog lineItems, plus returnUrl and cancelUrl.
2. Redirect the shopper to the returned checkoutUrl.
3. After they pay, JuzePOS sends them to your returnUrl with checkout_id. Cancel uses cancelUrl.
4. Confirm the sale with GET /v1/checkouts/:id or GET /v1/payments/:id (the id is the JuzePOS order id), and/or wait for the payment.succeeded webhook. Do not mark an order paid only because the shopper hit the success page.

curl -X POST https://juzepos.com/api/v1/checkouts \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": 42.00,
    "returnUrl": "https://your-shop.com/success",
    "cancelUrl": "https://your-shop.com/cart",
    "reference": "order-1001"
  }'

Hosted checkout is card-only. Send a tax-inclusive amount if you calculate tax on your site — API checkouts store tax as $0.00 so JuzePOS does not stack store tax on top of your total.

4. Direct charge (keep checkout on your domain)

1. From your server, call GET /v1/payments/config and pass the publishable Stripe or Square keys to your browser.
2. Collect the card with Stripe.js / Payment Element or the Square Web Payments SDK. That produces a token such as pm_… / pi_… (Stripe) or cnon:… / ccof:… (Square).
3. Your server calls POST /v1/payments with that paymentToken and the amount or line items.
4. Look at status: succeeded, failed, or pending. Later you can poll GET /v1/payments/:id.

curl -X POST https://juzepos.com/api/v1/payments \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{ "amount": 42.00, "paymentToken": "pm_...", "reference": "order-1001" }'

5. Catalog and shared stock

GET /v1/products and GET /v1/categories return live prices and on-hand stock (query: page, limit, search, categoryId).

Prefer product-backed line items so JuzePOS owns the price and decrements the same inventory as the POS:

curl -X POST https://juzepos.com/api/v1/checkouts \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [{ "productId": "<id>", "variantId": "<id?>", "quantity": 1 }],
    "returnUrl": "https://your-shop.com/success",
    "cancelUrl": "https://your-shop.com/cart"
  }'

A client-supplied unitPrice is ignored when productId is set.

6. Refunds, idempotency, webhooks

• Refund: POST /v1/payments/:id/refunds. Omit amount for a full refund.
• Send Idempotency-Key on checkout and charge. The same key within 24 hours returns the original order and will not double-charge.
• Webhook events: payment.succeeded, payment.failed, refund.completed. Verify X-Juze-Signature (t=<unix>,v1=<hex HMAC-SHA256 of t.rawBody>) with the signing secret shown once. Failed deliveries retry for about 8 hours. Example verifier: Developers → Webhooks.

What v1 covers (and what it does not)

v1 is complete for taking card payments from your own site: hosted pay page, token charge, catalog + stock, retrieve payment/checkout, refunds, signed webhooks, and idempotency. Payouts use the same ACH schedule as in-store card sales.

Not in this API (use POS, marketplace, or Settings instead):

• Wallet, cash, ACH, Tap to Pay, or split tender
• ProofMile delivery on an API checkout
• Listing or canceling payments in bulk (void unpaid orders in the dashboard Orders screen)
• Automatic store tax on API totals (include tax in the amount you send)

Common questions

Do I need a developer?

Hosted checkout is a few server calls plus a redirect. Direct charge needs someone who can put Stripe or Square’s card form on your site. JuzePOS support can point you at the docs; we do not build custom storefronts as part of standard support.

Can I use this with Shopify / WooCommerce / a custom cart?

Yes, if that platform can call HTTPS APIs from the server when the customer is ready to pay. There is no official Shopify/Woo plugin; your developer maps the cart to POST /v1/checkouts or POST /v1/payments.

The card was charged twice

Always send a stable Idempotency-Key (your order id is a good choice) and treat retries as the same request. Confirm with GET /v1/payments/:id before creating another charge.

Related

Questions: support@juzepos.com