Transaction Fulfillment

Once a Partner application's backend receives a transaction initiation webhook notification and retrieves the transaction request information, it can begin fulfilling the request and updating the transaction response. The Partner application will likely need to communicate with proprietary services/systems to do so, which are referred to as the Partner fulfillment system below.

Immediate (sync) vs. Extended (async) Transaction Response Fulfillment

Transaction fulfillment may be an immediate process, in which case it would be appropriate for interactive transaction initiation workflows to keep users waiting on the application's UI while the process completes. This may also be an extended process, in which case it would be best to release the user once the transaction is validated and acknowledged by the integration. Partner integrations can easily model each type of fulfillment process on the EPC platform.

If transaction fulfillment is an immediate process, it would be appropriate to directly update the transaction with a completed response comprising of the completed response status, an internal partnerStatus and referenceNumber for the transaction, response loan data, resources (file attachments), and contact information for the fulfilling organization. Marking a transaction response completed closes the transaction from any further updates by the lender or Partner. Communication regarding the transaction's resolution can still occur via transaction events.

If transaction fulfillment is not immediate but an extended process, after validating the request and initiating the internal fulfillment process, it is required to first acknowledge intent to continue with transaction fulfillment. This can be done by updating the transaction response with a response status of processing, and including the transaction's internal partnerStatus and referenceNumber. If available, also include the contact information for the fulfilling organization. Transaction acknowledgement will kick-off certain workflows in the originating application, such as the creation of a tracking eFolder document in Encompass that helps lenders track transaction fulfillment.

Once the transaction request is fulfilled and it is time to deliver response loan data and resources (file attachments), the Partner application can update the response by setting the status to completed and including the updated partnerStatus, loan, resources, and fulfilling organization's information. Marking a transaction response completed closes the transaction from any further updates by the lender or Partner. Communication regarding the transaction's resolution can still occur via transaction events.

Application Response Processing

Once a Partner application delivers its completed response, including with loan data and resources (file attachments) via the Partner REST API, the EPC platform acknowledges the response update and forwards to the originating Encompass application for processing. Response processing is asynchronous, but the EPC platform delivers a webhook notification to the Partner application once a response is successfully processed. This is described in further detail in the section about transaction response events.

Step 1: Send a completed response and receive acknowledgement

Deliver a completed response with loan data, resources (file attachments), internal status, reference, and fulfilling party contact information. You will receive a 2xx HTTP response status as acknowledgement.

{
  "status": "completed",
  "referenceNumber": "TWX104356",
  "partnerStatus": "Appraisal Report Delivered",
  "respondingParty": {
    "name": "AAA Appraisers",
    "address": "3232 Loan Ave",
    "city": "Pleasanton",
    "state": "CA",
    "postalCode": "94588",
    "pointOfContact": {
      "name": "Scott Cooper",
      "role": "Co-ordinator",
      "email": "[email protected]",
      "phone": "343-222-1954"
    }
  },
  "loanFormat": "application/vnd.plm-2.0.0+json",
  "loan": {
    "propertyAppraisedValueAmount": "500000",
    "underwriterSummary": {
      "appraisalType": "Form 1004 appraisal with interior/exterior",
      "appraisalCompletedDate": "2020-04-24T19:00:04Z"
    }
  },
  "resources": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "AppraisalReport.pdf",
      "mimeType": "application/pdf"
    }
  ]
}

204 No Content

Transaction Display Field as part of response fulfillment
Partners can define which fields will be displayed on the Services Landing Page (SLP) in Encompass Web.

📘

NOTE

The ability to define the fields displayed on the Encompass LO Connect SLP will be supported in a future release. With the EPC Oct 2021 release, partners can test the feature in Encompass Partner Connect in preparation of the upcoming LO Connect release.

In order for the display fields to be shown on the SLP in Encompass Web the integration needs send the display as part of transaction response fulfillment under the displayFields object. The displayFields object in transaction response takes two attributes, label and value. The values of these two attributes are used by SLP to populate the detail grid. If the integration does not send any display fields, SLP will only show few standard information about the transaction such as Ordered Date, Ordered By, transaction status etc.

{
  "loan": {},
  "status": "completed",
  "resources": [],
  "loanFormat": "application/vnd.plm-2.0.0+json",
  "respondingParty": {},
  "displayFields": [
      {
         "label" : "Equifax",       
          "value": 730
      },
      {
         "label" : "Transunion",
          "value": 730
      },
      {
          "label" : "Equifax",
          "value": 730
      },
      {
        "label" : "Total Monthly Income Amount",
          "value": 20000
      }
    ]
}

Step 2: Receive Webhook for urn:elli:epc:transaction:event resource

This indicates that a new event has been created for the subject transaction and can be retrieved.

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

Step 3: Retrieve the created transaction event

To retrieve details of the transaction event, the Partner will call back into EPC. The callback URL is provided under the resourceRef property of the Webhook JSON payload, as shown in the example below:

{
  "text": "Transaction response successfully processed",
  "type": "urn:elli:epc:transaction:response:processed",
  "from": "System",
  "comments": "Transaction response successfully processed"
}

Once the transaction response has been successfully processed, the Partner application can synchronize its internal systems with the completed status for the transaction.