Payments API for your website

Merchant tutorial · Charge from your site, WooCommerce, or Shopify

Use the JuzePOS Payments API when you already have a website, WooCommerce store, or Shopify payments app, and you want JuzePOS to take the payment, 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"
  }'

The hosted pay page takes a card. Wallet, cash, ACH, Tap to Pay, and split tender use a direct charge (section 4). Tax is $0.00 unless you send applyTax: true (section 5). A cart that already includes tax should leave applyTax off.

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. Store tax, ProofMile, and other tenders

Store tax

Send applyTax: true on a checkout or a direct charge. JuzePOS adds the location sales-tax rate, or the merchant rate when the location has none, on the goods subtotal only. The delivery fee is not taxed. Leave applyTax off when your cart total already includes tax.

curl -X POST https://juzepos.com/api/v1/checkouts \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "applyTax": true,
    "locationId": "<location-id>",
    "returnUrl": "https://your-shop.com/success",
    "cancelUrl": "https://your-shop.com/cart"
  }'

A 10% store rate on $100.00 of goods returns a total of $110.00. taxAmount is on the checkout response.

ProofMile delivery

ProofMile must already be enabled for the store and the pickup location needs a street, city, state, and ZIP. Send delivery.address. JuzePOS quotes a live fee, adds it after tax, and dispatches the courier after the payment succeeds.

curl -X POST https://juzepos.com/api/v1/checkouts \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 42.00,
    "applyTax": true,
    "returnUrl": "https://your-shop.com/success",
    "cancelUrl": "https://your-shop.com/cart",
    "delivery": {
      "phone": "+17045550100",
      "address": {
        "line1": "100 Main St",
        "city": "Charlotte",
        "state": "NC",
        "postalCode": "28202"
      }
    }
  }'

Wallet, cash, ACH, Tap to Pay, and split

Set paymentMethod on POST /v1/payments. Hosted checkout stays card-only.

curl -X POST https://juzepos.com/api/v1/payments \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1002" \
  -d '{
    "amount": 15.00,
    "paymentMethod": "split",
    "splitCashAmount": 10.00,
    "splitCardAmount": 5.00,
    "paymentToken": "pm_..."
  }'

7. List, cancel, refunds, and webhooks

• List API payments: GET /v1/payments?status=requires_payment&page=1&limit=20. Status is requires_payment, paid, failed, refunded, or canceled.
• Void one unpaid payment: POST /v1/payments/:id/cancel.
• Void up to 50: POST /v1/payments/cancel with { "ids": ["…", "…"] }. Each result is canceled or error. A paid payment must be refunded instead.
• 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.

8. WooCommerce

1. Copy plugins/woocommerce/juzepos-gateway.php into wp-content/plugins/juzepos-gateway/ and activate JuzePOS Payments.
2. Under WooCommerce → Settings → Payments, enable JuzePOS and paste the API key from Settings → Developer. API base is https://juzepos.com/api.
3. Paste the webhook signing secret, and in JuzePOS set the webhook URL to https://your-store.com/?wc-api=juzepos.
4. At checkout the plugin posts the Woo order to POST /v1/woocommerce/checkouts and sends the shopper to the JuzePOS pay page. Woo already calculated tax, so JuzePOS does not add tax again. A shipping address turns on ProofMile when the order needs delivery.
5. A payment.succeeded webhook marks the Woo order paid. Refunds from Woo call POST /v1/payments/:id/refunds.

9. Shopify

1. This is a Shopify payments app, not Authorize.net. Shopify will not list JuzePOS until the app is installed on the shop.
2. Set JUZEPOS_API_KEY to the merchant’s jz_live_… key and run plugins/shopify/server.mjs. Point the payments app payment URL at that server’s POST /payment.
3. The server posts the Shopify payment session to POST /v1/shopify/payment-sessions and returns the JuzePOS checkoutUrl as redirect_url.
4. Shopify has already taxed the cart, so JuzePOS does not add store tax. A shipping address on the session is quoted as ProofMile delivery.

curl -X POST https://juzepos.com/api/v1/shopify/payment-sessions \
  -H "Authorization: Bearer jz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "sess_1",
    "gid": "gid://shopify/PaymentSession/1",
    "amount": "18.50",
    "currency": "USD",
    "cancel_url": "https://your-store.myshopify.com/cart",
    "kind": "sale"
  }'

What v1 covers

v1 takes a payment from your own site and from a WooCommerce or Shopify cart:

• Hosted checkout and direct charge
• Card, wallet, cash, ACH, Tap to Pay, and split tender on POST /v1/payments (paymentMethod)
• Store tax when you send applyTax: true (goods only; delivery is not taxed). Leave it off when your cart total already includes tax
• ProofMile delivery when you send delivery.address. The live fee is added to the total and dispatched after payment
• List payments with GET /v1/payments, void one with POST /v1/payments/:id/cancel, or void many with POST /v1/payments/cancel
• Catalog, stock, refunds, signed webhooks, and idempotency

WooCommerce: install plugins/woocommerce/juzepos-gateway.php and set the API key. Shopify: run plugins/shopify/server.mjs and point the payments app at POST /payment. Both open a JuzePOS hosted checkout. Payouts use the same ACH schedule as in-store card sales. Shopify shows JuzePOS only after that payments app is installed. It is not an Authorize.net gateway.

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. A custom cart calls POST /v1/checkouts or POST /v1/payments. WooCommerce uses the JuzePOS gateway plugin, which posts the order to POST /v1/woocommerce/checkouts. Shopify’s payments app posts the session to POST /v1/shopify/payment-sessions (or to the bundled plugins/shopify server). Those carts already include tax, so the adapters do not add store tax again. This is not an Authorize.net connection.

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