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 !== "http://example.org:8080")
    return;
  // ...
}, false);

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

The Messaging Service can emit the following messages:

Event

Message

Success Property Included?

Notes

Application
Loaded

"Initialize: App loaded"

Yes

This 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"

Yes

This is called after the application has fully loaded and the content is ready to display to the customer.

Consent
Acknowledgement

"Consent: Initial Payment"

No

This is called when the user acknowledges the Initial Payment consent.

Consent
Acknowledgement

"Consent: Recurring Payment"

No

This is called when the user acknowledges the Recurring Payment consent.

Consent
Acknowledgement

"Consent: Refundable Lease Deposit"

No

This 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}"

No

This 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"

No

This 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"

No

This is called when the "Download" button is pressed by the user.

Submit Button

"Submit: Pressed"

No

This is called when the user click the "Submit" button.

Timeout

"Timeout"

No

This 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"

Yes

This 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.


Did this page help you?