Going forward, it is recommended that all new app POS installations such as kiosks use the POS features provided by OMS v2.

App URL Format

The format of an app URL for use with POS is as follows:

https://legacy.custom-gateway.net/acp/app/?l=acp3_2#p=...&r=...&guid=...&ep3dUrl=...

or for distributed apps:

https://g3d-app.com/s/app/acp3_2/en_GB/default.html#_usePs=1&p=...&r=...&guid=...&ep3dUrl=...

In the case of distributed apps, it is necessary to force the app to use product state (_usePs=1) rather than normal print jobs. This is because the print job might not be picked up by OMS for several minutes and using product state provides enough information for OMS to be able to create an order without needing the print job to be available.

An example:

https://g3d-app.com/s/app/acp3_2/en_GB/default.html#_usePs=1&p=1007644&r=2d-canvas&guid=99999&ep3dUrl=https://oms.custom-gateway.net/v2/order-it/pos-unbranded/callback/?k=abcdefghijklmnopqrstuvwxyz0

Note HTTPS is required for both the main app URL and the callback URL. This means that any external assets such as stylesheets must also be specified as HTTPS.

Callback URL

The callback URL is specified via the ep3dUrl parameter and follows the below format:

https://oms.custom-gateway.net/v2/order-it/pos-unbranded/callback/?k=...

Where k should be the API key of the relevent company.

Once the callback URL is reached, the browser will be redirected back to the original app URL after two seconds.

Note The URL will allow anybody to create an order for the company in question without any payment being made.

Note For security, it is recommended that a dedicated POS company is used that has a different API key from any relevent sites.

There are also some additional URL parameters for controlling the behaviour of the callback:

Parameter Values Default Description
k Alpha numeric string N/a API key
r 0 / 1 0 Controls whether or not a receipt will be displayed at the end of the process
g 0 / 1 0 Controls whether or not to generate artwork synchronously at the end of the process

Any ampersands (&) must be replaced with their URL safe encoding, %26.

A tool such as https://meyerweb.com/eric/tools/dencoder/ can be used to encode the entire URL.

Smart link builder will encode the URL automatically.

Synchronously Generate Artwork

Normally, artwork for POS orders would join the artwork generation queue however when synchronous artwork generation is turned on, the artwork will be generated at the end of the POS process and a link provided to the end user for them to download the artwork.

There are some caveats:

  • Artwork cannot currently be synchronously generated if a distributed app is being used, however support may be added in the future.

  • Only the Node Canvas renderer is used. Output types on companies and products will be ignored.

  • Only the multi paged PDF output will be returned to the user.

  • Large products may take time to generate or generation time may be slow when the system is busy.

Display Receipt

A receipt can be displayed at the end of the process.

The receipt contains the following information:

  • SKU
  • Description
  • Quantity
  • Price (only if the order-it/pos/receipt:show-item-price company setting is enabled)
  • EAN13 product barcode derived from the product’s barcode field in CPP (only if the order-it/pos/receipt-show-product-barcode company setting is enabled)
  • Codabar item barcode (only if the order-it/pos/receipt-show-item-barcode company setting is enabled)

The format used to display the price is locale aware, with the company’s locale and currency settings being taken into account.

The price value itself is sourced from the order item’s unit sale price field.

Order Details

Some apps support an order details form for collecting customer information and shipping details.

The POS callback URL can accept the following fields from an app:

  • customer_name
  • customer_email
  • customer_telephone
  • shipping_address_1
  • shipping_address_2
  • shipping_address_3
  • shipping_address_4
  • shipping_address_5
  • shipping_postcode
  • shipping_country
  • shipping_country_code
  • billing_customer_name
  • billing_customer_email
  • billing_customer_telephone
  • billing_address_1
  • billing_address_2
  • billing_address_3
  • billing_address_4
  • billing_address_5
  • billing_postcode
  • billing_country
  • billing_country_code
  • shipping_method
  • shipping_carrier
  • shipping_tracking
  • required_dispatch_date
  • coupon_code