Pos

global.apis.pos.registerCardProcessor({
    // Shown in PostalPoint settings menu
    name: "Demo Card Processor",
    // Set true if the integration can credit funds back to a customer card.
    // A return/refund/credit transaction will call checkout with a negative amount.
    // If this is not true, the card payment option will not be shown on the checkout
    // during a return transaction.
    allowCreditCharges: false,
    init: async function () {
        // This will run after PostalPoint launches
        // and before any payments are processed.
        // In some situations it might run multiple times in a session.
    },
    checkout: async function ({amount, capture = true}) {
        // Charge a credit card using a card reader device.
        // amount is in pennies (or the equivalent base unit in the local currency).
        // If a credit is to be issued to the card, amount is * -1.

        // Add a payment to the receipt with the total amount paid, card details, etc.
        global.apis.pos.addReceiptPayment(
            new global.apis.pos.ReceiptPayment(
                global.apis.i18n.currencyMinorToMajor(amount),
                "card", // Payment type. Accepted values are card, ach, crypto, cash,
                // check, account, and free.  Other types will be displayed as-is.
                "Demo Card\nCardholder Name, etc\nMore info for receipt" // Additional text for receipt
            )
        );


        // Must return boolean false if the payment failed.
        // Otherwise it will be assumed it succeeded.
        // If an error is encountered, handle it and return false.
        // It's recommended to display a short "payment failed" error
        // message via global.apis.alert, and outputting more details
        // via global.apis.pos.addOnscreenPaymentLog.

        // If capture is false, perform an authorization but don't capture,
        // and return a value you can use to identify the authorization later
        // and complete it.  The value will be passed back to finishPayment, below.
        // This is used mainly for the self-serve kiosk mode, in case the label fails
        // to be purchased/generated by the carrier.
    },
    cancelCheckout: function () {
        // The user has requested the card transaction be canceled before it completes.
        // Reset the terminal to its resting state, clear its screen, etc.
    },
    finishPayment: async function ({checkoutResponse}) {
        // Finish a payment that was authorized but not captured
        // because checkout() was called with capture = false.
        // If payment was already captured and added
        // to the receipt, just return true.
        global.apis.pos.addReceiptPayment(
            new global.apis.pos.ReceiptPayment(
                global.apis.i18n.currencyMinorToMajor(amount),
                "card",
                "Demo Card\nCardholder Name, etc\nMore info for receipt"
            )
        );
    },
    updateCartDisplay: function (receipt) {
        // Show transaction data on the card reader display.
        // This function is called when the "cart" or total changes.
        // `receipt` is a receipt object, see docs for details.
    },
    checkoutSavedMethod: async function ({customerID, paymentMethodID, amount}) {
        // Same as checkout() except using a payment method already on file.
        // customerID and paymentMethodID are provided by getSavedPaymentMethods below.

        // Must return true upon success.
        // If the payment is not successful, and you didn't throw an Error to show the user,
        // then `return false` instead and it'll appear that the user's action to start the payment did nothing.
        return true;
    },
    saveCardForOfflineUse: async function (statusCallback, customerAddress) {
        // Use the card reader to capture an in-person card and save it for offline use.
        // Provided details are an Address object with the customer's contact info.
        // Saved card details must be tied to the customerAddress.uuid, as that's how saved cards are looked up.

        // statusCallback(string, boolean) updates the progress message on the cashier's screen.
        // If the boolean is true, the progress message is replaced with a confirmation message.
        statusCallback("Saving card details...", false);

        return true; // Card saved to customer
        // If an error occurred, you can throw it and the error
        // message will be displayed to the cashier.
        // Alternatively, return boolean false and display the error
        // yourself with global.apis.alert(message, title) or something.
    },
    getExternalURLForSavingCard: async function (statusCallback, customerAddress) {
         // Alternate flow for saving cards. If this function is defined, an alternate card saving UI is used.
         // Returns a URL and a Promise.  The URL is for an external webpage that accepts
         // the customer's card info and saves it. The URL will be opened by the customer
         // on their phone, or possibly by the store in the system web browser.
         // The Promise resolves when the card info is saved,
         // with the same behavior as saveCardForOfflineUse.
         return {
             url: "https://...",
             promise: async function () {
                 // wait for card info to be saved
             }
    },
    cancelSaveCardForOfflineUse: function () {
        // Cancel the process running in saveCardForOfflineUse() or getExternalURLForSavingCard() at the user/cashier's request.
    },
    getSavedPaymentMethods: async function ({customerUUID}) {
        // Return all saved payment methods tied to the provided customer UUID.
        return [{
            customer: "<internal string referencing the customer>", // Passed to checkoutSavedMethod as customerID
            customer_uuid: customerUUID,
            id: "<card/payment method identifier>", // Passed to checkoutSavedMethod as paymentMethodID
            type: "card", // Payment type. Accepted values are card, ach, crypto, cash, check, account, and free.
            label: "Visa debit x1234 (exp. 12/29)", // Label for payment method
            label_short: "Visa debit x1234" // Abbreviated label for payment method
        }];
    },
    deleteSavedPaymentMethod: async function ({customerUUID, customerID, paymentMethodID}) {
        // Delete the payment method identified by paymentMethodID
        // and tied to the PostalPoint customerUUID and the card processor customerID.
        // If unable to delete, throw an error and the error message
        // will be displayed to the cashier.
    }
});

global.apis.pos.registerCryptoProcessor({
    name: "Demo Crypto", // Shown in PostalPoint settings menu
    init: async function () {
        // This is run after PostalPoint starts,
        // and before any other crypto functions are called.
    },
    checkout: async function ({amount}) {
        // Run the checkout process.
        // amount is the amount of fiat currency to collect,
        // in pennies (or the local equivalent).

        // If an error is encountered during processing,
        //    display an error message in a dialog and return boolean false.
        //    If this function returns anything except false or undefined,
        //    and doesn't throw an error,
        //    it is assumed the payment was successful.

        // Adds a line of text visible to the cashier
        global.apis.pos.addOnscreenPaymentLog("Getting crypto payment...");

        // Display a web page (i.e. with a payment QR code)
        // to the customer on the customer-facing display.
        global.apis.ui.setCustomerScreen("<html></html>", "html");
        global.apis.ui.setCustomerScreen("https://postalpoint.app", "raw");

        // Poll the status of the crypto transaction
        var paymentComplete = false;
        do {
            await global.apis.util.delay(1000);
            paymentComplete = true;
        } while (paymentComplete != true);

        global.apis.pos.addReceiptPayment(
                new global.apis.pos.ReceiptPayment(
                        global.apis.i18n.currencyMinorToMajor(amount),
                        "crypto", // Payment type.
                        "Bitcoin\n0.00001234 BTC" // Additional text for receipt
                        )
                );
        global.apis.pos.addOnscreenPaymentLog("Payment successful!");
        global.apis.ui.clearCustomerScreen();
    },
    cancelCheckout: function () {
        // The user requested to cancel the payment.
        // Reset things accordingly.
        global.apis.ui.clearCustomerScreen();
    },
    isConfigured: function () {
        // Is this plugin properly setup
        // and able to process payments?
        // If not, return false.
        // This determines if the crypto payment method button will be shown.
        return true;
    }
});

[{
    "transactionid": 220, // Internal database ID.
    "uuid": "fh38mmun15f7qdmj", // The receipt's public ID.
    "date": "2026-04-06 19:35:47",
    "cashierid": -1, // Employee's database ID number, or -1 if not using employee logins.
    "customeruuid": "be89ab9c-83a4-4ee7-a8ff-9464bf656f15", // Customer UUID, or null.
    "originaluuid": null, // If a return, the original receipt's ID.
    "type": "SALE", // "SALE" or "RETURN"
    "total": 22,
    "itemCount": 1,
    "paidTotal": 22,
    "costTotal": 0,
    "taxTotal": 0,
    "cashTotal": 22,
    "cardTotal": 0,
    "checkTotal": 0,
    "cryptoTotal": 0,
    "discountTotal": 0,
    "roundingTotal": 0, // Cash rounding to 5 cents
    "otherTotal": 0, // Other payment types.
    "dueTotal": 0,
    "paid": true,
    "cashCount": 1,
    "cardCount": 0,
    "checkCount": 0,
    "cryptoCount": 0,
    "discountCount": 0,
    "roundingCount": 0, // Cash rounding to 5 cents
    "otherCount": 0, // Other payment types.
    "netProfit": 22, // Net profit if the sale were fully paid: revenue - costTotal - taxTotal
    "netProfitActual": 22, // Actual net profit based on payments received so far: paidTotal - costTotal - taxTotal
    "items": [
        {
            "category": "", // Item category name.
            "merchandiseid": null, // If set, is a string UUID for a merchandise item.
            "type": "ship", // "merch" or "ship"
            "label": "Item Label",
            "priceEach": 22, // Price for one unit of the item.
            "qty": 1, // Quantity/units sold.
            "taxRate": 0, // Tax rate.
            "taxableAmount": "", // If "markup", only the margin/markup is taxable. Rarely, this is how shipping is taxed in some jurisdictions.
            "cost": 0, // Item cost for one unit, set by the user in the merchandise database.
            // See ReceiptItem docs for info on the JSON data.
            "json": "{\"id\":\"item_id_12345\",\"label\":\"Item Label\",\"text\":\"Item Receipt Text Lines\",\"priceEach\":22,\"qty\":1,\"cost\":0,\"retail\":0,\"taxRate\":0,\"taxableAmount\":\"\",\"taxTotal\":0,\"free\":false,\"barcode\":\"406183511501\",\"certifiedInfo\":false,\"isMerch\":false,\"merchid\":null,\"surcharge\":false,\"mailboxNumber\":null,\"mailboxDays\":0,\"mailboxMonths\":0,\"carrier\":\"\",\"service\":\"\",\"category\":\"\",\"electronicReturnReceipt\":false,\"isStamp\":false,\"extraData\":{}}"
        }
    ],
    "payments": [
        {
            "type": "cash",
            "amount": 22,
            "text": "" // Extra text lines printed on the receipt. Present for card payments and in some other situations.
        }
    ]
}]

// Reduce the stock count by 2
await global.apis.pos.updateStock("243d4c0f-c9ce-414a-aec7-9fc753eb13d6", -2);

// Increase the stock count by 5
await global.apis.pos.updateStock("243d4c0f-c9ce-414a-aec7-9fc753eb13d6", 5);

[{
 "id": "", // UUID v4
 "name": "",
 "category": "",
 "price": 1.0,
 "cost": 0.5,
 "barcode": "",
 "taxrate": 0.1,
 "stock": 10,
 "show": 1, // Boolean
 "length": 0,
 "width": 0,
 "height": 0,
 "rental_days": 0,
 "rental_months": 0,
 "rental_size": "1"
}]