Nōwn Meal Plan System

REST API Guide

Last updated: 2026-05-14

This guide documents the REST API for the Nōwn Meal Plan System (MPS). It is written for external integrators who need to look up customer meal plans and process transactions against them.

Contents

1. Getting started
2. Conventions
   • Base URL
   • Authentication
   • Response envelope
   • Error model
   • HTTP status codes
   • Idempotency
   • Field naming gotchas
3. Patron lookup
   • GET /payment/gateway/patron
4. Transactions
   • POST /payment/gateway/transaction/estimate
   • POST /payment/gateway/direct-transaction
   • POST /payment/gateway/transaction/refund
5. Other endpoints
   • GET /payment/gateway/last-transaction
   • GET /payment/gateway/location
   • GET /payment/gateway/version
6. End-to-end walkthrough
7. Error code reference
8. Changelog

Getting started

1. Request credentials

Contact support@nownpos.com to receive credentials for your environment. You will be given two values:

• Host: the base URL for all API requests, e.g. https://api.example.com.
• Auth key: a token used in the Authorization header for every request.

Treat the auth key as a secret. We recommend storing it in a configuration file or secret manager keyed per location, so that transactions can be uniquely attributed to a location in the MPS dashboard.

Migrating from the v1.1 PDF guide? Previous versions of this guide instructed integrators to base64-decode a wrapper blob to extract the host and auth key. The new onboarding flow gives you both values directly. No decoding needed.

2. Make your first request

Replace {HOST} and {AUTH_KEY} with the values you received.

curl '{HOST}/payment/gateway/version' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {AUTH_KEY}'

Expected response:

{
    "success": true,
    "version": "1.0.0"
}

If you receive 401 Unauthorized, recheck the Authorization header. See Authentication below.

Conventions

Base URL

All endpoints are mounted under /payment/gateway on the host you were issued. Throughout this guide, {HOST} is a placeholder for your assigned host (for example, https://api.example.com).

Authentication

Every request must include an Authorization header with the Bearer scheme:

Authorization: Bearer {AUTH_KEY}

The auth key is a single token. It is not a base64-encoded user:password pair. Send it verbatim.

Note for integrators upgrading from the v1.1 PDF: Earlier versions of this guide instructed using Authorization: Basic <auth-key>. That instruction was incorrect. The server validates the token against its AccessToken table via the Bearer / OAuth auth path; the Basic-auth path expects a different format (user:password base64-encoded) and will reject your token. If you have an existing integration using Basic, switch to Bearer. The token value does not change, only the scheme keyword.

Response envelope

Most endpoints return a JSON envelope of the form:

{
    "success": true,
    "data": { ... },
    "error": null
}

• success (boolean): true if the request was accepted and processed.
• data (object | null): present on success; shape depends on the endpoint.
• error (object | null): present on failure; see Error model.

A few endpoints (last-transaction, version) return the payload directly without the envelope. These are noted in their individual sections.

Error model

When success is false, the response body includes an error object:

{
    "success": false,
    "error": {
        "reason": "Insufficient Tender Amount",
        "code": 100002
    }
}

• reason (string): human-readable error message.
• code (integer): numeric error code. See the Error code reference for the full list.

Endpoints that do not use the envelope (last-transaction, version) return errors as non-2xx HTTP status codes — see HTTP status codes for the body shape.

HTTP status codes

Most operations return HTTP 200 with the response envelope — business-logic failures (validation, patron not found, insufficient balance) still return 200. Check success in the envelope, not the HTTP status.

A few classes of error use real HTTP status codes:

Recommended client behavior:

1. Check the HTTP status code first.
2. On 200, inspect the envelope's success field.
3. On non-2xx, parse the appropriate error body. The numeric error code lives at exception.appCode (most endpoints) or code (/last-transaction).

Note: The error body shape on non-2xx responses differs from the envelope's error object. The envelope uses {reason, code}; non-2xx responses use {error, exception: {appCode, message}} (or {code, message} for /last-transaction). Plan your error-parsing code accordingly.

Idempotency

POST /payment/gateway/direct-transaction is idempotent on transactionUuid. If a request with the same transactionUuid (and same authenticated user) has already been processed, the server returns the original response without re-executing the transaction. There is no double-charge and no error.

You should:

• Generate a fresh transactionUuid (RFC 4122 v4, 36 characters) for every new transaction.
• On a network error or timeout where you do not have a confirmed response, retry with the same transactionUuid rather than generating a new one. The server will return the original result if the first attempt actually completed.

Field naming gotchas

A few details that catch integrators by surprise:

• itemPrice and itemTotalPrice are the canonical field names on receipt items, not price and total. Older clients may have used price/total; those names still deserialize but fail validation on direct-transaction. Use itemPrice and itemTotalPrice.

Patron lookup

GET /payment/gateway/patron

Looks up a patron by their Nōwn customer-app identifier (QR code value). This endpoint also decrypts the rotating QR format used by the Nōwn customer app.

Side effect: This endpoint may write to the patron's meal plan service period if one is active. This is intentional and ensures subsequent direct-transaction calls do not contend on the patron row.

Query parameters

Request

curl '{HOST}/payment/gateway/patron?patronKey={URL_ENCODED_PATRON_KEY}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {AUTH_KEY}'

Response: success

{
    "success": true,
    "data": {
        "valid": true,
        "patronId": 10001,
        "companyId": 1,
        "patronKey": "PATRON-0001",
        "patronCompanyKey": "PATRON-0001",
        "emailAddress": "patron@example.com",
        "firstName": "Pat",
        "lastName": "Patron",
        "password": "",
        "status": 0,
        "birthDate": null,
        "gender": null,
        "homeTown": null,
        "homeState": null,
        "homeCountry": null,
        "academicYear": null,
        "major": null,
        "athlete": null,
        "athleteSport": null,
        "dorm": null,
        "source": 0,
        "hasExpiredMealPlans": false,
        "photoUrl": null,
        "lucovaUserName": "abc123def4567890",
        "hasCreditCard": true,
        "applicableMealEquivalency": null,
        "fiitLocationId": null,
        "fiitPosStationId": null,
        "fiitCashierShiftId": null,
        "fiitLocationOverrideAllowed": false,
        "fiitLastTransaction": null,
        "overridePatronCompanyKey": 0,
        "mealPlans": [
            {
                "mealPlanId": 1,
                "companyId": 1,
                "name": "Unlimited Coffee 100",
                "mealPlanDescription": "",
                "mealPlanType": "DCB",
                "enabled": true,
                "mealPlanRunning": true,
                "mealPlanApplicable": true,
                "isMealPlanApplicable": true,
                "mealPlanAvailable": true,
                "isAvailable": true,
                "unavailablityReasons": {
                    "unavailableAtLocation": false,
                    "expired": false,
                    "noPriority": false,
                    "disabled": false,
                    "noBalance": false,
                    "active": true,
                    "ruleApplied": false
                },
                "patronMealRuleDeductions": [],
                "rules": [],
                "initialBalance": 100,
                "currentDcbBalance": 95.5,
                "currentMealPlanBalance": 0,
                "currentChargeBalance": 0,
                "remainingServicePeriodDcb": 95.5,
                "remainingServicePeriodMeals": 0,
                "remainingServicePeriodCharge": 0,
                "mealsPerPeriod": 0,
                "mealsPerServicePeriod": 0,
                "priority": 2,
                "taxFree": false,
                "guestPlan": false,
                "mealEquivalencyEnabled": true,
                "maxFlexAmountPerTransaction": 100,
                "maxTransactionServicePeriod": 0,
                "chargeBalance": 0,
                "flexAmount": 0,
                "mealPlanCyclePeriod": "WEEKLY",
                "mealPlanResetDay": "SATURDAY",
                "mealPlanResetMonth": null,
                "resetPeriodEnd": true,
                "forceReset": false,
                "isForceReset": false,
                "importExclusionEnabled": false,
                "archivedBalanceDeducted": false,
                "expired": null,
                "startDateTime": 1691539200000,
                "endDateTime": 1782863999000,
                "mealPlanResetTimeMillis": 1778043600000,
                "mealPlanResetDateMillis": 1736553600000,
                "servicePeriodEndMillis": 1778817540000,
                "nextResetDateMillis": 1778907600000,
                "lastResetDateMillis": 1778302800000,
                "patronMealPlanId": 10001,
                "patronId": 10001,
                "patronKey": null,
                "patronCompanyKey": null,
                "emailAddress": "",
                "firstName": "",
                "lastName": ""
            }
        ]
    }
}

Response: patron not found

{
    "success": false,
    "error": { "reason": "Invalid Patron: Not Found", "code": 101 }
}

Notes

• Use mealPlanAvailable / isAvailable to decide whether a meal plan can be charged. If false, inspect unavailablityReasons for why. Common reason: active: false means there is no current active service period for the plan (e.g. a breakfast-only plan looked up at dinner time).
• lucovaUserName is the patron's app-side identifier. Save it from this response and pass it to direct-transaction when charging the patron.
• hasCreditCard: true indicates the patron has a credit card on file in the Nōwn app. Use this to decide whether to fall back to a credit-card charge when no meal plan is available.
• mealPlanType values include DCB (declining cash balance) and MEAL (meal-swipe plan).
• Some fields are legacy aliases that mirror each other: mealPlanApplicable / isMealPlanApplicable, mealPlanAvailable / isAvailable. Either name works; new code should prefer the non-is-prefixed form.
• Many patron-profile fields (birthDate, gender, homeTown, etc.) are typically null for integration use cases.

Transactions

POST /payment/gateway/transaction/estimate

Calculates what a transaction would look like without committing it. Useful for showing the cashier a tender breakdown (DCB applied, remaining balance to charge to credit card, taxes) before confirming the sale.

Request body: same shape as direct-transaction.

Request

curl '{HOST}/payment/gateway/transaction/estimate' \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_KEY}' \
  --data-raw '{
    "requestAmount": 4.50,
    "request": {
        "patronId": 10001,
        "subtotal": 4.50,
        "totalTaxes": 0,
        "totalSales": 4.50,
        "receiptItems": [
            { "quantity": 1, "name": "Blueberry Yogurt Parfait", "itemPrice": 4.50, "itemTotalPrice": 4.50 }
        ]
    }
  }'

Response: success

{
    "success": true,
    "data": {
        "approvedAmount": 4.50,
        "approvedDCBAmount": 4.50,
        "approvedMealEqAmount": 0,
        "approvedMeal": 0,
        "outstandingAmount": 0,
        "partiallyApproved": false,
        "items": [ /* per-item calculation breakdown */ ]
    }
}

Response fields

Notes

• estimate requires an active cashier shift at the location's default POS station. If none exists, the response is NO_ACTIVE_SHIFT (code 407).
• estimate is read-only and does not consume any balance.

POST /payment/gateway/direct-transaction

Charges a transaction directly to the patron's account. This is the primary transaction endpoint for most integrations.

Required headers

Content-Type: application/json
Authorization: Bearer {AUTH_KEY}

Request body

Receipt item fields

Charging a credit card on file

To charge a customer's credit card stored in the Nōwn app:

1. Confirm the patron has one: hasCreditCard: true in the patron-lookup response.
2. Submit direct-transaction without a patronId (or with patronId: -1).
3. Set creditCardAmount to the amount to charge.
4. Still include lucovaUserName and transactionUuid.

Request

curl '{HOST}/payment/gateway/direct-transaction' \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_KEY}' \
  --data-raw '{
    "requestAmount": 4.50,
    "request": {
        "patronId": 10001,
        "dcbAmount": 4.50,
        "creditCardAmount": 0,
        "debitCardAmount": 0,
        "subtotal": 4.50,
        "totalTaxes": 0,
        "totalSales": 4.50,
        "receiptItems": [
            {
                "quantity": 1,
                "name": "Blueberry Yogurt Parfait",
                "itemPrice": 4.50,
                "itemTotalPrice": 4.50
            }
        ],
        "lucovaUserName": "abc123def456",
        "transactionUuid": "11111111-2222-4333-8444-555555555555"
    }
  }'

Response: success

{
    "success": true,
    "data": {
        "success": true,
        "transaction": {
            "preauth": false,
            "amount_cents": 450,
            "tax_cents": 0,
            "discount_cents": 0,
            "transaction_type": "direct",
            "status": "completed",
            "transaction_opened": 1747227024,
            "transaction_closed": 1747227024,
            "transaction_opened_obj": "2026-05-14T13:30:24Z",
            "transaction_opened_hr": "2026-05-14 13:30:24 +0000",
            "user_name": "abc123def456",
            "short_id": "12345678",
            "merchant_id": "...",
            "node_id": "...",
            "node_name": "Example Cafeteria",
            "pos_order_id": "...",
            "summary": "$4.50"
        },
        "message": null,
        "error_code": 0
    }
}

Response fields (top-level under data.transaction)

Response: failure

If the request is rejected before reaching the payment processor (validation, no POS station, no active shift), the envelope returns success: false with an error object. If the payment processor rejects the transaction, you'll get success: true at the envelope level but data.success: false and data.message / data.error_code set.

Common validation errors

POST /payment/gateway/transaction/refund

Refunds a previously processed transaction.

Required headers: same as direct-transaction.

Request body

Request

curl '{HOST}/payment/gateway/transaction/refund' \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_KEY}' \
  --data-raw '{
    "transactionId": 5001,
    "description": "Customer return: item out of stock",
    "transactionUuid": "99999999-2222-4333-8444-555555555555"
  }'

Response: success

{
    "success": true,
    "data": {
        "transactionId": 5001,
        "patronName": "Pat Patron",
        "userName": "abc123def456",
        "servicePeriodName": "Week 19",
        "posStationName": "Station 1",
        "dcbAmount": 4.50,
        "cashAmount": 0,
        "changeAmount": 0,
        "creditCardAmount": 0,
        "totalTaxes": 0,
        "totalSales": 4.50,
        "totalDiscount": 0,
        "time": "2026-05-14T14:02:11Z"
    }
}

Other endpoints

GET /payment/gateway/last-transaction

Returns the most recent transaction for a patron. Returns the LastTransactionDTO directly (no envelope).

Query parameters

Response

{
    "transactionId": 5001,
    "locationName": "Example Cafeteria",
    "paymentMethod": "DCB",
    "transactionDateTime": "2026-05-14T13:30:24Z",
    "elapsedTime": 12,
    "elapsedTimeUnit": "minutes",
    "tenders": { "DCB": 450 }
}

tenders is a map of tender-type → amount in cents.

GET /payment/gateway/location

Returns the location associated with the auth key.

Request

curl '{HOST}/payment/gateway/location' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {AUTH_KEY}'

Response: success

{
    "success": true,
    "data": {
        "locationId": 1,
        "companyId": 1,
        "nodeId": "node-example",
        "locationName": "Example Cafeteria",
        "mealPlanIds": [1, 2],
        "mealPlans": [ /* MealPlanDTO list */ ],
        "servicePeriodIds": [10, 11],
        "servicePeriods": [ /* ServicePeriodDTO list */ ],
        "tenderTypeIds": [1, 2, 3],
        "overrideAllowed": false
    }
}

Useful for confirming which location a given auth key is provisioned for, and which meal plans are configured at that location.

GET /payment/gateway/version

Returns the MPS calculation API version. Useful as a health check.

Response

{ "success": true, "version": "1.0.0" }

This endpoint returns the payload directly (no {success, data} envelope around it).

End-to-end walkthrough

The typical integration flow for a single transaction:

1. Look up the patron with GET /payment/gateway/patron?patronKey=<URL_ENCODED_PATRON_KEY>.

2. Check whether to charge a meal plan or a credit card. Look at the response:

   • If any meal plan has mealPlanAvailable: true, charge the patron's meal plan. Note the lucovaUserName from the response.
   • If no plan is available but hasCreditCard: true, charge their credit card on file.
   • If neither is available, prompt the cashier for an alternative payment method.

3. (Optional) Preview the tender split with POST /payment/gateway/transaction/estimate to show the cashier what will be charged to DCB vs. credit card.

4. Charge the patron with POST /payment/gateway/direct-transaction:

   • Generate a fresh transactionUuid (UUID v4).
   • Include the lucovaUserName from the patron-lookup response.
   • Include itemPrice and itemTotalPrice (not price/total) on each receipt item.
   • On network errors, retry with the same transactionUuid. The server is idempotent.

5. Persist short_id from the response for reconciliation and customer-facing receipts.

6. Refund later if needed: look up the transactionId via GET /payment/gateway/last-transaction?patronId={patronId}, then call POST /payment/gateway/transaction/refund with it.

Error code reference

Error codes fall into four groups:

1. Common errors (codes 400–413): general operational and validation errors that any endpoint may return.
2. MPS-specific errors (codes 1000–1001): returned by /last-transaction.
3. Gateway calculation errors (codes 100001–100002): issues talking to the meal-plan calculation server.
4. Validation errors (no numeric code): request-shape failures on direct-transaction. The code field is 0 or omitted; the reason field carries the human-readable message.

In addition, the direct-transaction endpoint may surface passthrough error codes from the downstream payment processor under data.error_code when data.success is false. These are not MPS codes. Contact engineering@nownpos.com for guidance on specific codes.

Common errors

MPS-specific errors

Returned by /last-transaction. These arrive as a non-2xx HTTP status with the body { "reason": "...", "code": ... } (no envelope).

Gateway calculation errors

Validation errors (no code)

Returned with code: 0 (or omitted) and a reason describing the problem. These are emitted by request-shape validation before any business logic runs.

Payment processor passthrough errors

When a direct-transaction request authenticates and validates successfully but the downstream payment processor rejects the charge, the response envelope returns success: true with data.success: false, data.message set to a human-readable message, and data.error_code set to a processor-specific numeric code. These codes are not enumerated in this guide. Contact engineering@nownpos.com for guidance on specific codes.

Support

• Credentials and environment access: support@nownpos.com
• API and integration questions: engineering@nownpos.com

When reporting an integration issue to engineering@nownpos.com, include:

• transactionUuid if the problem involves a transaction (direct-transaction, refund).
• Request timestamp (UTC) and the endpoint path that was called.
• The full request payload and the full response body (headers and JSON). For non-2xx responses, include the HTTP status code.

Changelog

2026-05-14

• Replaced the v1.1 PDF guide. New format is a single living Markdown document.
• Auth correction: Authorization header now correctly documented as Bearer, not Basic. Existing integrations using Basic should switch the scheme keyword. The token value does not change.
• Credentials format: Host and auth key are now issued as two separate values. No more base64-decoding the comma-separated wrapper.
• Receipt item fields: Canonical names are itemPrice and itemTotalPrice. The legacy price / total names deserialize but fail validation; integrators should migrate.
• Idempotency: Documented transactionUuid idempotency behavior on direct-transaction.
• New sections: Error code reference (AppCode enum, MPS errors, gateway errors, validation errors, payment processor passthrough notes), end-to-end walkthrough, field-naming gotchas.
• Endpoint coverage: Added transaction/estimate, transaction/refund, last-transaction, location, version.

v1.1 (2024-10-08)

• Previous PDF revision.