Manual Flow in POS System Checkout

Overview

After obtaining an access token, your POS system can interact with the Widgets platform through a sequence of API calls. This flow allows you to retrieve available widgets, initiate a widget session, and display the resulting QR code on the customer-facing screen (CFS) or deliver it via other supported methods (e.g., email or SMS).

Manual Flow Steps

Add Products to Cart

Merchant adds products to the shopping cart.

Proceed to Checkout

Merchant proceeds to the checkout process.

System Checks

During checkout, the POS system completes several checks:

Check if post-purchase transactions are enabled
Check if POS Rules are enabled

Show Confirmation Modal

If POS Rules are disabled, a confirmation modal is shown proposing to use ClearLine Marketing apps.

Display Marketing Apps

If merchant confirms to proceed with ClearLine Marketing, a modal is shown with the marketing apps list (tiles view).Endpoint: Get Available Widgets (Marketing Apps)

Select Marketing App

Merchant clicks on one of the marketing apps.Endpoint: Start a Widget Session (Display QR Code preview)

Complete Session

Merchant clicks the “Open QR Code” button or “Send” button.Endpoint: Complete the Widget Session

Deliver Content

ClearLine app shows the QR Code template (modal) or sends SMS/email to the customer.

Get Available Widgets (Marketing Apps)

Retrieve a list of widgets available for a specific POS location. These widgets can be used to engage customers through various delivery methods like QR codes, emails, or SMS.

POST https://public-api-test.clearline.me/v2/pos/{posSystem}/widgets/list

{
  "posLocationId": "string"
}

{
  "data": [
    {
      "id": 1,
      "name": "Digital Coupons",
      "icon": "https://web.clearline.me/widget/IssueCoupon/icon",
      "description": "How It Works\\nWhen you decide that your business...",
      "deliveryMethods": ["Sms", "Email", "QrCode"],
      "flow": ["Default", "Custom"]
    }
  ]
}

Headers

Name	Value	Description
Authorization	Bearer access_token	Request authorization header
Content-Type	application/json	Content type

Path Parameters

Field name	Description
posSystem	The identifier of the POS system (e.g., pax, clover)

Request Body

Field name	Type	Description
posLocationId	string	The identifier of the POS location

Response Fields

array

Array of available widget objects

Show Widget Object Properties

integer

Identifier of the marketing app

string

Name of the marketing app

string

Icon in SVG format

string

Description of the marketing app

string[]

Allowed delivery methods (Sms, Email, QrCode)

string[]

Identifies the flow of the widget execution (Default, Custom)

UI Example

Initiate a widget session and preview the QR code.

POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/widget/start

{
  "posLocationId": "{posLocationId}",
  "widgetId": "{widgetId}",
  "terminalId": "{terminalId}",
  "couponId": "{couponId}"
}

{
  "data": {
    "sessionId": "string",
    "qrCodePreviewHtmlLinkUrl": "string"
  }
}

Headers

Name	Value	Description
Authorization	Bearer access_token	Request authorization header
Content-Type	application/json	Content type

Path Parameters

Field name	Type	Description
posSystemId	string	The identifier of the POS system (e.g., pax, clover)

Request Body

Field name	Type	Required	Description
posLocationId	string	Yes	The identifier of the POS location
widgetId	integer	Yes	The identifier of the widget
terminalId	string	Yes	The identifier of the POS terminal
couponId	string	No	The identifier of the coupon, required for Issue Coupon widget only

Response Fields

object

Widget session data

Show Properties

string

Session identifier for tracking the widget interaction

string

Preview QR code HTML link URL

Display the widget QR code to the customer on the customer-facing screen.

POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/widget/showQrCode

{
  "widgetId": 0,
  "sessionId": "string",
  "posLocationId": "string",
  "terminalId": "string",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "customerEmail": "string",
    "customerPhone": "string",
    "salesPerson": "string"
  },
  "couponId": "string"
}

{
  "data": {
    "qrCodeHtmlLinkUrl": "string"
  }
}

Headers

Name	Value	Description
Authorization	Bearer access_token	Request authorization header
Content-Type	application/json	Content type

Path Parameters

Field name	Type	Description
posSystemId	string	The identifier of the POS system (e.g., pax, clover)

Request Body

Field name	Type	Required	Description
widgetId	integer	Yes	The identifier of the widget
sessionId	string	Yes	The session identifier from the start widget call
posLocationId	string	Yes	ID of the location where the transaction was made
terminalId	string	Yes	The identifier of the POS terminal
profile	object	No	Customer profile information
couponId	string	No	The identifier of the coupon, required for Issue Coupon widget only

Profile Object

Field name	Type	Description
firstName	string	Customer’s first name
lastName	string	Customer’s last name
customerEmail	string	Customer’s email address
customerPhone	string	Customer’s phone number
salesPerson	string	Name of the sales person

Response Fields

object

QR code display data

Show Properties

string

QR code HTML link URL to display on the customer-facing screen

Send the widget QR code to the customer via email or SMS instead of displaying it on the customer-facing screen.

POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/widget/sendMessage

{
  "widgetId": 0,
  "sessionId": "string",
  "posLocationId": "string",
  "terminalId": "string",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "customerEmail": "string",
    "customerPhone": "string",
    "salesPerson": "string"
  },
  "couponId": "string"
}

{
  "data": {}
}

Headers

Name	Value	Description
Authorization	Bearer access_token	Request authorization header
Content-Type	application/json	Content type

Path Parameters

Field name	Type	Description
posSystemId	string	The identifier of the POS system (e.g., pax, clover)

Request Body

Field name	Type	Required	Description
widgetId	integer	Yes	The identifier of the widget
sessionId	string	Yes	The session identifier from the start widget call
posLocationId	string	Yes	ID of the location where the transaction was made
terminalId	string	Yes	The identifier of the POS terminal
profile	object	Yes	Customer profile information (required for delivery)
couponId	string	No	The identifier of the coupon, required for Issue Coupon widget only

Profile Object

Field name	Type	Required	Description
firstName	string	No	Customer’s first name
lastName	string	No	Customer’s last name
customerEmail	string	No	Customer’s email address
customerPhone	string	No	Customer’s phone number
salesPerson	string	No	Name of the sales person

At least one of customerEmail or customerPhone must be provided to send the message.

Response Fields

object

Empty object returned on successful message delivery

Next Steps

Checkout Integration Flow

View the complete checkout integration workflow

Widget API Reference

Explore all widget endpoints

Authentication

Learn how to authenticate API requests

POS Settings

Configure manual vs automated flow

Getting Started

Integration Options

POS Integration

API Reference

Overview

Manual Flow Steps

Get Available Widgets (Marketing Apps)

Headers

Path Parameters

Request Body

Response Fields

UI Example

Start a Widget Session

Headers

Path Parameters

Request Body

Response Fields

Show Widget QR Code

Headers

Path Parameters

Request Body

Profile Object

Response Fields

Send Widget QR via Email or SMS

Headers

Path Parameters

Request Body

Profile Object

Response Fields

Next Steps

Checkout Integration Flow

Widget API Reference

Authentication

POS Settings

​Overview

​Manual Flow Steps

​Get Available Widgets (Marketing Apps)

​Headers

​Path Parameters

​Request Body

​Response Fields

​UI Example

​Start a Widget Session

​Headers

​Path Parameters

​Request Body

​Response Fields

​Show Widget QR Code

​Headers

​Path Parameters

​Request Body

​Profile Object

​Response Fields

​Send Widget QR via Email or SMS

​Headers

​Path Parameters

​Request Body

​Profile Object

​Response Fields

​Next Steps

Checkout Integration Flow

Widget API Reference

Authentication

POS Settings

Overview

Manual Flow Steps

Get Available Widgets (Marketing Apps)

Headers

Path Parameters

Request Body

Response Fields

UI Example

Start a Widget Session

Headers

Path Parameters

Request Body

Response Fields

Show Widget QR Code

Headers

Path Parameters

Request Body

Profile Object

Response Fields

Send Widget QR via Email or SMS

Headers

Path Parameters

Request Body

Profile Object

Response Fields

Next Steps