Upload
others
View
0
Download
0
Embed Size (px)
Citation preview
COMO API Version 4.3.0
Table of Contents
Introduction ..................................................................................................................... 1
Communication Format .................................................................................................... 2
Identification & Protocol ......................................................................................................................... 2
Request Format ....................................................................................................................................... 2
Response Format (error handling) .......................................................................................................... 3
Product & API Call Overview ............................................................................................. 4
Club Features .......................................................................................................................................... 4
Purpose of API Calls ................................................................................................................................. 5
Club Workflow ......................................................................................................................................... 6
General Guidelines ........................................................................................................... 7
Monetary Values ..................................................................................................................................... 7
Displaying Balances ................................................................................................................................. 7
Date Standard and Format ...................................................................................................................... 7
Synchronous Execution ........................................................................................................................... 7
Empty Fields ............................................................................................................................................ 8
API Call Specification ........................................................................................................ 9
getMemberDetails call ............................................................................................................................ 9
getBenefits call ...................................................................................................................................... 13
payment call .......................................................................................................................................... 17
cancelPayment call ................................................................................................................................ 20
submitPurchase call ............................................................................................................................... 23
cancelPurchase call ............................................................................................................................... 27
voidPurchase call ................................................................................................................................... 30
Field Details ................................................................................................................... 31
customer ............................................................................................................................................... 31
purchase ................................................................................................................................................ 33
items ...................................................................................................................................................... 34
membership .......................................................................................................................................... 36
assets ..................................................................................................................................................... 38
deals ...................................................................................................................................................... 40
redeemAssets ........................................................................................................................................ 42
benefits ................................................................................................................................................. 45
meansOfPayment .................................................................................................................................. 48
POS Configurations ......................................................................................................... 50
API Settings............................................................................................................................................ 50
Translations ........................................................................................................................................... 50
Flows ............................................................................................................................. 51
Main Flow .............................................................................................................................................. 51
Non-Members ....................................................................................................................................... 55
Refunds/Voids ....................................................................................................................................... 56
Multiple Members ................................................................................................................................. 57
Registration ........................................................................................................................................... 58
Advanced Payment ................................................................................................................................ 59
Redeemable Gift List ............................................................................................................................. 60
Gift List Inquiries.................................................................................................................................... 61
Discount Implementation ...................................................................................................................... 62
Tax-Excluded Countries ......................................................................................................................... 63
Version Changes ............................................................................................................. 64
Version Updates (4.3.0) ......................................................................................................................... 64
Version Updates (4.2.4) ......................................................................................................................... 64
I n t r o d u c t i o n | 1
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Introduction This document describes the Como API for external services that wish to integrate with the Como
customer engagement solution. While most of the document uses a POS semantic, all API calls can be
made from any kind of service with web access—including POS’s, e-commerce sites, vending
machines, gas station pumps, etc.
The Como API consist of the following API calls:
getMemberDetails
getBenefits
payment
cancelPayment
submitPurchase
cancelPurchase
voidPurchase
C o m m u n i c a t i o n F o r m a t | 2
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Communication Format
Identification & Protocol
The Como API is based on simple HTTP POST requests over HTTPS. Identification is performed using a
secret API key. Upon registering to the Como platform, each business is provided with their own
unique API key—so all request should be sent with the API key of the relevant business.
Como API Servers
Host: https://api.prod.como.com
Note: When a static IP is required, use the following host: https://static-api.como.com
Request Format
The POST body is a UTF-8 encoded object. The URL for the request should be built as follows:
1. API server host
2. Prefix path followed by the name of the API call
3. Query parameters – specific to each API call
Headers
Name Description Type Mandatory
Content-Type The request payload content type; should be 'application/json'. String Y
X-Api-Key The api key used for authentication String Y
X-Branch-Id The business branch identifier String Y
X-Pos-Id The identifier of the POS “terminal” that triggered the request String Y
X-Source-Type Origin of the transaction, such as POS, Website, or App String Y
X-Source-Name Integrator name (ex: POS name) that triggered the request String Y
X-Source-Version Software version of the integrator String Y
https://api.prod.como.com /api/v4/apiCall?apiCallParameters
1 2 3
C o m m u n i c a t i o n F o r m a t | 3
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Format (error handling)
The response is a JSON object. The "status" attribute returned in this object indicates success ("ok") or
failure ("error"). In case of failure, the response body will contain additional information which you
can inspect for debugging and error handling. For descriptions of specific errors that are returned and
guidance for when to display them to the cashier, click here.
errors properties
Field Description Type Returned
code Error code String Always
message Description of the error String Always
cause Optional object that holds the reason the error occurred Sometimes
{ "status": "error", "errors": [ { "code": "4001012", "message": "Customer(s) not found" } ] }
C l u b F e a t u r e s | 4
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Product & API Call Overview Como Sense is an end-to-end customer engagement solution that integrates with POS software to
provide a seamless customer experience. It provides businesses with a set of tools that work
together, including loyalty programs, a customized and branded mobile app, actionable data, and a
management console for creating the app, operating the loyalty program, and viewing analytics. The
loyalty club offers members rewards and incentives—like point accumulation, gifts, and punch cards.
The integration with POS systems and other third-party services enables Como to gather the data
required to deliver personalized and seamless customer experiences.
Club Features
Here’s an overview of the main features of a loyalty club.
Gifts Gifts are items members can redeem in the business—from products to discount
vouchers. Members can buy gifts in their app’s Point Shop using points or receive them
as a reward for joining the club, for their purchase, etc. Each gift can be redeemed only
once—using a code generated from the app or directly from the gift list on the POS.
Punch Cards Punch cards provide rewards to members after a certain number of purchases (such as
buy 9 coffees and get the 10th for free). Each time they make a purchase that’s eligible for
a punch, they automatically get a punch in their card after we receive the purchase
details. Once the card is full, they can redeem the card for a reward.
Deals Deals are reusable benefits or promotions that customers receive (such as 10% off their
entire purchase). Unlike gifts, deals do not need to be redeemed (they are automatically
applied) and they are not for one-time use.
Points Members can earn points for their purchase—which are automatically added once we
receive the purchase details. They can use points to buy gifts in the app’s Point Shop, to
redeem in the business. Businesses can also allow members to buy points, or buy items in
the business directly using their points.
Credit Credit can be accumulated, purchased or added—and then used as a form of payment to
purchase items from the business. Businesses can also allow members to use credit to
buy gifts from the Point Shop.
Mobile Payments Members can add credit cards to their app to use to pay for items in the business. When
they want to make a payment, they select a credit card from the list of cards they added
and tap Pay. The app then generates a payment (verification) code that they provide to
the POS. Learn more.
P u r p o s e o f A P I C a l l s | 5
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Purpose of API Calls
Below is a short summary of the main purpose of each API call.
getMemberDetails To display member details and gifts (also required to allow employees to select
gifts to redeem from the gift list)
getBenefits To redeem gifts (assets) and/or apply deals to the purchase
payment To pay for purchases using credit, points, or mobile payments
cancelPayment To cancel credit/point/mobile payments
submitPurchase To send purchase data (used to automatically give members points, punch their
punch cards, etc.)
cancelPurchase To cancel a purchase after the purchase is completed
voidPurchase To void a transaction before the purchase is completed
C l u b W o r k f l o w | 6
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Club Workflow
The diagram below shows when API calls are generated in a typical club flow.
1. The member identifies (ex: by phone number) and member details are displayed on the POS.
2. Items are added to the customer’s shopping cart.
3. Customers can choose which gifts to redeem. The cashier either enters redeem codes that
the member generates from their app or selects gifts from a list on the POS.
4. Upon subtotal, benefits (corresponding to gifts or deals) are applied to the purchase.
5. The customer pays using regular means of payment, and/or credit, points, or mobile
payments.
6. Purchase details are sent to the Como server.
G e n e r a l G u i d e l i n e s | 7
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
General Guidelines
Monetary Values
All monetary values (such as sum, totalAmount, discount, etc.) are presented in the API as follows:
• in the smallest unit of currency (for example, as cents and not dollars)
• positive when referring to a price or an amount paid by the customer
• negative when referring to a discount for the customer
Displaying Balances
All balances—such as point or credit balances—are returned with two values:
• monetary—How much the non-monetary balance is worth in currency according to the
conversion rate specified by the business (ex: what the points are worth in currency)
• nonMonetary—the balance (ex: number of points)
All balances are returned to the POS in the smallest unit of measurement (like cents). The POS should
divide all balances by 100 when displaying them on the POS, and display 2 values after the decimal.
Date Standard and Format
For all dates and times in the API, the ISO 8601 standard should be used—both for the request and
the response. Since UTC+00 is always used, the POS should convert the dates to local time for display.
There are two formats used in the API:
• format for Date: yyyy-MM-dd
• format for DateTime: yyyy-MM-ddThh:mm:ssZ (Z indicates UTC+00)
Synchronous Execution
All API calls—except for the voidPurchase call and the submitPurchase call with status=open—should
be handled synchronously. The POS is required to implement a time-out mechanism for when the
response is not received within a reasonable amount of time (around 5-10secs, taking into account
the internal POS environment routing times).
For the submitPurchase call with status=final, an asynchronous guaranteed delivery mechanism is
required for the following cases:
• if Como returns an error that begins with 5xx (representing a Como server error), or
• if there is a communication error on the side of the POS
We recommend trying to send it again twice close of the time of the purchase (since members are
waiting to see their rewards) and then trying again at the end of the day.
G e n e r a l G u i d e l i n e s | 8
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Empty Fields
The POS should not send fields that don’t have values.
g e t M e m b e r D e t a i l s c a l l | 9
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
API Call Specification
getMemberDetails call
Description
Purpose This API call is used to verify the customer is a club member, present their member
details (name, point balance, etc.) and present their gift list (to allow the cashier to
select which gifts to redeem directly from this list).
When to Use • To verify the customer is a club member
• When requested to display details or to select gifts to redeem
Notes Redeeming Assets
The getMemberDetails call is used to display a gift list, from which the cashier can
select gifts to redeem. However, benefits are only actually calculated using the
getBenefits call and redeemed using the submitPurchase call.
Related Flows Main Flow
Multiple Members
Registration
Redeemable Gift List
Gift List Inquiries
Discount Implementation
Tax-Excluded Countries
Request Format
See Communication Format for the structure of the URL and Headers.
Query Parameters
Name Description Type Mandatory
returnAssets
Which assets (i.e. gifts) to return. Options are:
• active—assets of the customer with asset status as active
• inactive—assets of the customer with any asset status except active
• all—assets of the customer with any asset status Note: If this parameter is not passed, no assets are returned.
String N
expand
List of response items to expand, i.e. provide more information about. Option is:
• assets.redeemable –Adds the redeemable flag to the assets, indicating if the asset is currently in a redeemable state and if not, why (requires returnAssets in the query and purchase in the body)
List of Strings N
g e t M e m b e r D e t a i l s c a l l | 10
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Body
Field Description Type Mandatory
customer Object representing a member’s identifier (ex: phone number) Customer Y
purchase Customer’s purchase details Purchase N
Request Example
POST https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customer": { "phoneNumber": "2128782328" }, "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 1200, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 1000 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 200 } ] } }
g e t M e m b e r D e t a i l s c a l l | 11
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Format
Field Description Type Returned
membership An object with member details Membership Always
memberNotes
An object representing a custom message that should be
displayed to the customer on the POS, with the following
(string) attributes:
• content—the message content
• type—whether the message is text (default) or URL
Sometimes
g e t M e m b e r D e t a i l s c a l l | 12
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Example
{ "status": "ok", "membership": { "firstName": "Jane", "lastName": "Smith", "birthday": "1995-03-03", "email": "[email protected]", "gender": "female", "phoneNumber": "2128782328", "status": "Active", "createdOn": "2016-05-19T10:19:08Z", "allowSMS": true, "commonExtId": "1d722661-0a94-4a36-8dea-ae23e5e3f440", "mobileAppUsed": true, "mobileAppUsedLastDate": "2017-06-15T10:12:29Z", "pointsBalance": { "monetary" : 2000, "nonMonetary" : 2000, "usedByPayment": false }, "creditBalance": { "monetary" : 1000, "nonMonetary" : 1000, "usedByPayment": true }, "assets": [ { "key": "60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8", "name": "Free Muffin", "description": "Free muffin with the purchase of a large coffee", "status": "Active", "image": "https://storage-download.googleapis.com/server-prod/images/giftimg.jpg", "validFrom": "2017-01-05T20:59:59Z", "validUntil": "2017-08-05T20:59:59Z" }, { "key": "1zikFHzdF1jLPqMXdqrfEkJ2rOAXTX9Cw4BFIfq48", "name": "Sandwich Coupon", "description": "$5 Off Sandwich", "status": "Active", "image": "https://storage-download.googleapis.com/server-prod/images/giftimg.jpg", "validFrom": "2017-01-05T20:59:59Z", "validUntil": "2017-08-05T20:59:59Z" } ] }, "memberNotes":[ { "content": "Deal of the month: 20% off milkshakes", "type": "text" } ] }
g e t B e n e f i t s c a l l | 13
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
getBenefits call
Description
Purpose This API call is used to apply benefits or promotions to the customer’s purchase—
by redeeming a customer’s gifts (assets) or by automatically applying deals. For
example, it can be 10% off their purchase or $5 off specific items.
When to Use Upon “subtotal” after all non-Como discounts are applied
Notes Sending the Request
• If this API call is called multiple times for the same purchase, make sure to clear
the previously returned benefits and add the new benefits each time.
• If the POS doesn’t support subtotal, the POS should present a dedicated button
(or an equivalent trigger before payment).
Applying Discounts
• The POS should allocate discounts as it is essential for the proper calculation of
Como rewards, reporting, displaying discounts to customers, and tax calculation
(see Discount Implementation).
• The total discount applied for each item (including Como or other discounts)
should not be greater than the item price.
Related Flows Main Flow
Multiple Members
Registration
Non-Members
Discount Implementation
Tax-Excluded Countries
Request Format
See Communication Format for the structure of the URL and Headers.
Query Parameters
Name Description Type Mandatory
expand
List of response items to expand, i.e. provide more information about. Options are:
• discountByDiscount - Shows how discounts should be allocated to specific items in the purchase
List of Strings N
g e t B e n e f i t s c a l l | 14
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Body
Field Description Type Mandatory
customers Array of member identifiers (ex: phone number) Customer N
purchase Customer’s purchase details Purchase Y
redeemAssets Array of the assets (gifts) that the member requested to redeem RedeemAssets N
Request Example
POST https://api.prod.como.com/api/v4/getBenefits?expand=discountByDiscount HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customers":[ { "phoneNumber": "2128782328" } ], "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 1200, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 1000 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 200 } ] }, "redeemAssets":[ { "key":"60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8" }, { "key":"1zikFHzdF1jLPqMXdqrfEkJ2rOAXTX9Cw4BFIfq48" } ] }
g e t B e n e f i t s c a l l | 15
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Format
Field Description Type Returned
deals An array of objects representing deals that should be
applied to a customer’s purchase Deals Sometimes
redeemAssets An array of assets (gifts) that the member requested to
redeem (including benefits that should be applied) RedeemAssets Sometimes
totalDiscountsSum Total sum of all discounts that should be applied (when the
benefit type is discount) Integer Sometimes
g e t B e n e f i t s c a l l | 16
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Example
{ "status": "ok", "deals": [ { "key": "30yj439fK2zfUrcrir9D37n3kf8orXpPJADN8fnj56", "name": "10% off purchase", "benefits": [ { "type": "discount", "sum": -120, "extendedData": [ { "item": { "code": "1111", "quantity": 5, "netAmount": 1000, "lineId": "1" }, "discount": -100, "discountedQuantity": 5, "discountAllocation": [ { "quantity": 5, "unitDiscount": -20 } ] }, { "item": { "code": "5555", "quantity": 1, "netAmount": 200, "lineId": "2" }, "discount": -20, "discountedQuantity": 1, "discountAllocation": [ { "quantity": 1, "unitDiscount": -20 } ] } ] } ] } ], "redeemAssets": [ { "key": "60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8", "name": "Free Muffin", "redeemable": true, "benefits": [ { "type": "dealCode", "code": "6543" } ] }, { "key": "1zikFHzdF1jLPqMXdqrfEkJ2rOAXTX9Cw4BFIfq48", "name": "Sandwich Coupon", "redeemable": false, "nonRedeemableCause": { "code": "5501", "message": "Conditions not satisfied" } } ], "totalDiscountsSum": -120 }
p a y m e n t c a l l | 17
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
payment call
Description
Purpose Allows customers to pay for their purchase using their credit, points, or mobile
payments
When to Use When the cashier taps a dedicated button to pay with Como payments
Notes Verification Codes
The business can secure these payments by requiring members to provide a
verification code at the POS. Members can generate it from their app or receive it
by SMS.
Related Flows Main Flow
Multiple Members
Advanced Payment
Discount Implementation
Tax-Excluded Countries
Request Format
See Communication Format for the structure of the URL and Headers.
Query Parameters
Name Description Type Mandatory
mode Function performed by the API call. Options:
• pay—used to perform a payment (default)
• query—used to query a balance Enum:pay|query N
p a y m e n t c a l l | 18
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Body
Field Description Type Mandatory
customer Object representing a member’s identifier (ex: phone number) Customer N
purchase Customer’s purchase details Purchase Y
verificationCode
Verification code provided by the customer—generated in the app,
or sent by SMS
Note: In many cases, this field is required for mobile payments and
point/credit payments.
String N
amount
Requested amount to pay in cents. It should be negative when
reimbursing the customer.
Note: See Tax-Excluded Countries
Integer Y
Request Example
POST https://api.prod.como.com/api/v4/payment HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customer": { "phoneNumber": "2128782328" }, "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ] }, "verificationCode": "9876", "amount": 600 }
p a y m e n t c a l l | 19
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Format
Field Description Type Returned
confirmation Payment identifier provided by the payment API call (also used for
cancelling the payment) String Always
payments
Object indicating how to apply a payment and the payment amount,
with these properties:
• paymentMethod— if the payment should be applied as a
discount, meanOfPayment or either
discountOrMeanOfPayment (Enum)
• amount—amount that should be applied as a
discount/payment towards the purchase (Integer)
Always
type
Indicates the payment type (string). Options are:
• memberCredit
• memberPoints
• creditCard (mobile payments)
Enum Always
details Additional details String Sometimes
updatedBalance
Object representing the customer’s new balance after the payment
with these properties:
• monetary
• nonMonetary
Note: This object isn’t returned if the type is creditCard.
Sometimes
Response Example
{ "status": "ok", "payments": [ { "paymentMethod": "meanOfPayment", "amount": -600 } ], "confirmation": "2b027fbd-d478-42d2-b7d9-9c7235ad6e5b", "type": "memberCredit", "updatedBalance": { "monetary": 400, "nonMonetary": 400 } }
c a n c e l P a y m e n t c a l l | 20
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
cancelPayment call
Description
Purpose This API call allows the POS to cancel a credit/point/mobile payment using the
confirmation code from the payment call.
When to use When the cashier taps a dedicated button to cancel the Como payment
Notes When the cancelPayment call is sent after the purchase is completed, the purchase
is not cancelled unless the cancelPurchase call is also sent.
Related Flows Refunds/Voids
Discount Implementation
Request Format
Field Description Type Mandatory
confirmation Confirmation code provided by the payment call String Y
purchase Customer’s purchase details Purchase N
c a n c e l P a y m e n t c a l l | 21
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Request Example
POST https://api.prod.como.com/api/v4/cancelPayment HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "confirmation":"2b027fbd-d478-42d2-b7d9-9c7235ad6e5b", "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ], "meansOfPayment":[ { "type":"memberCredit", "amount": 600 } ] } }
c a n c e l P a y m e n t c a l l | 22
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Format
Field Description Type Returned
type
Indicates which payment type was used (string). Options are:
• memberCredit
• memberPoints
• creditCard (mobile payments)
Enum Always
updatedBalance
Object representing the customer’s new balance after a
credit/point payment with these properties:
• monetary
• nonMonetary
Note: This object isn’t returned if the type is creditCard.
Sometimes
Response Example
{ "status": "ok", "type": "memberCredit", "updatedBalance": { "monetary": 1000, "nonMonetary": 1000 } }
s u b m i t P u r c h a s e c a l l | 23
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
submitPurchase call
Description
Purpose Once the transaction is completed, this API call is used to send Como a customer’s
purchase details—such as the total amount paid and the complete shopping cart.
These purchase details are used by Como to segment members or perform actions
on them—such as automatically punch their punch cards (based on specific items
in the cart), give them points or send them other rewards.
When to Use • After the final payment (sent with status=final)
• After applying the getBenefits response (sent with status=open)
Notes Sending the Request
• On final payment, the submitPurchase call should be sent for all purchases
(including purchases of non-members) to allow the business to receive
actionable data and BI on all their purchases.
• Since the submitPurchase call is the basis of the entire loyalty club, guaranteed
delivery is required for submitPurchase with status=final in the following cases:
if Como returns an error that begins with 5xx (representing a Como server
error), or if there’s a communication error on the side of the POS.
Related Flows Main Flow
Multiple Members
Registration
Non-Members
Refunds/Voids
Discount Implementation
Tax-Excluded Countries
Request Format
See Communication Format for the structure of the URL and Headers.
Query Parameters
Name Description Type Mandatory
status Indicates whether the transaction was finalized
(final) or not (open) Note: Default is final String N
s u b m i t P u r c h a s e c a l l | 24
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Body
Field Description Type Mandatory
customers Array of member identifiers (ex: phone number) Customer N
purchase The customer’s purchase details Purchase Y
redeemAssets
An array of the assets (gifts) that were applied or partially
applied to the purchase (using the getBenefits call)
Note: This allows us to mark the asset as used (since assets can
only be redeemed once).
RedeemAssets N
deals An array of deals that were applied or partially applied to the
purchase (using the getBenefits call) Deals N
s u b m i t P u r c h a s e c a l l | 25
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Request Example
POST https://api.prod.como.com/api/v4/submitPurchase HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customers":[ { "phoneNumber":"2128782328" } ], "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ], "meansOfPayment":[ { "type":"memberCredit", "amount": 600 }, { "type":"cash", "amount": 300 } ] }, "deals":[ { "key":"30yj439fK2zfUrcrir9D37n3kf8orXpPJADN8fnj56", "appliedAmount": -120 } ], "redeemAssets":[ { "key": "60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8", "appliedAmount": 0 } ] }
Note: The appliedAmount
should be 0 only if the benefits
type is itemCode or dealCode.
s u b m i t P u r c h a s e c a l l | 26
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Response Format
Field Description Type Returned
confirmation Confirmation code provided by the submitPurchase API call String Always
memberNotes
An object representing a custom message that should displayed to the
customer (ex: printed on the receipt), with these (string) attributes:
• content—the message content
• type—whether the message is text (default) or URL
Sometimes
Response Example
{ "status": "ok", "confirmation": "KYr2Zs4vabkuoANrzD9CkAzlsn9BQJO26i1Q09Cd69DmHlI8", "memberNotes":[ { "content": "Check your app to see your new point balance", "type": "text" } ] }
c a n c e l P u r c h a s e c a l l | 27
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
cancelPurchase call
Description
Purpose This API call allows the POS to cancel a transaction using the confirmation code
from the submitPurchase call.
When to Use When the cashier initiates a purchase cancellation
Notes Cancelling Payments
If a member pays for their purchases using the payment call and then cancels their
purchase using the cancelPurchase call, the payment is not cancelled unless the
cancelPayment call is also sent.
Related Flows Refunds/Voids
Request Format
See Communication Format for the structure of the URL and Headers.
Body
Field Description Type Mandatory
confirmation Confirmation code provided by the submitPurchase call String Y
purchase The customer’s purchase details Purchase N
c a n c e l P u r c h a s e c a l l | 28
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Request Example
Response Format
Only the status field (“ok”) is returned for a successful response.
Response Example
POST https://api.prod.como.com/api/v4/cancelPurchase HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "confirmation": "KYr2Zs4vabkuoANrzD9CkAzlsn9BQJO26i1Q09Cd69DmHlI8", "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ], "meansOfPayment":[ { "type":"memberCredit", "amount": 600 }, { "type":"cash", "amount": 300 } ] }
{ "status":"ok" }
v o i d P u r c h a s e c a l l | 29
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
voidPurchase call
Description
Purpose This API call allows the POS to void a transaction before it is complete (before the
submitPurchase call is sent with status=final).
When to Use When the cashier voids the transaction
Notes Cancelling Payments
If a member pays for their purchases using the payment call and then the purchase
is voided using the voidPurchase call, the payment is not cancelled unless the
cancelPayment call is also sent.
Related Flows Refunds/Voids
Request Format
See Communication Format for the structure of the URL and Headers.
Body
Field Description Type Mandatory
purchase The customer’s purchase details Purchase Y
Request Example
Response Format
Only the status field (“ok”) is returned for a successful response.
Response Example
POST https://api.prod.como.com/api/v4/voidPurchase HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 0 } }
{ "status":"ok" }
c u s t o m e r | 30
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Field Details
customer
customer is an object representing a Como club member identifier. By passing the customer object to
API calls, Como will process the API call using the identified customer.
Note: When the API call allows more than one customer in the request, the customers array is used
instead (with the same properties as customer).
Each customer has the type of the identifier as the key and the identifier as the value.
Properties (Types of Identifiers)
Field Description
phoneNumber Customer’s phone number
govId Locally relevant government issued ID number, driver’s license, etc.
memberId An external number representing the member like their membership card number
appClientId A temporary ID that the member generates from their app—presented as a number,
barcode or QR code
customIdentifier Custom identifier chosen by the business such as government ID or license plate number
Example
customers array
customer object
"customer": { "Customer1_Identifier_type":"Customer1_Identifier_value" }
{ "customers":[ { "phoneNumber":"534645645" }, { "phoneNumber":"3f09101f9" } ] }
{ "customer": { "phoneNumber": "534645645" } }
p u r c h a s e | 31
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
purchase
purchase is an object representing the customer’s purchase details. It should be sent in all API calls.
Field Description Type Mandatory
transactionId
Transaction identifier from the POS
Note: The same identifier should be passed in all API
calls for the same transaction.
String Y
openTime Transaction start time – should be the same value each
time this field is sent for the same transaction DateTime Y
relatedTransactionId
Transaction identifier from an external system (ex:
ordering system) – should only be sent if the transaction
was initiated in an external system
String N
totalAmount Total amount of the purchase in cents
Note: See Tax-Excluded Countries Integer Y
totalTaxAmount Total amount of tax applied to the purchase in cents
Note: Only reported for Tax-Excluded Countries Integer N
totalGeneralDiscount
Total amount in cents of all discounts that weren’t
apportioned to particular items (including Como
discounts and other discounts)
Integer N
orderType Type of transaction—such as takeaway, dineIn or
delivery String N
items An array of items in the current transaction Items N
meansOfPayment Array of payments made in the transaction (incl. the
payments made using the payment call that were
applied as means of payment)
MeansOfPayment N
tags
Array of strings—includes optional tags that are
available to the business
Note: The business specifies in API settings which
attributes correspond to tags.
String array N
employee ID or name of the current transaction operator (ex:
cashier) String N
i t e m s | 32
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
items
items is a list of items in the purchase—used by Como to calculate discounts and validate conditions
based on the customer’s shopping cart. It should be sent in the submitPurchase, getBenefits,
getMemberDetails and payment calls.
Properties
Field Description Type Mandatory
lineId Line reference number corresponding to the line item String Y
code Item identification code (i.e. PLU) String Y
name Human readable item name String Y
departmentCode Department code (or other relevant hierarchy code) String Y
departmentName Human readable hierarchy information String Y
quantity Number of times the item was purchased in this transaction Integer Y
weight
Weight of the current item for items priced by weight. It should
be in the highest unit of measurement (kg, pounds, liters, etc.)
Note: If the item is weighable, quantity must be 1.
This field is mandatory if the item is weighable. If not, this field
should not be passed.
Double N
grossAmount
𝑔𝑟𝑜𝑠𝑠𝐴𝑚𝑜𝑢𝑛𝑡 = (𝑔𝑟𝑜𝑠𝑠 𝑝𝑟𝑖𝑐𝑒 𝑝𝑒𝑟 𝑖𝑡𝑒𝑚)𝑥(𝑞𝑢𝑎𝑛𝑡𝑖𝑡𝑦 𝑜𝑟 𝑤𝑒𝑖𝑔ℎ𝑡)
where gross price is the price before it’s discounted (in cents)
Note: See Tax-Excluded Countries
Integer Y
netAmount
𝑛𝑒𝑡𝐴𝑚𝑜𝑢𝑛𝑡 = (𝑛𝑒𝑡 𝑝𝑟𝑖𝑐𝑒 𝑝𝑒𝑟 𝑖𝑡𝑒𝑚)𝑥(𝑞𝑢𝑎𝑛𝑡𝑖𝑡𝑦 𝑜𝑟 𝑤𝑒𝑖𝑔ℎ𝑡)
Total amount after any Como or other discounts were applied
(in cents)
Note: See Tax-Excluded Countries
Integer Y
action Type of action that’s performed for this line—values are: sale
(default) or refund Enum N
tags
Array of strings—including optional tags that are available to the
business and are relevant for the specific item
Note: The business specifies in API settings which attributes
correspond to tags.
String array N
i t e m s | 33
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Example
{ "items":[ { "lineId":"1", "code":"601040007", "name":"Prod1", "departmentCode":"123", "departmentName":"Dep1", "quantity":1, "grossAmount":400, "netAmount":400, "action":"sale", "tags":[ "Nestle", "dairy" ] }, { "lineId":"2", "code":"601040007", "name":"Prod1", "departmentCode":"123", "departmentName":"Dep1", "quantity":2, "grossAmount":800, "netAmount":800, "action":"sale", "tags":[ "Nestle", "dairy" ] }, { "lineId":"3", "code":"601040008", "name":"Prod2", "departmentCode":"456", "departmentName":"Dep2", "quantity":1, "weight":1.2415, "grossAmount":400, "netAmount":400, "action":"sale", "tags":[ "Organic", "produce" ] } ] }
items list with three items. The second item is
identical to the first item but with the
quantity of 2 (notice that the grossAmount
has doubled). The third item is a weighable
item (so it has quantity of 1).
m e m b e r s h i p | 34
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
membership
membership is an object representing the member (returned in the getMemberDetails call). Although
the business can configure other fields that will be returned, here are the main attributes:
Field Description Type Returned
firstName First name of the member String Sometimes
lastName Last name of the member String Sometimes
pushNotificationEnabled Whether the member enabled push notifications in the app Boolean Sometimes
locationEnabled Whether or not the member enabled location for the app Boolean Sometimes
mobileAppUsed Whether or not the member used their app Boolean Sometimes
mobileAppUsedLastDate Last login from the mobile app DateTime Sometimes
phoneNumber Member’s phone number String Sometimes
allowSMS Whether or not the member enabled SMS’s from Como Boolean Always
govId Locally relevant government issued ID number String Sometimes
commonExtId Member identifier for external purposes String Always
email Member’s email address String Sometimes
memberId External number representing the member (ex: membership
card number) String Sometimes
birthday Member’s birthday Date Sometimes
anniversary Member’s anniversary Date Sometimes
gender Member’s gender (options are defined by the business) String Sometimes
genericString1 A general purpose string variable String Sometimes
genericInteger1 A general purpose integer variable Integer Sometimes
genericCheckBox1 A general purpose boolean variable Boolean Sometimes
genericDate1 A general purpose date variable DateTime Sometimes
tag Business tags that provide additional information about the
member String Sometimes
assets An array of assets (gifts or punch cards) of the member Assets Sometimes
expirationDate Date that the customer’s club membership expires Date Sometimes
status Member’s club status. Options: Active, Inactive, Expired,
Pending Enum Always
pointsBalance Member’s current point balance PointsBalance Always
creditBalance Member’s current credit balance CreditBalance Always
m e m b e r s h i p | 35
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Balance Fields
A customer’s current point or credit balance is represented by the pointsBalance and creditBalance
objects, each with the properties below.
Field Description Type Returned
monetary
How much the non-monetary balance is worth in currency according to
the conversion rate specified by the business (ex: what the points are
worth in currency)
Integer Always
nonMonetary The balance (ex: number of points) Integer Always
usedByPayment Whether or not this balance is the one used for payment (via the
payment call) Boolean Always
Note: All balances are returned to the POS in the smallest unit of measurement (such as cents). The
POS is responsible to divide all balances (including points) by 100 when displaying them on the POS,
as well as display 2 decimal places.
a s s e t s | 36
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
assets
assets is an array of objects providing details on a member’s gifts or punch cards. Customers can
choose to redeem assets in the purchase for a benefit (such as a free drink).
The array can be obtained by calling getMemberDetails using the returnAssets query parameter, in
order to present a gift list to the customer.
Properties
Field Description Type Returned
key Unique identifier of the asset String Always
name Name of the asset String Always
description Detailed description of the asset String Always
status
The value can be:
• Active–asset has potential to be redeemed
• Redeemed—asset has already been redeemed
• Deactivated—asset was deactivated by the business
• Expired—asset’s expiration date has passed
• Future—asset is only valid from a future date
• In progress—asset cannot be redeemed in this purchase
String Always
image URL of the asset’s image String Always
validFrom Date and time from which the asset can be redeemed DateTime Always
validUntil Expiration date and time of the asset DateTime Always
redeemDate Date on which the asset was redeemed (returned only when the
status is Redeemed) DateTime Sometimes
redeemable Shows if the asset can be redeemed (returned only when the
query includes expand=assets.redeemable) Boolean Sometimes
nonRedeemableCause
When redeemable is false, object containing details of why the
asset cannot be redeemed, with these properties:
• code: Error code corresponding to the reason that the asset
cannot be redeemed (String)
• message: Reason the asset cannot be redeemed (String)
Sometimes
a s s e t s | 37
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Example
{ "assets": [ { "key": "3T6qGoLjHV7RRKkdfLLmH09CGve9AkVIa46R9BWhro8", "name": "$10 off purchase", "description": "Get $10 off a purchase over $40", "status": "Active", "image": "https://storage-download.googleapis.com/server-prod/images/giftimg.jpg", "validFrom": "2017-01-09T07:56:14Z", "validUntil": "2017-12-01T07:56:14Z", "redeemable": true } ] }
d e a l s | 38
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
deals
deals is an object which represents reusable benefits or promotions that customers automatically
receive (like 10% off for all club members). It is used in two ways:
1. getBenefits Response
In the response of the getBenefits API call, deals is an array of objects representing benefits that
should be applied to a customer’s purchase.
Field Description Type Returned
key Unique identifier for the deal—that should be sent in the
submitPurchase call if the deal was applied to the purchase String Always
name Human readable deal name String Always
benefits Array representing the benefits provided to the customer Benefits Always
2. submitPurchase Request
In the request of the submitPurchase API call, deals is an array of objects representing benefits that
were applied to a customer’s purchase (from the deals returned in the getBenefits call).
Field Description Type Mandatory
key Unique identifier for the deal—that was returned in the getBenefits call String Y
appliedAmount Discount amount applied to the purchase from the getBenefits deals Integer Y
{ "deals": [ { "key": "kjdsfh8734yrb34feh34", "name": "Spend $20 and get a free coffee", "benefits": [ { "type": "dealCode", "code": "1234" } ] }, { "key": "kjdhf984u3rjh9ujf3", "name": "10 percent off the purchase", "benefits": [ { "type": "discount", "sum": -200 } ] } ] }
d e a l s | 39
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
{ "deals": [ { "key": "kjdsfh8734yrb34feh34", "appliedAmount": 0 }, { "key": "kjdhf984u3rjh9ujf3", "appliedAmount": -200 } ] }
r e d e e m A s s e t s | 40
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
redeemAssets
redeemAssets is an object which represents personal one-time benefits that the customer wants to
redeem (like a coupon for $5 off their purchase). It is used in three ways:
1. getBenefits Request
To redeem a customer’s assets (gifts), the POS sends the getBenefits API call with the redeemAssets
array, where each array item points to an asset either by code or by key (but not both).
Field Description Type Mandatory
code
Code given by the customer to the POS—which was generated
from their app or presented on a coupon
Note: Either code or key should be sent, but not both.
String
Y
key Asset key provided in the response of the getMemberDetails call
Note: Either code or key should be sent, but not both.
String
{ "redeemAssets": [ { "code": "2003" }, { "code": "7689" }, { "key": "50i0JIztJ2jbTrMnhrv0LGSbzwY6cqXVBzhrnM48" } ] }
r e d e e m A s s e t s | 41
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
2. getBenefits Response
redeemAssets is then returned with additional fields specifying the benefits that should be applied to
the customer’s purchase, or indicating that the asset isn’t redeemable and why.
Field Description Type Returned
code
Code given by the customer to the POS—which was
generated from their app or presented on a coupon
Note: Either code or key is always returned, but not both.
String
Always
key
Asset key provided in the response of the getMemberDetails
API call
Note: Either code or key is always returned, but not both.
String
name Human readable name of the asset String Always
redeemable Shows if the asset can be redeemed Boolean Always
nonRedeemableCause
When redeemable is false, object containing details of why the
asset cannot be redeemed, with these properties:
• code: Error code corresponding to the reason that the
asset cannot be redeemed (String)
• message: Reason the asset cannot be redeemed (String)
Sometimes
benefits Represents the benefits that should be provided to the
customer (corresponding to the asset they want to redeem)
Benefits Always
{ "redeemAssets": [ { "code": "2003", "name": "Free Coffee", "redeemable": true, "benefits": [ { "type": "discount", "sum": -10 } ] }, { "key": "50i0JIztJ2jbTrMnhrv0LGSbzwY6cqXVBzhrnM48", "name": "Sandwich Deal", "redeemable": false, "nonRedeemableCause": { "code": "5501", "message": "The asset was redeemed" } } ] }
r e d e e m A s s e t s | 42
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
3. submitPurchase Request
redeemAssets should be also sent in the submitPurchase call—with all the assets (gifts) the customer
successfully redeemed in the purchase (with the fields below). This allows Como to mark the assets as
used (since assets can only be redeemed once).
Field Description Type Mandatory
code
Code given by the customer to the POS—which was generated from
their app or presented on a coupon
Note: Either code or key should be sent, but not both.
String
Y
key Asset key provided in the response of the getMemberDetails API call
Note: Either code or key should be sent, but not both.
String
appliedAmount Discount amount corresponding to the redeemed asset Integer Y
{ "redeemAssets": [ { "code": "2003", "appliedAmount": -10 } ] }
b e n e f i t s | 43
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
benefits
benefits is an array of objects representing the benefits provided to the customer when redeeming
assets (gifts) or using deals— such as a free coffee and 10% off their purchase. This array is returned
in the getBenefits API call (part of deals or redeemAssets).
Properties
Field Description Type Returned
type
Indicates how to apply the benefit to the purchase—options are:
• discount: discounts defined and calculated by Como (such as a
percentage or fixed amount off the entire purchase or specific
items)
• itemCode: used for actual catalog items in the POS system (like
an item with a lower price, zero price or negative price)
• dealCode: activates the POS's promotion system (like fixed
discounts, percentage discounts or triggers for POS
promotions)
String Always
sum Amount by which to discount the purchase when the type is
discount (negative sum) Integer Sometimes
code Code to add or activate on the purchase when the type is either
itemCode or dealCode String Sometimes
extendedData
Array representing the breakdown of how the discount should be
allocated to specific items in the purchase—returned only when
type is discount and expand=discountByDiscount is passed in the
query (see Discount Implementation)
ExtendedData Sometimes
ExtendedData Properties
Field Description Type Returned
item Object representing to the item that was discounted Item Always
discount Total discount that should be applied to the lineId
(negative sum) Integer Always
discountedQuantity
Number of items that are discounted from the items
corresponding to the lineId sent by the POS. Note: This
can be different than quantity due to discount
configurations in the Como management console
Integer Always
discountAllocation Array of different discount rates for the lineId since each
item can be discounted differently DiscountAllocation Always
b e n e f i t s | 44
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Item Properties
Field Description Type Returned
code Item code corresponding to the lineId item code sent by the POS String Always
quantity Quantity corresponding to the lineId quantity sent by the POS (even if
not all the items are discounted) Integer Always
netAmount Sum corresponding to the lineId sent by the POS Integer Always
lineId Line reference number corresponding to the line item that is discounted String Always
DiscountAllocation Properties
Field Description Type Returned
quantity Number of items corresponding to a specific discount rate (unitDiscount) Integer Always
unitDiscount Discount rate applied to each item from the corresponding quantity in
the discountAllocation array Integer Always
Examples
Without extendedData:
{ "benefits": [ { "type": "dealCode", "code": "1234" }, { "type": "discount", "sum": -10 } ] }
b e n e f i t s | 45
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
With extendedData:
{ "benefits": [ { "type": "discount", "sum": -700, "extendedData": [ { "item": { "code": "222", "quantity": 2, "netAmount": 3000, "lineId": "1" }, "discount": -300, "discountedQuantity": 2, "discountAllocation": [ { "quantity": 2, "unitDiscount": -150 } ] }, { "item": { "code": "111", "quantity": 1, "netAmount": 4000, "lineId": "2" }, "discount": -400, "discountedQuantity": 1, "discountAllocation": [ { "quantity": 1, "unitDiscount": -400 } ] } ] }
m e a n s O f P a y m e n t | 46
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
meansOfPayment
An array of payments that were made for the purchase (sent in the submitPurchase call under
purchase). This array should also include the payments that were made using the payment call, if they
were applied as a mean of payment (and not discount).
Properties
Field Description Type Mandatory
type Type of the payment—such as cash, credit_card,
cheque, memberCredit, etc. String Y
details Additional info like the payment confirmation number String N
amount Sum of the payment in cents Integer Y
paymentCard Object containing additional info on the payment card
used (such as credit card, debit card, etc.) PaymentCard N
PaymentCard Properties
Field Description Type Mandatory
cardType Type of card used (visa, mc, amex, etc.) String N
last4 Last 4 digits of the card number String N
cardholderName Name of card holder appearing on the card String N
first6 First 6 digits of the card number String N
expirationMonth Expiration month on the card String N
expirationYear Expiration year of the card String N
token Token String N
m e a n s O f P a y m e n t | 47
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Example
{ "meansOfPayment":[ { "type":"credit_card", "details":"jdfv87rnf8f", "amount":2000, "paymentCard":
{ "cardType":"VISA",
"last4":"1234", "cardholderName":"Jane Smith", "first6":"458023", "expirationMonth":"02", "expirationYear":"2020", "token":"12kjfg843krjf90f" } }, { "type":"memberCredit", "amount":1000 } ] }
P O S C o n f i g u r a t i o n s | 48
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
POS Configurations
API Settings
The business should be able to configure certain settings on the POS to support their specific needs.
Topic Setting Default
General If to show a pop-up at the start of each transaction to ask if they are a
member
No
Identification Which identification methods to display and the names All methods
If to show gifts or member details first after identification Member details
Gift List If to show all active assets or only redeemable assets in the gift list All active assets
Member Details Which membership details to display in addition to the default
First name, last name,
customer identifier,
status, points, credit
Points/Credit If to show the payment screen for points/credit Yes
If to apply a point/credit payment as a discount or mean of payment* Discount
Mobile Payments If to show the payment screen for mobile payments Yes
If to apply a mobile payment as a discount or mean of payment* Mean of payment
Registration If to use the registration flow, and if so, the membership item code Yes
Purchase
Which purchase attributes to send as purchase tags None
Which item attributes to send as item tags None
If to send submitPurchase with status=open before purchase is finalized No
If to send getBenefits for non-members** No
If to send submitPurchase for non-members** Yes
* Only required in tax-excluded countries (see Tax-Excluded Countries)
** When non-members request to redeem assets, both getBenefits and submitPurchase should be
sent regardless of these configurations
Translations
The POS should allow each business to translate and present translations for any text presented on
the POS interface to support the Como API.
M a i n F l o w | 49
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Flows The POS should support all the outlined flows—including the settings chosen by the business.
Main Flow
Step 1: Identify the member
1. The cashier selects to identify a member.
2. The cashier enters the member identifier.
3. The POS sends the getMemberDetails request (without returnAssets), with the following URL: https://api.prod.como.com/api/v4/getMemberDetails
Note: If the business configures to display the gift list first after identification (API settings),
then the request should be sent with returnAssets. Each time the cashier selects to display
the gift list, a new getMemberDetails request should be sent (to refresh the gift list which can
include different gifts).
UI Recommendations
There should be an option to allow
non-members to use coupon codes
without identifying (ex: Add Coupon
Code button).
UI Recommendations
The business configures which identifiers
to display and the names (API settings).
M a i n F l o w | 50
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
4. If the request succeeds: the POS displays the customer details and memberNotes (if sent).
5. If the request fails: the POS displays an error.
Step 2: Select gifts to redeem
The cashier can select the gifts that the member wants to redeem in two ways: by entering the
redeem codes (generated from the app), or by selecting the gifts directly from the gift list on the POS.
1. To select gifts using codes: the cashier enters the redeem codes.
UI Recommendations
Display:
• first name
• last name
• identifier (ex: phone number)
• status
• points (“pointsBalance” – monetary)
• credit (“creditBalance” – monetary)
• any other fields chosen by the business (see API settings)
Note: Both balances should be divided by 100 and display 2 decimal places. There should also be an indication for which balance is used for payment (ex: $)
UI Recommendations
Display:
• customer identifier (to discover typos)
• cancel button (so the invalid identifier will not be sent with purchase details)
• try again button
UI Recommendations:
If a customer wants to redeem multiple
gifts, all codes should be entered into the
same screen.
M a i n F l o w | 51
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
2. To select gifts from the gift list:
• The POS sends the getMemberDetails request, with the following URL: https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active
• The POS displays all assets (gifts) and the cashier selects which to redeem.
3. The POS saves the redeem codes and asset keys (corresponding to the gifts selected) and
displays a message to indicate that the discounts are only applied before payment.
Step 3: Apply benefits
Benefits corresponding to deals or selected gifts are applied to the purchase (see Discount
Implementation).
1. Upon “subtotal” (and after all non-Como discounts are applied), the POS sends a getBenefits
request (including any gifts that the member requested to redeem in Step 2).
2. If the request succeeds:
• All benefits in the response are applied to the purchase.
• For redeemAssets with redeemable as false, the POS displays an error.
3. If the request fails (indicating an error processing the request), the POS displays an error.
UI Recommendations
For each asset, display:
• name
• status
• validFrom
• validUntil
• image
UI Recommendations:
For each asset, display:
• gift name
• message and code from the nonRedeemableCause object
M a i n F l o w | 52
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Note: If getBenefits is sent multiple times (ex: shopping cart is changed after subtotal), it should
include the same asset keys/codes unless the cashier explicitly changed the selections.
Step 4: Pay with points or credit
1. When the cashier selects to pay with points/credit, the POS displays a payment screen.
2. The cashier enters the verification code (that the member generated from the app or
received by SMS) and confirms (or edits) the payment amount.
Note: Since a verification code is not mandatory in all cases, entering this code should not be
mandatory on this screen (although this field should always be displayed).
3. The POS sends a payment request.
4. If the request succeeds: the payment amount is applied to the purchase (as either a discount
or mean of payment, according to the paymentMethod in the response) and the POS displays
a pop-up with the updated balance.
Note: The amount that should be applied should be taken from the response since it may be
less than the requested amount (if the customer didn’t have enough in their balance).
5. If the request fails: the POS displays an error.
Step 5: Send a final submitPurchase
After the final payment, the POS sends a submitPurchase request with status as final.
UI Recommendations
Display:
• Either monetary points or credit balance (whichever has usedByPayment as true)
• payment amount should be autofilled but editable (with no limit for a max amount)
• “Generate Code” button—This button should trigger a payment request without a verification code. Although Como returns an error “Pending verification code”, this triggers Como to send an SMS to the member with a code. Once the member gives the code to the cashier, another payment request can be sent.
N o n - M e m b e r s | 53
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Non-Members
Non-members can also perform Como related actions—such as redeem gifts (using third party codes).
Their purchase details also provide the business with actionable data and BI. The business can
configure whether or not to send the getBenefits or submitPurchase calls for non-members (API
settings). However, getBenefits and submitPurchase should always be sent for members who request
to redeem assets.
Step 1: Enter coupon codes
1. The cashier selects to enter a coupon code.
2. The cashier enters the coupon codes.
3. The POS saves the coupon codes.
Step 2: Apply benefits
Benefits are applied to the purchase as in Step 3 of the main flow.
Step 3: Send a final submitPurchase
After the final payment, the POS sends a submitPurchase request with status as final.
UI Recommendations
There should be an option to allow non-
members to use coupon codes without
identifying (ex: Add Coupon Code button).
UI Recommendations:
If a customer wants to redeem multiple
gifts, all codes should be entered into the
same screen.
R e f u n d s / V o i d s | 54
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Refunds/Voids
Before a purchase is complete, specific items or the entire purchase can be voided. Once the
purchase is complete, customers may be able refund their entire purchase or only specific items
(depending on the business’ refund policy and local legal requirements).
Refund Purchases
Once a purchase is completed (after submitPurchase was sent with status=final), customers can
refund their entire purchase using the cancelPurchase call. However, if a payment was made using
the payment call, it is not cancelled unless the cancelPayment call is also sent.
Refund Items
Once a purchase is completed (after submitPurchase was sent with status=final), customers can
refund specific items in a separate transaction using the submitPurchase call. The refunded items
should be sent in a new transaction as follows:
• action should be refund
• quantity should be negative
• grossAmount should be negative
• netAmount should be negative
Void Items
Before a purchase is completed (before submitPurchase is sent with status=final), the cashier can void
specific items in the same transaction—for example, if a mistake was made or if the customer
changed their mind. In this case, the POS should clean the shopping cart before sending the
submitPurchase request—sending only the items that were actually purchased.
Void Purchases
Before a purchase is completed (before submitPurchase is sent with status=final), the cashier can void
the entire purchase using the voidPurchase call. For example, if customers change tables in a
restaurant, the waiter can void the current transaction and open a new one. If the customer
requested to redeem a gift in the first transaction and getBenefits was sent, sending voidPurchase
“unlocks” the gift so they can now redeem it in the new transaction.
M u l t i p l e M e m b e r s | 55
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Multiple Members
Multiple members can participate in the same transaction. The member whose details are currently
displayed on the POS is the “main member” on the purchase. The “main member” on the purchase
should be controlled from a single place—the member details screen.
Step 1: Identify all members
Step 1 from the main flow is performed for each member separately—where each getMemberDetails
request includes only the member currently being identified.
Step 2: Select gifts to redeem
Step 2 of the main flow is performed for each member that wants to redeem a gift. The cashier can
change the “main member” on the purchase to view and select their gifts.
Step 3: Apply benefits
Step 3 of the main flow is performed for all members together—so the getBenefits request includes
all the selected gifts (from all members). However, the “main member” should be passed first in the
customers array since only the deals of the “main member” are returned.
Step 4: Pay with points or credit
Step 4 of the main flow is performed for each member that wants to pay—where each payment
request includes only the member currently paying (“main member”). The cashier can change the
“main member” on the purchase to use their payment balance.
Step 5: Send a final submitPurchase
Step 5 of the main flow is performed for all members together—where all members should be passed
in the customers array but the “main member” should be passed first.
UI Recommendations
Display:
• Option to add another member to the purchase (ex: “add member” button)
• Option to change the “main member” on the purchase (ex: drop-down menu)
R e g i s t r a t i o n | 56
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Registration
New members can register to the club using the POS puchase registration flow—where the customer
is registered only after the POS sends the submitPurchase call with their phone number and a specific
membership item.
Note: If additional members are identified on a purchase that’s used to register a new member, the
registration will not succeed.
Step 1: Try to identify the customer
The customer tries to identify using their phone number—using step 1 of the main flow. Once the
POS receives an error (since the customer is not found), the POS displays a message with the option
to register the new member.
Step 2: Add membership item
The cashier selects to register the customer and the POS automatically adds a membership item to
their cart.
Note: The membership item is a dedicated item that the business adds to their catalog (either as a
paid item or free item). The membership item code is specified in the API settings.
Step 3: Apply benefits
Step 3 of the main flow is performed.
Step 4: Send a final submitPurchase
After the final payment, the POS sends a submitPurchase request with status as final—including the
customer’s phone number in the customers array.
Once Como receives the submitPurchase call with an unregistered phone number and the
membership item, the customer is either automatically registered or receives an SMS with a code to
enter into their app to register (based on the flow the business selects via Como).
UI Recommendations
Display:
• customer identifier (to discover typos)
• register button
• cancel button (so the invalid identifier will not be sent with purchase details)
• try again button—since in many cases, the error occurs because of a typo
A d v a n c e d P a y m e n t | 57
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Advanced Payment
In addition to paying with points or credit, members can pay with mobile payments.
Pay with Mobile Payments
Businesses can allow members to pay for their purchases using mobile payments—where members
can pay with credit cards that they added to their app. To secure these payments, members are
usually required to provide a verification code that they generate from their app. Learn more.
1. When the cashier selects to pay with mobile payments, the POS displays the payment screen.
2. The cashier enters the payment code (that was generated from the app) and confirms (or
edits) the amount.
3. The POS send a payment request.
4. If the request succeeds: the payment amount (from the response) is applied towards the
purchase.
5. If the request fails: the POS displays an error.
UI Recommendations
Display:
• payment amount should be autofilled but editable
• payment code field should be displayed but not mandatory to fill out
R e d e e m a b l e G i f t L i s t | 58
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Redeemable Gift List
Instead of presenting a gift list with all active assets (as in step 2 of the main flow), the business can configure in API settings to display only redeemable assets. In this case, the gift list includes only assets that satisfy advanced redeem conditions based on shopping cart. To show only redeemable assets, the POS sends the getMemberDetails request with: • https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active&expand=assets.rede
emable
• Purchase details are required to validate redeem conditions based on shopping cart If the request succeeds, only assets with redeemable as true should be presented in the gift list. Note: Each time the cashier selects to display the gift list, a new getMemberDetails request should be sent. Refreshing the gift list is essential since changes in the shopping cart can change which gifts are “redeemable” (and which gifts are displayed).
G i f t L i s t I n q u i r i e s | 59
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Gift List Inquiries
To allow the cashier to address customer inquiries regarding gifts that don’t appear in the gift list
(expired gifts, gifts that don’t meet the current conditions, etc.), the following flow should be
supported.
1. The cashier selects to display only inactive/non-redeemable gifts.
2. The POS sends the getMemberDetails request according to the API settings for whether the
gift list includes all active assets or only redeemable assets.
In other words, if the gift list displays all active assets, this list should display inactive assets. If
the gift list displays only redeemable assets, this list should displays only non-redeemable
assets.
Display URL Body
All inactive assets https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=inactive
Only non-redeemable
assets
https://api.prod.como.com/api/v4/g
etMemberDetails?returnAssets=inact
ive&expand=assets.redeemable
Purchase details are required to check
which assets cannot be redeemed
based on shopping cart
3. The POS displays the inactive/non-redeemable gift list.
UI Recommendations
For all inactive assets, display all assets from
the response. For only non-redeemable
assets, display only assets with redeemable
as false.
For each asset, display:
• name
• status
• validFrom
• validUntil
• image
D i s c o u n t I m p l e m e n t a t i o n | 60
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Discount Implementation
Customers can receive discounts in different ways—from the POS promotion system (non-Como),
Como benefits (deals and gifts) and Como payments applied as discounts.
Order of Discounts
Discounts should be applied to a customer’s purchase in the following order:
For Como benefits, deals should be applied before gifts. If the member requested to redeem a gift but
there is no discount left to apply (ex: relevant items are already free), the gift should not be passed in
submitPurchase at all so that the member can redeem it in a different purchase.
Note: The total discount applied for each item (Como or other) should not be greater than the item price.
Re-applying Discounts
If getBenefits needs to be sent again (ex: shopping cart is changed after subtotal):
1. Clear all discounts from the purchase (including Como benefits and discount payments)
2. Send cancelPayment if a payment was applied as a discount
3. Send a new getBenefits request—including the same asset keys/codes unless the cashier
explicitly changes the selection
Discount Allocation
Discounts should be allocated to the right items since Como rewards are based on which items are
discounted. For example, members can accumulate points at different rates for different items (ex:
10% on dairy, 5% on meat), or not receive punches for free items. Discount allocation also enables
accurate tax calculation for items that are taxed differently, and showing customers which items were
discounted.
The POS should reflect all discounts in the item price (netAmount). For Como benefits, discounts
should be: a) allocated according to extendedData, b) displayed to the customer according to the
specific deal or gift, and c) reported in submitPurchase in redeemAssets and deals.
Note: If the POS cannot allocate discounts as described due to technical limitations, contact the Como integration team to discuss which options are available.
T a x - E x c l u d e d C o u n t r i e s | 61
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Tax-Excluded Countries
For countries in which item prices are presented without tax, the POS should report certain amounts
without tax—so that benefits are calculated accurately and payments are properly applied.
Purchase
Amounts related to the item prices should be reported without tax—so Como can properly calculate
benefits like gifts and deals.
• In purchase: totalAmount should exclude tax.
• In items: grossAmount and netAmount should exclude tax.
However, the total tax on the purchase should be reported in totalTaxAmount in purchase.
Payments
Each business can configure whether a specific Como payment type (ex: points) should be applied as
a discount or as a mean of payment. This affects whether the payment is applied before or after tax.
To ensure the payment is properly applied, the following is required from the POS:
• Setting per business if to apply a specific payment type as a discount or mean of payment
• Separate payment screens for each payment type
• Payment amount in each payment screen should be autofilled according to the setting:
→ for discounts, the payment amount should exclude tax
→ for means of payment, the payment amount should include tax
For example, suppose the business configures in the POS settings that points should be applied as a
discount. In the dedicated point payment screen, the POS autofills the payment amount as the
amount without taxes. However, the amount should still be editable.
V e r s i o n C h a n g e s | 62
Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment
Version Changes Below is a summary of the changes that were made in the API doc since the last version (4.2.4).
Version Updates (4.3.0)
Gift Cards • Gift card functionality was removed from the document
submitPurchase • New object was added to meansOfPayment when the payment is made
using a card: paymentCard
API Settings • Separate settings for whether or not to send getBenefits or
submitPurchase for non-members, including the clarification that both
API calls should be sent when the non-member requests to redeem an
asset in the purchase
Version Updates (4.2.4)
General Guidelines • Clarification that the time-out mechanism should be around 5-10secs
• Clarification for the guaranteed delivery mechanism of submitPurchase
regarding when to try sending it again
To view a summary of the changes that were made in the API doc since the older versions, click here.
www.como.com