POS Itemised Payment Contract#

Updated: 2026-10-26

This is the mobile/POS contract for submitting an itemised cart through the five supported
Transaction APIs. It complements Device Integration and
Product Catalog.

Endpoints#

The inventory-finality column assumes POS inventory settlement is enabled in that environment.
The client cannot read or control that server-side rollout setting, and payment success by itself
never proves that stock was deducted.

Do not use POST /api/v1/public/transaction for a POS cart. Its compatibility whitelist does not
forward lineItems.

Authentication and headers#

Mobile must send:

Authorization: Bearer <user-jwt>
X-Device-Token: <device-token>
X-Tenant-ID: <tenant-id>
Content-Type: application/json

The device token supplies the current server-authoritative merchant, device, and physical branch.
Do not send a cashier-selected stock location or calculate Available on the device.

The full catalog, location, and stock preflight in this document applies because these requests
carry verified device context. Non-device API integrations retain the quantity-limit-only contract
documented in Transactions, section "Itemised sale (lineItems)".

For /sale, /auth, /token-sale, and /ach-sale, also send:

Idempotency-Key: <stable-uuid-for-this-payment-attempt>

The key must be 16–255 characters. A network retry must reuse the same key and identical body. A
new payment attempt must use a new key. Reusing a key with a different body returns
422 IDEMPOTENCY_KEY_REUSED; a concurrent duplicate may return 409 until the first attempt
finishes. /external-payment is instead idempotent by (tenantId, gatewayTransactionId); always
reuse the provider's original transaction id.

For the first four endpoints, merchantId must be the merchant selected by the authenticated
mobile session and must match the device context. /external-payment derives the merchant from
X-Device-Token and does not need merchantId in its body.

The client must preserve that match; the current runtime does not yet reject every mismatched body
merchant/device combination on the first four routes. Refresh the device session after login or a
merchant switch and never reuse a cart/payment body from the previous merchant.

Cart contract#

All five endpoints accept the same optional lineItems array:

lineItems[].type is a transaction-line classification, not the catalog item's
GET /device/products type. Map mobile cart rows as follows:

Do not send lineItems[].type: "service"; the Transaction API accepts only product or misc
and returns 400 INVALID_LINE_ITEMS for any other value. In this contract, product means
“catalog-backed line”, so it intentionally includes both catalog products and catalog services.

Additional rules:

• Maximum 200 lines. [], null, or omitted means no cart.
• Sum of normalized lineTotal must equal baseAmount within $0.01.
• If baseAmount is omitted, the server derives it as
  amount - tipAmount - taxAmount - convenienceFee.
• Duplicate product lines are allowed. The server aggregates their quantities to three decimals
  for maxQuantity and inventory validation, while preserving the individual receipt lines.
• Product lines are revalidated against the live product, current device branch, maxQuantity,
  tracking policy, allowZeroStockSale, and server-calculated Available.
• misc lines never create catalog products and never affect inventory or most-sold counts.
• The saved cart is immutable receipt history; later catalog edits do not rewrite it.

Example cart and amount breakdown:

{
  "amount": 19.98,
  "baseAmount": 18.48,
  "taxAmount": 1.5,
  "tipAmount": 0,
  "convenienceFee": 0,
  "lineItems": [
    {
      "type": "product",
      "productId": "3f2b8c1e-4d5a-4e6f-8a7b-9c0d1e2f3a4b",
      "name": "Diesel",
      "quantity": 2.5,
      "unit": "gallon",
      "unitPrice": 4.19
    },
    {
      "type": "misc",
      "name": "Car wash",
      "quantity": 1,
      "unitPrice": 8.0
    }
  ]
}

The normalized product line total is 10.48; the misc line total is 8.00; therefore
baseAmount is 18.48.

1. Sale#

{
  "merchantId": "{{merchantId}}",
  "amount": 19.98,
  "baseAmount": 18.48,
  "taxAmount": 1.5,
  "tipAmount": 0,
  "currency": "USD",
  "paymentMethod": "Cash",
  "lineItems": [
    {
      "type": "product",
      "productId": "{{productId}}",
      "name": "Diesel",
      "quantity": 2.5,
      "unit": "gallon",
      "unitPrice": 4.19
    },
    {
      "type": "misc",
      "name": "Car wash",
      "quantity": 1,
      "unitPrice": 8
    }
  ]
}

Card sale#

Use the same amount/cart fields plus a PCI token:

{
  "merchantId": "{{merchantId}}",
  "amount": 19.98,
  "baseAmount": 18.48,
  "taxAmount": 1.5,
  "currency": "USD",
  "paymentMethod": "Card",
  "pciToken": "{{pciToken}}",
  "lineItems": [
    {
      "type": "product",
      "productId": "{{productId}}",
      "name": "Diesel",
      "quantity": 2.5,
      "unit": "gallon",
      "unitPrice": 4.19
    },
    {
      "type": "misc",
      "name": "Car wash",
      "quantity": 1,
      "unitPrice": 8
    }
  ]
}

Never send PAN or CVV to this endpoint. Obtain pciToken from the hosted PCI fields/SDK. Sandbox
testers may use the documented secret-key tokenization endpoint, but raw card data must not enter
mobile, Postman collections shared with the team, logs, or Production.

Success: 201 { "success": true, "data": <transaction> }.

2. Authorization#

Body: the card-sale body above with a fresh Idempotency-Key. A successful AUTH stores the cart but
does not deduct inventory. Capture it later with:

Only the successful capture queues inventory settlement. Capture requires the ordinary capture
permission and its own idempotency key.

{
  "merchantId": "{{merchantId}}",
  "amount": 19.98,
  "baseAmount": 18.48,
  "taxAmount": 1.5,
  "currency": "USD",
  "gatewayToken": "{{gatewayToken}}",
  "paymentMethodId": "{{paymentMethodId}}",
  "transactionType": "sale",
  "lineItems": [
    {
      "type": "product",
      "productId": "{{productId}}",
      "name": "Diesel",
      "quantity": 2.5,
      "unit": "gallon",
      "unitPrice": 4.19
    },
    {
      "type": "misc",
      "name": "Car wash",
      "quantity": 1,
      "unitPrice": 8
    }
  ]
}

{
  "merchantId": "{{merchantId}}",
  "amount": 19.98,
  "baseAmount": 18.48,
  "taxAmount": 1.5,
  "currency": "USD",
  "pciAchToken": "{{pciAchToken}}",
  "accountType": "checking",
  "accountHolderName": "Test Customer",
  "secCode": "PPD",
  "lineItems": [
    {
      "type": "product",
      "productId": "{{productId}}",
      "name": "Diesel",
      "quantity": 2.5,
      "unit": "gallon",
      "unitPrice": 4.19
    },
    {
      "type": "misc",
      "name": "Car wash",
      "quantity": 1,
      "unitPrice": 8
    }
  ]
}

{
  "gatewayTransactionId": "{{providerTransactionId}}",
  "paymentMode": "NEARPAY",
  "type": "sale",
  "amount": 19.98,
  "baseAmount": 18.48,
  "taxAmount": 1.5,
  "tipAmount": 0,
  "convenienceFee": 0,
  "currency": "USD",
  "cardLast4": "4242",
  "cardBrand": "Visa",
  "orderId": "MOBILE-ORDER-1001",
  "lineItems": [
    {
      "type": "product",
      "productId": "{{productId}}",
      "name": "Diesel",
      "quantity": 2.5,
      "unit": "gallon",
      "unitPrice": 4.19
    },
    {
      "type": "misc",
      "name": "Car wash",
      "quantity": 1,
      "unitPrice": 8
    }
  ]
}

Responses and cart errors#

The first four endpoints return 201 on success. /external-payment returns 201 or 200 as
described above. Success bodies use:

{
  "success": true,
  "data": {
    "id": "<transaction-row-id>",
    "transactionId": "<display/reference-id>",
    "status": "approved|settled|pending|...",
    "lineItems": [
      {
        "type": "product",
        "productId": "<uuid>",
        "name": "Diesel",
        "quantity": 2.5,
        "unit": "gallon",
        "unitPrice": 4.19,
        "lineTotal": 10.48
      }
    ]
  }
}

Important errors:

error.details.violations identifies every affected product. INVALID_LINE_ITEMS supplies the
line index when the failure belongs to one line. A subtotal mismatch supplies lineItemsTotal and
baseAmount.

Inventory behavior mobile must assume#

• allowZeroStockSale=false: the first four endpoints reject insufficient stock before provider
  work. No payment and no deduction occur.
• allowZeroStockSale=true: payment may complete. Under the balance lock, Available 2 / sell 5
  records deducted 2, not deducted 3, and leaves Available at 0. Later Quantity In does not consume
  the historical shortfall.
• AUTH and pending ACH do not deduct. Capture and ACH settlement deduct once.
• Duplicate requests, callbacks, reconciliation, and worker retries do not deduct twice.
• Settlement delivery retries are server-managed and bounded. A terminal delivery failure is
  retained for operational review; it does not create a second payment or change payment success.
• Refund, void, reversal, dispute, ACH return, and customer return do not automatically restock.
  Physical returns require an explicit Quantity In / Customer Return movement.
• Payment success is never rolled back because post-payment inventory work failed.
• Refresh GET /api/v1/device/products after final sale/capture/settlement; the previous Available
  value is advisory and may already be stale.

Postman verification workflow#

For local testing, import the ready-made collection and environment described in
"POS Inventory Local Postman". The steps below remain useful when recreating
the requests manually or adapting them for UAT.

Create environment variables:

baseUrl = https://uat.auxcore.net
tenantId
userJwt
deviceToken
merchantId
productId
pciToken              # card sale/auth only
gatewayToken          # saved-card flow only
paymentMethodId       # when required by the saved method
pciAchToken            # ACH only
providerTransactionId # external-payment only
idempotencyKey         # stable for one attempt; replace for a new attempt

Use {{baseUrl}}/api/v1/... in each request. Before payment:

1. Confirm the paired device session/test-connection is usable.
2. Call GET {{baseUrl}}/api/v1/device/products?limit=200 with both tokens.
3. Select a real data[].id, copy its name/unit/price, and note trackInventory,
   allowZeroStockSale, available, and eligible.
4. Build lineItems and make its sum equal baseAmount.
5. Generate a UUID for idempotencyKey; keep it unchanged only when retrying the exact request.

For the first four requests, this optional Postman pre-request script creates a key only when the
environment does not already have one:

if (!pm.environment.get('idempotencyKey')) {
  pm.environment.set('idempotencyKey', pm.variables.replaceIn('{{$guid}}'));
}

Set the header to Idempotency-Key: {{idempotencyKey}}. Delete or replace the environment value
before starting a genuinely new payment; leave it unchanged for a transport retry. Add this test
script to save the returned transaction identifier and catch malformed success responses:

pm.test('payment request succeeded', () => {
  pm.expect([200, 201]).to.include(pm.response.code);
});

const response = pm.response.json();
pm.expect(response.success).to.eql(true);
pm.expect(response.data.id).to.be.a('string');
pm.environment.set('transactionRowId', response.data.id);
pm.environment.set('transactionId', response.data.transactionId);

Recommended cases:

After a successful request:

1. Save data.id.
2. Call GET {{baseUrl}}/api/v1/transactions/{{transactionRowId}}; the path accepts either the
   UUID data.id or the human-readable data.transactionId. The detail response includes
   normalized lineItems.
3. Do not use GET /transactions to validate the cart; list rows intentionally omit lineItems.
4. Re-fetch GET /device/products after financial finality to inspect server-confirmed Available.
   Inventory settlement is asynchronous, so an unchanged value on the first refresh is not by
   itself a failure. Retry briefly; if it still does not converge, do not resubmit the payment.
   Operational staff must inspect the Transaction settlement outbox and any Invoice Pending Review
   application before concluding that no deduction occurred.

What can and cannot be tested in the current web UI#

The web portal is useful for setup and observation:

• /invoices/products: create/edit a product, enable inventory tracking and short-sale policy;
  use the Inventory tab for Quantity In and Inventory Activity.
• /branches: create an active physical location and assign/reassign the device.
• /transactions: find the transaction; open /transactions/<id> to verify the normalized cart,
  amounts, payment status, branch, and receipt data.

The current Tenant Dashboard Virtual Terminal does not send this POS lineItems contract, so it
does not prove the five itemised endpoints end to end. Use Postman or the mobile build to submit the
cart. Also, the existing Inventory Pending Review component is not currently rendered in the
Inventory tab; verify accepted business-review work through the recovery API, and terminal
Transaction delivery failures through operational logs, metrics, or outbox tooling until that UI
is enabled.

Mobile implementation checklist#

• Gate POS cart UI on GET /api/v1/device/parameters → posLite.enabled.
• Read products only from GET /api/v1/device/products; never use portal GET /products.
• Send product id/name/unit/price as a sale snapshot; do not send Available or branch selection.
• Recalculate display totals locally for UX, but treat server subtotal/product validation as final.
• Persist one idempotency key per payment attempt and reuse it across transport retries.
• Treat AUTH and pending ACH/external payments as non-final; do not optimistically reduce stock.
• On 409/422 product violations, refresh the device catalog before the cashier retries.
• After final payment, show payment success even if inventory is delayed or under review; never
  create a replacement payment to recover inventory.