Skip to main content
Documentation Powered by Redocly

Integration API (v2)

Download OpenAPI specification:Download

API Reference for interacting with the Customer Session

Customer Session

Request

A customer session request object includes

  • identifying information for the session (id)
  • consistency identifier (consistency_id)
  • basket information (basket: { total })
  • scanned tokens intended to be included in the session
  • items in the customers basket the merchant would like to check for subsidies

The items provided can be compared against the relevant_items (see below).

Response

A customer session response object includes

  • identifying information for the session (id, consistency_id, ref)
  • scanned tokens used to retrieve associated coupons
  • the current state of the session (OPEN, CLOSED or CANCELLED)
  • an external identifier for the customer providing the coupon, can be used to identify the customer to Merchant Loyalty Program
  • a list of coupons associated with the scanned token
  • relevant_items (products) associated with the extracted coupons
  • subsidies that Transit will provide towards products

Update a Customer Session

A session can be created just by sending a ref to the Transit Desktop Agent's http://localhost:42000/v2/customer_session endpoint. Once created, you can expand on the interaction with repeated PUT requests to the same endpoint.

Repeated calls function as a transaction negotiation and allow the Merchant and Transit to come to agreement on the subsidies Transit is committing to provide.

Request Body schema: application/json
Any of
ref
required
string

Reference id to create a new session

Responses

Response Schema: application/json
id
required
string

Session identifier

consistency_id
required
string

Session consistency identifier
Returned as new value in every response, latest value is required in subsequent requests

required
object

Customer profile identifier

id
required
string <uuid>
ref
required
string

Initial session reference identifier

initiated_at
required
string <date-time>

Session initiated time

state
required
string
Enum: "OPEN" "CLOSED" "CANCELLED"

Current state of a session

tokens
required
Array of strings

A list of tokens

authorization_code
string
required
Array of objects

Data associated with tokens added to the session

Array
valid
required
boolean

Is the given token valid and known

message
string

Explains why the token is invalid

token
required
string

The token string

coupons
required
Array of strings

Coupons associated with the token

code
required
string

The code provided by the customer. E.g. The first 10 charachters of the bCODE.

required
Array of objects

A list of coupons from tokens

Array
id
required
string

Coupon identifier

name
required
string

Coupon name

status
required
string
Enum: "VALID" "INVALID" "ALREADY_REDEEMED" "EXPIRED"

Coupon status

token
required
string

The associated token

required
Array of objects

The items associated with this coupon

Array
sku
string

Item SKU

required
Array of objects

Item subsidies in effect when this coupon's criteria are met (VALID, relevant items in cart, etc)

Array
sku
string

Subsidised item SKU

value
number <double>

Amount of subsidy

coupon_id
string

Coupon identifier

required
Array of objects

Additional subsidies in effect when this coupon's criteria are met (VALID, relevant items in cart, etc)

Array
name
string

Subsidy name

value
number <double>

Amount of subsidy

coupon_id
string

Coupon identifier

required
Array of objects

Relevant items list

Array
sku
required
string

Item SKU

required
Array of objects

Session items list

Array
sku
required
string

Item SKU

price
required
number <double>

Item price

quantity
integer <int64> >= 1
Default: 1

Item quantity

name
string

Item name

category
string

Optional item category

Array of objects

A list of item subsidies in absolute values

Array
sku
required
string

Subsidised item SKU

value
required
number <double>

Amount of subsidy

coupon_id
required
string

Coupon identifier

Array of objects

A list of additional subsidies not relevant to items

Array
coupon_id
required
string

Coupon identifier

name
required
string

Name of subsidy

value
required
number <double>

Amount

object

All subsidies summary

item_subsidies_total
required
number <double>

Total sum of item subsidies

additional_subsidies_total
required
number <double>

Sum of additional subsidies

total
required
number <double>

Total sum of all subsidies

Response Schema: application/json
message
required
string

Error message

object

Error data

data
required
object
Response Schema: application/json
message
required
string

Request samples

Content type
application/json
Example
{
  • "ref": "my-ref-id-1"
}

Response samples

Content type
application/json
{
  • "id": "cs_lm65Qtbtv9b2NH0R2WcHf1Hq5Msp",
  • "consistency_id": "MTY1OTk1NTA4NjAxMF85Ng",
  • "customer_profile": {
    },
  • "ref": "my-ref-001",
  • "initiated_at": "2019-08-24T14:15:22Z",
  • "state": "OPEN",
  • "tokens": [
    ],
  • "authorization_code": "string",
  • "token_data": [
    ],
  • "coupons": [
    ],
  • "relevant_items": [
    ],
  • "items": [
    ],
  • "item_subsidies": [
    ],
  • "additional_subsidies": [
    ],
  • "subsidy_summary": {
    }
}

Tokens

The customer session api accepts { tokens: [...] }, an array containing tokens to apply during the customer session. If a hardware scanner is connected to the POS host, a token can be obtained using the /v2/token/scan api.

When no scanner is connected or to perform manual redemption, a manual token can be obtained using the /v2/token/encode endpoint.

Scan a Token

Is used to scan a token from a customers mobile device. Calling /v2/token/scan will trigger the scanner to begin listening for scans, and the red scanning light will be activated for the duration of the request.

When the scanner scans a bCODE, the request will return a token, which can be passed to the Transit API.

Exiting scanning mode
Cancelling the HTTP request will exit scanning mode and turn off the red scanning light on the hardware device.
query Parameters
attempts
integer <int64> >= 1
Default: 20

Maximum amount of times to attempt a scan

timeout
integer <int64> >= 1
Default: 30

Maximum time in seconds allowed for customer to scan

provider
string
Default: "transit"
Enum: "giftaway" "transit"

Used to specify the token provider. Defaults to transit

Responses

Response Schema: application/json
token
required
string
Response Schema: application/json
Any of
message
required
string
required
object
attempts
required
Array of strings
Response Schema: application/json
Any of
attempts
required
integer <int64> >= 1
message
required
string
Response Schema: application/json
message
required
string
Response Schema: application/json
message
required
string

Response samples

Content type
application/json
{
  • "token": "bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0"
}

Creating a Manual Token

Is used to encode input data captured manually by a cashier from a customers mobile device.

The response will contain a token, which can be passed to the Transit API.

Request Body schema: application/json
data
required
string

Data captured by cashier

provider
string
Default: "transit"
Enum: "giftaway" "transit"

Used to specify the token provider. Defaults to transit

Responses

Response Schema: application/json
token
required
string
Response Schema: application/json
message
required
string
required
object
data
required
string
Response Schema: application/json
message
required
string
Response Schema: application/json
message
required
string

Request samples

Content type
application/json
{
  • "data": "FIXED00002",
  • "provider": "giftaway"
}

Response samples

Content type
application/json
{
  • "token": "m_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0"
}