Transaction Origination

Overview

The transaction origination process applies to user-interaction based modes of transaction initiation. It is the process via which a Partner application's UI is granted the temporary authorization to access specific information about the originating user, their parent organization, and their configured application credentials, including contextual information about the subject loan (as governed by their origin data entitlements) and existing transactions in whose context the user-interaction was initiated.

The process begins when an Encompass application user launches a Partner application's UI. The user implicitly grants the application short-lived access to specific information about themselves, the lender, and the subject loan.

To avail this temporary entitlement, one of the first things an application's UI needs to do on-load is invoke the Partner JavaScript API's transaction.getOrigin method and receive a fresh originId and partnerAccessToken in the response.

📘

How temporary? 🕒

The originId and partnerAccessToken are only valid for 300 seconds once generated.

If your tokens expire, call back the JavaScript API's transaction.refreshOrigin method to generate new ones.

This is like a secure authorization handshake between the guest Partner application and host Encompass application. It grants the Partner application a set of "session" tokens which need to be forwarded to the application's backend to invoke the Partner REST API's GET https://api.elliemae.com/partner/v2/origins/:id endpoint, and retrieve the user/organization/credentials/loan information it is temporarily entitled to access. After this, the Partner application's backend can authenticate the subject user, and subsequently return relevant loan information to its UI for contextual display.

Step 1: Access current originId and partnerAccessToken

Upon the UI loading, invoke the JavaScript API's transaction.getOrigin method to receive a fresh origin ID and partner access token in the response.

async function initializeOriginationContext() {
  try {
    const transactionObject = await elli.script.getObject('transaction')
    const originationContext = await transactionObject.getOrigin()

    applicationState.originId = originationContext.id
    applicationState.partnerAccessToken = originationContext.partnerAccessToken
    if (originationContext.transactionId) {
      applicationState.transactionId = originationContext.transactionId
    }
  } catch (error) {
    console.log({error})
  }
}

initializeOriginationContext()

Step 2: Forward tokens to application back-end

Forward both the originId and partnerAccessToken to the application's backend so it can invoke the Partner REST API's GET https://api.elliemae.com/partner/v2/origins/:id endpoint and retrieve the user/organization/credentials/loan information it is temporarily entitled to access.

// Initializor function to update user-interface application state with origin data
  const initializeOriginInformation = async (originId, partnerAccessToken) => {

    // Assume OriginService is a client module that encapsulates the
    // user-interfaces communication with the applications back-end
    const origin = OriginService(originId, partnerAccessToken);
    const originLoanData = await origin.getOriginLoanData();
    setInitializationInformation(originLoanData);
  };

...

Step 3: Invoke the Partner REST API to retrieve origin data

Invoke the Partner REST API's GET https://api.elliemae.com/partner/v2/origins/:id endpoint from the application's backend to retrieve the user/organization/credentials/loan information it is temporarily entitled to access.

{
  "id": "5824a99b-64f2-4dd4-bdaf-b6ec31601f5e",
  "entityRef": {
    "entityId": "urn:elli:encompass:BE11177525:loan:c1613163-fa00-4b17-969c-a029c0637c6d",
    "entityType": "urn:elli:encompass:loan"
  },
  "loanFormat": "application/vnd.plm-2.0.0+json",
  "loan": {
    "property": {
      "streetAddress": "4430 Rosewood Dr          ",
      "city": "San Ramon",
      "state": "CA",
      "postalCode": "94583",
      "county": "Contra Costa",
      "loanPurposeType": "ConstructionOnly",
      "propertyUsageType": "SecondHome"
    }
  },
  "interfaceUrl": "https://lender.product.io/",
  "product": {
    "id": "05829be3-939d-4a12-9fac-31442715a6d4",
    "partnerId": "99999999",
    "name": "test-product"
  },
  "credentials": {
    "username": "donaldd",
    "password": "p@s$w0rd"
  },
  "environment": "sandbox",
  "originatingParty": {
    "name": "AMG Mortgage",
    "address": "4140 Dublin Blvd. # 301 ",
    "city": "Santa Maria",
    "state": "CA",
    "postalCode": "93458",
    "pointOfContact": {
      "name": "Donald Duck",
      "role": "Loan Officer",
      "email": "[email protected]",
      "phone": "666-666-6666",
      "personas" : ['Loan Officer', 'Closer']
    }
  }
}

After retrieving the transaction origin information, the Partner application's backend can authenticate the subject user, and subsequently return relevant loan information to its UI for contextual display.