Send Transaction
Transaction sending allows for SessionM to process and send transaction details in near real-time from both e-commerce platforms and point of sale systems. The calls in this API should be done asynchronously to not slow down user queue processing speeds. In the event of an integrating location going offline, all transactions should be stored on-premises for the duration of the offline event and batched back to SessionM when the location regains network connectivity.
Send Transaction API
Sends SessionM transaction details when a location is online. This API addresses two scenarios:
- Online state (Communication Processed to SessionM)
- Offline state (Logging Transactions to Disk)
It is important to note that if a user is not associated to the transaction (through User Lookup or offer application through Discounting) AND post-transaction association is enabled for the specific user, a globally unique QR Code should be generated and passed to SendTransaction. If a single payment was used, this would be passed as the Transaction receipt_code property. If multiple payments were used, this would be passed as the Payment Object receipt_code property.
The value of the QR Code that is printed should be of the format: https://[custom url configurable per client]/[QR CODE VALUE]. Only the QR CODE VALUE should be passed through the SendTransaction API. To generate a globally unique QR Code value, SessionM recommends using a UUID construct of whatever programming language that is being used. For example: .NET would use GUID; Java would use UUID; and Ruby would use SecureRandom.uuid.
For more information on this process flow, consult your Customer Success contact.
Endpoint
This API offers the following endpoint:
Endpoint Parameters
Not applicable.
Request Object
When this endpoint runs, it passes in a Transaction request object. When using this API, pass in the request_payload as the Transaction object, which is detailed in the following tables:
Request Properties for Transaction
| Property | Type Required/Optional |
Description |
|---|---|---|
| pos_employee_id | string required |
Client system employee_id for the employee who should be associated to this transaction. Maximum of 20 characters. |
| sm_employee_id | string optional |
SessionM user_id for the employee, which is only required for clients that have an employee reward program. |
| table_id | string optional |
Client system table_id for where the user was seated. For retail or e-commerce, this value is not used. Maximum of 20 characters. |
| guest_count | int optional |
Number of guests serviced by this transaction. |
| is_closed | bool required |
Indicates whether this is the final state for the transaction. Should only be closed once the check is finalized and closed. This is when any discounts that were locked will be applied. |
| is_voided | bool required |
Indicates whether this transaction was voided. If a transaction is voided, the value is true . Any and all loyalty earnings gained from association to this transaction will be removed. |
| transaction_id | string required |
Unique transaction identifier that should correspond to any and all future updates for this transaction. Maximum of 64 characters. |
| from_transaction_id | string optional |
In the event of a split transaction, this should reference the parent transaction that this transaction was split from. Maximum of 64 characters. |
| subtotal | decimal required |
Subtotal without tax included of the transaction. This subtotal should reflect all of the applied discounts. |
| tax_total | decimal required |
Total amount of tax for the transaction. If the tax for a certain item was included in the tax_included property of the Item object, it should not be included in the total tax accounted for in this property. |
| open_time | DateTime required |
Date and time that this transaction was opened or created. This value should remain consistent for all correspondence regarding this transaction. Should be JavaScript JSON date time format. (yyyy-MM-ddTHH:mm:ss.fffZ) and be passed as the UTC date and time. |
| modified_time | DateTime required |
Date and time that this transaction was last modified and triggered the update call to SessionM. Should be JavaScript JSON date time format. (yyyy-MM-ddTHH:mm:ss.fffZ) and be passed as the UTC date and time. |
| guest_receipt_code | string optional |
The globally unique across all client transactions receipt code printed on the guest check. If no guest check is printed, this can be null. |
| channel | string required |
Channel from which this transaction originated. For example, “STORE” or “ECOM” or “KIOSK”. Only used for client aggregation reporting. Values can be whatever the customer would like, but must be consistent across all instances of the same channel. Example values could be “IN-STORE”, “CARRY OUT”, and “DRIVE THROUGH”. |
| items | Item[] required |
Current collection of item objects that make up this transaction. |
| payments | Payment[] required |
Current collection of payment objects for this transaction. Note, if there are no payments applied this should be an empty array. |
| discounts | Discount[] required |
Current collection of discount objects for this transaction. Note, if there are no discounts applied this should be an empty array. |
| custom_data | JSON-formatted data | Additional transaction-level data that can be carried into the SessionM Platform for custom use cases. Intentions for use must be vetted with the SessionM Team prior to implementation to ensure that data can be leveraged properly. |
| business_def_collection | JSON-formatted data | Current collection of business defined objects for this transaction. Business defined objects allow a user of the platform to define custom attributes that will be ingested by the SessionM Platform. Please work with your SessionM team to define use cases around this collection. Note, if there are no business defined attributes applied to the transaction, this should be an empty array. |
Request Properties for Item Objects
| Property | Type Required/Optional |
Description |
|---|---|---|
| line_id | string required |
Unique, within-this-transaction, ID for this transaction line item. This is used for reference for modifiers and line item discounts. These values should remain consistent across subsequent requests. |
| item_id | string required |
Client system unique item_id. Maximum of 45 characters. |
| quantity | decimal required |
Quantity purchased for this item. |
| unit_price | decimal required |
Unit price for 1.0 quantity for this item. |
| subtotal | decimal required |
Subtotal for this line. Should reflect unit_price * quantity = subtotal. |
| tax_included | decimal required |
Amount of tax represented in the subtotal. Should only be used when the unit_price includes tax and should not be used for check-level taxes such as sales tax. Any tax that is represented at at item level via this property should not be included in the total transaction-level tax accounted for in the tax_total property. |
| modifies_line_id | string optional |
If this item is a modifier for another item, this is the line_id of the item it modifies. Modifier prices should not be reflected within the unit_price or subtotal of the item being modified. |
| custom_data | JSON-formatted data | Additional item-level data that can be carried into the SessionM Platform for custom use cases. Intentions for use must be vetted with the SessionM Team prior to implementation to ensure that data can be leveraged properly. |
Request Properties for Payment Objects
| Property | Type Required/Optional |
Description |
|---|---|---|
| payment_id | string required |
The unique, to this transaction, payment ID, assigned by the client system. Maximum of 64 characters. |
| amount | decimal required |
Total amount of this payment applied to the transaction. |
| type | string required |
Type of this payment. Example values: “Cash”, “Credit Card”, “Gift Card”, “Certificate”. Maximum of 20 characters. |
| payment_time | DateTime required |
Date and time when this payment was applied. Should be JavaScript JSON date time format. (yyyy-MM-ddTHH:mm:ss.fffZ) and be passed as the UTC date and time. |
| user_id | string optional |
User ID that is applied to this payment. |
| user_id_type | string optional |
Required when user_id is passed. This is used to determine the lookup type for a loyalty account. The lookup type provided must be configured as a required field and guaranteed unique within the program configuration. Legal values: “SessionM_ID”, “Email”, “SOR”, "External_ID". |
| additional_user_id | string optional |
Additional user ID applied to this payment. Depending on program structure, this could be used for reporting purposes or where multiple user accounts within a hierarchy should be rewarded. |
| additional_user_id_type | string optional |
Required when additional_user_id is passed. Used to determine the lookup type for a loyalty account. Lookup type provided must be configured as a required field and guaranteed unique within the program configuration. Legal values include: “SessionM_ID”, “Email”, “SOR”, "External_ID". |
| receipt_code | string optional |
The globally unique, across all client transactions, receipt code printed on the payment check. If a user was looked up and a user_id provided, this can be null. |
| custom_data | JSON-formatted data | Additional payment-level data that can be carried into the SessionM Platform for custom use cases. Intentions for use must be vetted with the SessionM Team prior to implementation to ensure that data can be leveraged properly. |
Request Properties for Discount Objects
| Property | Type Required/Optional |
Description |
|---|---|---|
| reference_id | string required |
Reference ID of the discount. If this is a SessionM provided discount, this should be the provided user offer id. If this a discount provided from another system, it should be the identifier that uniquely identifies this discount within the transaction. |
| reference_id_type | string required |
Will be used to be echoed back in Discounting APIs. |
| pos_discount_id | string optional |
If passed, can be used to apply the discount from the point of sale side linking the discount details below to the discount on the point of sale for reporting purposes. |
| status | string optional |
When this is provided in the response from any of the Discounting APIs it should be echoed back in subsequent transaction updates. Valid values are “LOCKED” or “REDEEMED” or “INFO” or “OFFLINE”. Note: The OFFLINE status should ONLY be used for offline transactions. This will skip any validation or restriction checks and force the offer to be removed from the user’s wallet. In the event the offer is no longer available due to expiration or being used by another online transaction, this will fail without notification back to the point of sale. OFFLINE should only ever be used to ensure that an offer is no longer available in a user’s wallet. |
| display_name | string required |
Name of the discount. |
| image_url | string optional |
Image URL associated with this discount. |
| discounted_line_ids | string[] optional |
If this discount is applied to one or more items within the transaction this should contain the line_id of what items were discounted. If this is a check level discount not applied to any specific items, this can be null. |
| discounted_line_id_quantities | string[] optional |
This array is aligned with the indexes from the discounted_line_ids property and specifies the quantity for each line to which the discount was applied. If this property is not passed, the discount is evenly distributed across the entire quantity specified for that line (which could adversely impact discount calculation in stacking scenarios). For example, if line_id “1234" was purchased with quantity "4", and a $10 discount was applied to the line_id, a discounted_line_id_quantities of “2” indicates that the $10 discount should be spread across only the first two items within that line_id ($5 per item). |
| discount_source | string required |
Source system for the discount. Example: If this discount was provided by SessionM the source should be “SessionM”. If this is a discount such as an employee discount the source could be “POS”. |
| amount | decimal required |
Amount of the discount applied to the check. |
| stack_order | int required |
Order in which this discount was applied. If it is the only discount on the check, this value should be 0. (For multiple discounts use order example: 0 => 1 => 2 => 3 => etc.) |
| applied_time | DateTime required |
Date and time that this discount was applied to the transaction. This should be JavaScript JSON date time format: (yyyy-MM-ddTHH:mm:ss.fffZ); and, it should be passed as the UTC date and time. |
| user_id | string optional |
Returned from the Lock and Redeem calls, this is the SessionM user’s identification. |
Response Object
The Transaction Response object will just be the generic response object with no payload, by which a 200 HTTP status code means it was received successfully. A 403 HTTP status code means the request was unauthorized or contained invalid credentials. A 500 HTTP status code means the call was unsuccessful and should be resubmitted.