Using the contracts iFrame

Signing Process

sequenceDiagram

autonumber

actor m as Merchant
participant p as Partner
participant l as Liberis

p ->> l: Get contract pack status
l --) p: Pack status
p --) p: Get signatory from status
p ->> m: Display signingUrl in iFrame
    loop outstandingContracts
    l ->> m: Display contract and notices
    m ->> l: Sign contract
end
l --) p: Signatures complete (iFrame postMessage)

Each signatory returned by the contract pack status has a signingUrl that can be used
with an iframe to gather any missing signatures that an applicant must complete. The below snippet will render the contract inline with any existing page.

<iframe
  url="https://uat-contracts.liberis.com/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBcHBsaWNhdGlvbklkIjoiZTdiNjc4MGItZjRjMi00ZGZlLWEyMjMtOTFkYjllZWE4N2ViIiwiSXNQcmltYXJ5IjoiVHJ1ZSIsIlBhcnRuZXJDb2RlIjoiQ2xvdmVyIiwiZXhwIjoyMTQ3NDgzNjQ3fQ.2yDShurMm5PK_nKURDOV1hvniQrpsvRoiYAev3frYP0"
  sandbox="allow-same-origin allow-scripts allow-modals allow-popups allow-popups-to-escape-sandbox allow-downloads" />

The UI inside the iframe will progress through each individual contract that an applicant
must sign. Only the outstanding contracts will be shown. Once all contracts are signed a download page will be shown where the merchant can directly download each document.

PostMessage events are fired to indicate when each transition has occurred, allowing the
partner to capture the events and progress the overall journey UI on their application page.

PostMessages

The contract UI will output messages that can be received using a window event listener.
These hooks allow for the UI to be resized in case of larger contracts; capturing signing events for internal state; and knowing when a merchant has completed their full signing flow for journey continuation. For example:

window.addEventListener("message", e => {
  if (e.origin != "https://yyy.liberis.com") {
    return; // ignore
  }

  const payload = JSON.parse(e.data);
  // Do stuff with payload (e.g. update iframe height on containerHeight message)
});

Content height changes

Fires whenever the height of the content changes. This will be the first message received
after a contract loads and their may be multiple occurances as scrollbars disappear etc. The provided height is the exact height that should be used on the iframe to fit the content.

{
  "containerHeight": xxx
}

User clicks sign

Fires whenever the user clicks the sign button. This will be received before the loader
for the next contract shows.

{
  "trackingEventName": "Button Click",
  "trackingLabel": "sign-contract",
}

All contracts are signed

Fired once all contracts have been signed. This will be received before the download page
is shown. This is usually the point where a partner journey will want to allow the merchant to progress to the next page.

{
  "status": "SigningComplete"
}

User downloads a contract

Fired once the user clicks a download link for a given contract. This can happen on the
sign page (at the top of the contract viewer) and it can happen on the download page after all documents have been signed.

{
  "status": "download-requested",
  "url": "https://..."
}

User continues on the Download page

This is fired once the user click continue on the download page.

{
  "status": "ContractComplete"
}

Error

When an error occurs a screen will appear containing a back button. When pressed this
raises the following payload.

{
  "status": "ContractFailure",
}