Digital Product Voucher Tutorial
Overview
The Transit Merchant Network API allows many different customer interactions at the point-of-sale (POS). All of these customer interactions are enabled by three simple steps:
- Start a customer session and scan a token
- Exchange transaction information
- Close the customer session
In this example a customer wishes to redeem an Digital Product Voucher (EPV) that allows a subsidy to be applied to an item or a set of items.
A customer is sent a scannable SMS EPV that gives them a $2 discount on all Iron Beard shaving products during the month of August 2022 at select Big Apple stores. The customer goes to their nearest Big Apple store and gets three Iron Beard shaving products and a candy bar. The customer proceeds to the checkout till and presents their scannable SMS code.
Start a customer session
A customer session can be created with a PUT request to http://localhost:42000/v2/customer_session and providing a customer reference for the transaction. Example request body:
{
// customer provide transaction ref
"ref": "1b343e6b-e01e-4137-b843-a7461c5f853c"
}
The following response will be returned by the Transit Desktop Agent:
{
// customer session id
"id": "cs_8JFnpNtPzH3pPnWTwvvKYzqbRxHY",
"ref": "1b343e6b-e01e-4137-b843-a7461c5f853c",
// list of coupons associated with token
"coupons": [],
"additional_subsidies": [],
"state": "OPEN",
"initiated_at": "2022-08-11T12:45:23Z",
"subsidy_summary": {
"item_subsidies_total": 0,
"additional_subsidies_total": 0,
"total": 0
},
// list of products associated with the coupons - used when choosing items to check for subsidies
"relevant_items": [],
// token scanned from customers device sms
"tokens": [],
"items": [],
"customer_profile": {
"id": "d547e902-a5f6-4fa7-a43d-119c6b187fce"
},
// consistency id
"consistency_id": "MTY3NzY3OTMxMTcyNF8zNzI",
"item_subsidies": [],
"token_data": []
}
Exchange transaction information
The items in the customer's cart that the subsidy can be applied to need to be provided to the Transit Desktop Agent as a PUT request. In our example, the customer has four items in their cart:
- 2 x Iron Beard product 1 [sku 28480549],
- 1 x Iron Beard product 2 [sku 29548790] and
- 1 x candy bar [sku 45873620]
The relevant coupon(s) also need(s) to be added to the session. This can be done by manually encoding the token or by activating the hardware scanner to scan a coupon. The returned token then needs to be added to the session as well, e.g. bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0= is the token returned after a successful scan.
An example request body to http://localhost:42000/v2/customer_session could be as follows:
{
// id, ref and tokens provided in /v2/customer_session/scan response
"id": "cs_8JFnpNtPzH3pPnWTwvvKYzqbRxHY",
"ref": "1b343e6b-e01e-4137-b843-a7461c5f853c",
"consistency_id": "MTY1OTk1NTA4NjAxMF85Ng",
"tokens": [
"bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0="
],
"items": [
{
"sku": "28480549",
"price": 12.0,
"quantity": 2
},
{
"sku": "29548790",
"price": 17.0
}
]
}
Note the object contains the session id and only the relevant items in the customer's cart with their associated quantities and values.
The following response will be returned by the Transit Desktop Agent:
{
"id": "cs_8JFnpNtPzH3pPnWTwvvKYzqbRxHY",
"initiated_at": "2022-08-11T12:45:23Z",
"state": "OPEN",
"tokens": [
"bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0="
],
"token_data": [
{
"valid": true,
"token": "bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0=",
"coupons": [
"3731a4c9-e506-47a1-8115-a2b82c176a0e"
],
"code": "5ESNE6E4DD"
}
],
"consistency_id": "MTY1OTk1NTA4NjAxMF85Ng",
"customer_profile": {
"id": "c494ddf3-7160-4089-82e1-7e927394705",
"full_name": "John Big Beard"
},
"coupons": [
{
"id": "3731a4c9-e506-47a1-8115-a2b82c176a0e",
"name": "$2 Iron Beard August Sale",
"status": "VALID",,
"token": "bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0=",
"relevant_items": [
{
"sku": "28480549"
},
{
"sku": "29548790"
},
{
"sku": "19039547"
}
],
"item_subsidies": [
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "29548790",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
}
],
"additional_subsidies": [],
}
],
"relevant_items": [
{
"sku": "28480549"
},
{
"sku": "29548790"
},
{
"sku": "19039547"
}
],
"item_subsidies": [
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "29548790",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
}
],
"additional_subsidies": [],
"subsidy_summary": {
"item_subsidies_total": 6.0,
"additional_subsidies_total": 0.0,
"total": 6.0
}
}
The response above indicates that three items are covered by the EPV provided by the customer, however, the customer has only selected two of the three relevant items. Therefore, the request body will only include those two items. The total subsidy being offered is $6.00 as indicated by the total key in the subsidy_summary object.
Close the customer session
To lock in the transaction the customer session needs to be closed. A PUT to http://localhost:42000/v2/customer_session with the following request body will achieve this:
{
"id": "cs_8JFnpNtPzH3pPnWTwvvKYzqbRxHY",
"ref": "1b343e6b-e01e-4137-b843-a7461c5f853c",
"consistency_id": "MTY1OTk1NTA4NjAxMF85Ng",
"state": "CLOSED",
"tokens": [
"bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0="
],
"items": [
{
"sku": "28480549",
"value": 12.0,
"quantity": 2
},
{
"sku": "29548790",
"value": 17.0
}
]
}
The request object is unchanged from the earlier PUT request to http://localhost:42000/v2/customer_session, however, an additial state key is added with the value closed. This state can be altered to cancel to transaction too - please see the API reference for more information.
The Transit Desktop Agent will return the following response:
{
"authorization_code": "H4J86GH",
"id": "cs_8JFnpNtPzH3pPnWTwvvKYzqbRxHY",
"consistency_id": "MTY1OTk1NTA4NjAxMF85Ng",
"initiated_at": "2022-08-11T12:45:23Z",
"finalised_at": "2022-08-11T12:45:45Z",
"state": "CLOSED",
"tokens": [
"bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0="
],
"token_data": [
{
"valid": true,
"token": "bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0=",
"coupons": [
"3731a4c9-e506-47a1-8115-a2b82c176a0e"
],
"code": "5ESNE6E4DD"
}
],
"customer_profile": {
"id": "c494ddf3-7160-4089-82e1-7e927394705"
},
"coupons": [
{
"id": "3731a4c9-e506-47a1-8115-a2b82c176a0e",
"name": "$2 Iron Beard August Sale",
"status": "VALID",
"token": "bl_eyJ0eXBlIjoiYmNvZGUiLCJ2YWx1ZSI6IjdkYjM2NTcyYWE4N2QzZTNkMzE2YjJlYjMwMjM3MjQ0In0=",
"relevant_items": [
{
"sku": "28480549"
},
{
"sku": "29548790"
},
{
"sku": "19039547"
}
],
"item_subsidies": [
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "29548790",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
}
],
"additional_subsidies": [],
}
],
"relevant_items": [
{
"sku": "28480549"
},
{
"sku": "29548790"
},
{
"sku": "19039547"
}
],
"item_subsidies": [
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "28480549",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
},
{
"sku": "29548790",
"value": 2.0,
"coupon_id": "3731a4c9-e506-47a1-8115-a2b82c176a0e"
}
],
"additional_subsidies": [],
"subsidy_summary": {
"item_subsidies_total": 6.0,
"additional_subsidies_total": 0.0,
"total": 6.0
}
}