Skip to content

# Pos

## pos : `object`

Point of Sale, transaction, and payment-related functionality.

Kind: global namespace

- pos : `object`
  - .ReceiptItem
    - new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount)
  - .ReceiptPayment
    - new ReceiptPayment(amount, type, text)
  - .addReceiptItem(item)
  - .addReceiptPayment(payment)
  - .addOnscreenPaymentLog(msg)
  - .getReceiptID() ⇒ `string`
  - .onReceiptChange(f)
  - ~~.onTransactionFinished(f)~~
  - .registerCardProcessor(f)
  - .registerCryptoProcessor(f)
  - .getShippingSalesTax() ⇒ `Object`

### pos.ReceiptItem

Kind: static class of `pos`
Properties

Name | Type | Default | Description
--- | --- | --- | ---
merch | `boolean` | `false` | True if merchandise, false if shipping.
barcode | `string` |  | Item barcode, or tracking number if `merch = false`.
qty | `number` | `1` | Item quantity.
retailPrice | `number` |  | The calculated retail/markup price for a shipment, regardless of actual sale price. If unset, defaults to priceEach * qty.
taxRate | `number` | `0` | Tax rate
toAddress | `Address` |  | Shipping destination address.
fromAddress | `Address` |  | Shipping return address.
carrier | `string` |  | Shipping carrier.
service | `string` |  | Shipping service.
category | `string` |  | Merchandise/item category.
electronicReturnReceipt | `boolean` | `false` | If true, the customer's receipt will have instructions on retrieveing the return receipt from USPS.
mailboxDays | `number` | `0` | Number of days this item adds to a mailbox's expiration date.
mailboxMonths | `number` | `0` | Number of months this item adds to a mailbox's expiration date.
mailboxNumber | `string` |  | Mailbox number to apply `mailboxDays` or `mailboxMonths` to after checkout.
setCertifiedInfo() | `function` |  | Set Certified Mail receipt data. `setCertifiedInfo(trackingNumber, certfee, extrafees, postage, date, location, toaddress)`
toJSON() | `function` |  | Get the item as an object suitable for JSON encoding.
fromJSON(json) | `static_function` |  | Returns a ReceiptItem created from the object returned by `item.toJSON()`.

#### new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount)

A class representing a sale item in the current transaction.

Param | Type | Default | Description
--- | --- | --- | ---
id | `string` |  | Unique ID number for this item (UPC code, inventory number, etc). Used to deduplicate and merge line items on the receipt. Unique items (like shipping labels) should be a unique/random ID.
label | `string` |  | One-line item information.
text | `string` |  | Extra multi-line item information.
priceEach | `number` |  | Sale price per unit.
quantity | `number` |  | Number of units.
cost | `number` |  | Cost per unit. Used for automatic expense tracking.
taxrate | `number` | `0.0` | Examples: 0 (for 0%), 0.05 (for 5%), etc
taxableAmount | `string` |  | The part of the sale price that's taxable. "" for default (all), "markup" for only taxing profit.

### pos.ReceiptPayment

Kind: static class of `pos`
Properties

Name | Type | Description
--- | --- | ---
label | `string` | (readonly) The human-readable string of the payment type.
id | `string` | Automatically-generated unique ID for this payment.
toJSON() | `function` | Get the payment as an object suitable for JSON encoding.
fromJSON(json) | `static_function` | Returns a ReceiptPayment created from the object returned by `payment.toJSON()`.

#### new ReceiptPayment(amount, type, text)

A class representing a payment entry for the current transaction.

Param | Type | Description
--- | --- | ---
amount | `number` | amount paid
type | `string` | payment type
text | `string` | extra data (credit card info, etc)

### pos.addReceiptItem(item)

Add an item (shipment, merchandise, etc) to the current transaction.

Kind: static method of `pos`

Param | Type
--- | ---
item | `ReceiptItem`

### pos.addReceiptPayment(payment)

Add a payment to the current transaction/receipt.

Kind: static method of `pos`

Param | Type
--- | ---
payment | `ReceiptPayment`

### pos.addOnscreenPaymentLog(msg)

Append a line of text to the onscreen log displayed during credit card processing. Not shown in kiosk mode.

Kind: static method of `pos`

Param | Type | Description
--- | --- | ---
msg | `string` | Line of text to add to the log.

### pos.getReceiptID() ⇒ `string`

Get the unique alphanumeric ID for the current transaction/receipt. This is the same code printed on receipts and used in digital receipt URLs.

Kind: static method of `pos`

### pos.onReceiptChange(f)

Specify a function to be called whenever the transaction data/receipt is changed. It is passed a single argument, a Receipt object containing the entire transaction so far.

Kind: static method of `pos`

Param | Type
--- | ---
f | `function`

### ~~pos.onTransactionFinished(f)~~

Deprecated

The supplied function will be called when a transaction is finished. It is passed a single argument, a Receipt object containing the entire transaction. Recommended to listen for the `transactionFinished` event instead.

Kind: static method of `pos`

Param | Type
--- | ---
f | `function`

### pos.registerCardProcessor(f)

Register as a card payment processor.

Kind: static method of `pos`

Param | Type | Description
--- | --- | ---
f | `Object` | Payment processor functions

Example

    global.apis.pos.registerCardProcessor({
        name: "Demo Card Processor", // Shown in PostalPoint settings menu
        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).

            // 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, customerUUID, name,
                 company, street1, street2, city, state, zip, country, email, phone}) {
            // Use the card reader to capture an in-person card and save it for offline use.
            // Provided details are the customer's info, which might be empty strings except for the customerUUID.
            // Saved card details must be tied to the customerUUID, 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.
        },
        cancelSaveCardForOfflineUse: function () {
            // Cancel the process running in saveCardForOfflineUse() 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.
        }
    });

### pos.registerCryptoProcessor(f)

Register as a cryptocurrency payment processor.

Kind: static method of `pos`

Param | Type | Description
--- | --- | ---
f | `Object` | Payment processor functions

Example

    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;
        }
    });

### pos.getShippingSalesTax() ⇒ `Object`

Get the sales tax percentage to charge on a shipping service ReceiptItem.

Kind: static method of `pos`
Returns: `Object` - `{type: "", percent: 0.15}` `type` is an empty string for taxing the entire price, or "markup" for only adding tax to the markup amount. `percent` is the tax percentage. A value of 0.15 means a 15% tax.