Contract Event Messaging

In some implementations of the Commerce API endpoints when our contract signing process is occurring within an iFrame in the Merchant site, it is necessary for the Merchant to observe events in the Lease cycle, like when the Customer has signed the Lease Contract, for example. Monitoring for these events allows you to better control the User's experience in your solution as well as providing event data to analytics solutions like Google Analytics and others. These events are communicated via the Window.postMessage() approach. A window can listen for dispatched messages by executing the following JavaScript:

window.addEventListener("message", (event) => {
  if (event.origin !== "")
  // ...
}, false);

For more information on this approach, additional documentation is available here.

The Messaging Service can emit the following messages:

EventMessageSuccess Property Included?Notes
"Initialize: App loaded"YesThis is called after the application has made all of the necessary calls and is now navigating to the lease summary/contract route.
Lease Summary Loaded"Lease Summary loaded"YesThis is called after the application has fully loaded and the content is ready to display to the customer.
"Consent: Initial Payment"NoThis is called when the user acknowledges the Initial Payment consent.
"Consent: Recurring Payment"NoThis is called when the user acknowledges the Recurring Payment consent.
"Consent: Refundable Lease Deposit"NoThis is only available if the lease has a refundable lease deposit. Currently, Project Lightning doesn't support RLD and this will not be emitted yet. But this is called when the users acknowledges the Refundable Lease Deposit consent.
Signatures"Signature: {X} of {Y}"NoThis is called for each signature block the user clicks on. X is the current index of the total Y amount of signatures.
Signatures"Signature: All completed"NoThis is called when the last signature block is clicked. The event "Signature: {X} of {Y}" will still be called on the last signature as well.
Download Button"Download: Pressed"NoThis is called when the "Download" button is pressed by the user.
Submit Button"Submit: Pressed"NoThis is called when the user click the "Submit" button.
Timeout"Timeout"NoThis will be called when a 30 minute timeout is reached. This is a fixed time as per our internal cacheing strategy.
For more information regarding timeouts, please refer to Handling Session Timeout
Post Processing"Post Process: Initiated"YesThis is currently being called when the user clicks the "Submit" button. But doesn't have any correlation to the "Submit" button. This call is made but we do not wait for the post processing to conclude. The call will send back a 200 if the Esign API call is successful. Not that the post processing has completed.

Each call has the following payload structure:

interface Message {
  message: string;
  success?: boolean;


The "Success" Field

The "Success" value (Yes or No), represents that the aforementioned success property will be included in the payload.