Fee Preview API (Dual Pricing / POS)#

Pre-sale price preview for mobile and POS integrators. Returns posted cash price, credit (card) price, and ACH price so the client can display lawful dual pricing before charging (required in jurisdictions such as New York).

Last updated: 2026-10-01

Two endpoints return the same pricing: the JWT route below (dashboard, mobile and POS apps) and the API-key route GET /api/v1/public/fee-preview for server and checkout integrations (see Fee Preview — Public API).

Endpoint#

Authentication#

Merchant-scoped users always get their own merchant (any merchantId sent is ignored). Admin users must pass merchantId, otherwise 400 VALIDATION_ERROR (Merchant ID is required for admin users). API-key integrations should call GET /api/v1/public/fee-preview instead.

Query parameters#

*When baseAmount is missing or ≤ 0 (or configOnly=true) no error is returned — the response is the config-only shape with zeroed prices.

Whether customer fees apply is taken from the merchant's primary gateway (serviceFeeActive, default true); it cannot be overridden on this route.

Response#

{
  "success": true,
  "data": {
    "baseAmount": 100,
    "tipAmount": 0,
    "cardPrice": 104,
    "cashPrice": 100,
    "achPrice": 100,
    "convenienceFee": 4,
    "pricingModel": "cashdiscount",
    "enforcementMode": "v5",
    "customerFeesEnabled": true,
    "dualPricingRequired": true,
    "showPreview": true,
    "source": "v5",
    "cashDiscount": {
      "cashPrice": 100,
      "cardPrice": 104,
      "adjustment": 4
    },
    "prices": {
      "cash": { "total": 100, "adjustment": 0, "label": "Cash price" },
      "card": { "total": 104, "adjustment": 4, "label": "Credit price" },
      "ach":  { "total": 100, "adjustment": 0, "label": "ACH price" }
    },
    "appliedRules": [
      { "feeCode": "CD_ADJ", "feeName": "Card Adjustment", "calc": "percent", "amount": 4 }
    ],
    "snapshotId": "9b2e4f61-0c3d-4a8e-b7f5-1d2c3e4f5a6b",
    "scheduleVersion": 3
  }
}

Also returned when applicable: perTransactionFee (tech-fee model), canChangePayer / defaultPayer (hybrid freedom model), and feeWarning ({ code, message }). cardPrice / cashPrice / achPrice are deprecated — use prices.*.total.

Fields integrators should use#

Semantic model (not a “discount”)#

• Posted / cash price = baseAmount + tipAmount (what the merchant advertises)
• Credit price = posted price + card adjustment (compiled from V5 cashdiscount schedule)
• ACH price = posted price under a V5 cashdiscount schedule (ACH is cash-equivalent). Under enforcementMode: legacy the legacy convenience fee is applied to the ACH lane as well, so always display prices.ach.total rather than assuming it equals the cash price

Config-only probe#

Check whether a merchant requires dual-pricing display before the operator enters an amount:

Returns dualPricingRequired, enforcementMode and customerFeesEnabled (plus pricingModel when one is resolved) with zeroed price fields and showPreview: false.

curl "https://uat.auxcore.net/api/v1/public/fee-preview?amount=49.00&tipAmount=0&paymentMethod=card"   -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "baseAmount": 49,
    "convenienceFee": 1.47,
    "totalAmount": 50.47,
    "currency": "USD",
    "paymentMethod": "card",
    "convenienceFeeActive": true,
    "prices": {
      "cash": { "total": 49, "adjustment": 0, "label": "Cash price" },
      "card": { "total": 50.47, "adjustment": 1.47, "label": "Credit price" },
      "ach":  { "total": 49, "adjustment": 0, "label": "ACH price" }
    },
    "pricingModel": "cashdiscount",
    "dualPricingRequired": true
  }
}

Internal fee-config (service-to-service)#

Served by the merchant service on its internal mount (not exposed through the API gateway):

Headers: x-internal-service-key, x-tenant-id

Returns cashDiscountEnabled, dualPricingRequired, v5PricingModel, enforcementMode, and legacy convenienceFee* fields.

POS integration checklist#

1. On amount entry (or cart total change), call fee-preview with baseAmount and tipAmount.
2. If dualPricingRequired, render prices.cash.label + prices.cash.total and prices.card.label + prices.card.total (and prices.ach when ACH is offered).
3. When the customer selects a payment method, charge the matching prices.{lane}.total.
4. Do not compute adjustments client-side — always use this API so preview matches the sale path.
5. Dual pricing needs the merchant's pricing set to the cash discount model; dualPricingRequired is true when it is.

Related endpoints#

See Mobile Device Integration for device auth patterns.