Transaction Initiation

Transaction initiation is the process by which lenders kick-off new transactions with a Partner. Lenders communicate their selected request type, options pertaining to the request, and resources (file attachments) in the transaction request to the Partner.

The Partner Connect platform supports 3 unique channels of transaction initiation for lenders, but enables (and encourages) Partner integrations to fulfill transactions from each initiation mode in a standard way.

1. Interactive Transaction Initiation - via Encompass Applications

When a user submits an order on a Partner application's UI (user-interface), the application initiates a transaction on the user's behalf. To create a transaction, the UI invokes the Partner JavaScript API's transaction.create method, which then invokes EPC's REST API to create the transaction and generate a new transaction ID in the method's response.

2. One-click/Automated Transaction Initiation - via the Encompass workflow engine

An integration's administrator-facing UI allows Lender administrators to create transactional templates. Once saved, these order templates are associated with certain business conditions in a loan. When those conditions are met, a transaction begins via a single click by a user, or via an automation engine using the template created by the Lender administrator.

3. Headless (API) Transaction Initiation - via Encompass Developer Connect

A UI is not involved. Lenders can invoke a service that orders APIs published on Encompass Developer Connect, supplying the necessary data inputs for a Partner integration to contextualize and fulfill an order. Lenders use these APIs to build proprietary automated workflows in their loan processing ecosystem.

Webhook Notifications: A Standard Process for Fulfillment

The EPC Partner API enables (and encourages) Partner integrations to be indifferent to a transaction's mode of origination. Notifications for all new transaction requests are received via the same mechanism (an HTTP callback), and can be similarly processed and fulfilled. This allows a single integration implementation to serve the breadth of interactive, 1-click, API-based, and automated ordering use-cases. This enables lenders to build powerful and intelligent service-ordering workflows.

Step 1: Listen for Webhook

Once a transaction has been initiated via any of these 3 modes of initiation, EPC sends a standard transaction initiation webhook notification to the application's backend informing it of this event:

{
  "eventTime" : "2020-05-02T11:08:52Z",
  "eventType" : "created",
  "meta" : {
    "resourceType" : "urn:elli:epc:transaction",
    "resourceId" : "{{TRANSACTION_ID}}",
    "instanceId" : "{{PRODUCT_NAME}}",
    "resourceRef" : "https://api.elliemae.com/partner/v2/transactions/{{TRANSACTION_ID}}"
  }
}

Step 2: Retrieve Request

The backend responds by calling back the EPC transactions REST API to retrieve the transaction request information, comprising of the lender's selected request type, selected options pertaining to the request, selected resources (file attachments), applicable loan data the Partner is entitled to access in the context of the request, credentials configured for the requesting user, and contact information for the requesting user and lending organization:

{
  "id": "0bf34a40-8ca1-4b58-8cbc-dd6b9f67dc63",
  "status": "completed",
  "clientId": "3010000024",
  "environment": "sandbox",
  "application": "LO Connect",
  "orderType": "MANUAL",
  "created": "2020-02-10T05:56:28Z",
  "createdBy": "urn:elli:service:soo",
  "entityRef": {
    "entityId": "urn:elli:encompass:BE11172718:loan:bd751bb3-0c26-407a-8846-8219bdda01a9",
    "entityType": "urn:elli:encompass:loan"
  },
  "product": {
    "id": "d714117c-247f-452e-9169-c112b6d24671",
    "partnerId": "99999999",
    "name": "test-product"
  },
  "request": {
    "type": "Appraisal",
    "loanFormat": "application/vnd.plm-2.0.0+json",
    "loan": {
      "property": {
        "city": "Pleasanton",
        "state": "CA",
        "county": "Alameda",
        "postalCode": "94588",
        "streetAddress": "4430 Rosewood Dr"
      },
      "loanNumber": "1911EM000412515"
    },
    "credentials": {
      "username": "donaldd",
      "password": "p@s$w0rd"
    },
    "requestingParty": {
      "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"
      }
    },
    "options": {
      "testOptionBool": true,
      "testOptionNumber": 100,
      "testOptionObject": {
        "testOptionBool": true,
        "testOptionNumber": 100,
        "testOptionString": "string"
      },
      "testOptionString": "string"
    }
  },
  "response": {},
  "events": [
    {
      "id": "e95f6f0e-85b2-43f3-bc56-0fb19944e823",
      "text": "Transaction Request Created",
      "type": "urn:elli:epc:transaction:request:created",
      "from": "System",
      "sent": "2020-02-10T05:56:28Z"
    }
  ]
}

Once the backend retrieves the request information, it can fulfill the request. This may be an immediate process, in which case it would be appropriate to keep the user waiting on the application's UI until it completes. This may also be an extended process, in which case it would be best to release the user after the transaction is validated and acknowledged by the integration.

The following sections illustrate how an EPC integration can model each type of fulfillment process.