Product Registration

One of the first things you need to when beginning to develop an integration on EPC, is to register an instance of your integration application with the EPC platform. This is done by invoking the POST HTTP operation on the https://api.elliemae.com/partner/v2/products resource.

An EPC product resource represents an instance of a partner application. Its data model encapsulates the various pieces of information that govern an application on the EPC platform. For example:

Environment and Status

Whether the instance is still in development and is only meant to serve sandbox/test transactions, or whether it has been approved to serve production transactions
Listing Information

How the partner integration is listed across the Encompass application suite
Routing Information

Where the application's user-interface is located and where it listens for webhook notifications
Credential Information

The credentials the application expects from Lenders and their users
Entitlements

The loan data an application is allowed to read and write to, and the instances of a specified Encompass product that are allowed to access the application

The example below shows how to create a new instance of an EPC product with basic configuration information (which will later be enhanced). In the sample EPC Postman collection provided, find the Create a New Product request in the Product Registration and Management folder. The product configuration options are to be supplied as JSON in the body of the request, as done below:

{
  "name": "{{product_name}}",
  "listingName": "{{product_listing_name}}",
  "interfaceUrl": "{{product_interface_url}}",
  "requestTypes": [
    "{{request_type}}"
  ],
  "tags": {
    "applications": [
      "LO Connect"
    ],
    "categories": [
      "{{service_category}}"
    ],
    "workflows": [
      "interactive"
    ]
  },
  "webhooks": [
    {
      "resource": "urn:elli:epc:transaction",
      "events": [
        "created",
        "updated"
      ],
      "signingkey": "TSuO$cRRSasmVr5RnQ8cqIkx^ugRFhOzI^bNGRwbu5P7B",
      "url": "{{webhook_url}}"
    },
    {
      "resource": "urn:elli:epc:transaction:event",
      "events": [
        "created"
      ],
      "signingkey": "TSuO$cRRSasmVr5RnQ8cqIkx^ugRFhOzI^bNGRwbu5P7B",
      "url": "{{webhook_url}}"
    }
  ],
  "credentials": [
    {
      "id": "username",
      "type": "string",
      "title": "Username",
      "secret": false,
      "required": true,
      "scope": "user"
    },
    {
      "id": "password",
      "type": "string",
      "title": "Username",
      "secret": true,
      "required": true,
      "scope": "user"
    },
    {
      "id": "organizationId",
      "type": "string",
      "title": "Organization ID",
      "secret": false,
      "required": true,
      "scope": "company"
    }
  ]
}

EPC product endpoints support the JSON merge specification for the PATCH operation that updates the product configuration, so not all these options have to be supplied in the first call. An iterative approach can be used for product registration: first register a product with minimal configuration options, then add configuration options in consequent calls.

Webhook Subscriptions and User Interface URL

To register a product, at least one backend webhook listener is required to be active and be able to receive transaction events. If you're running your application locally, the easiest way to create a webhook listener for development/testing is to use a tool like ngrok or specify a public endpoint from where you can tunnel traffic to your localhost in the products configuration.

The product's user-interface can also be served from a local machine or a hosted and publicly available endpoint during development/testing.

Webhook Signing Key

When subscribing for transactional webhooks, partners need to provide a shared secret signingkey - used by the EPC platform to generate a SHA256 hash-based message authentication code (HMAC) to deliver to partners as part of their webhook notifications. This key needs to be between 32 and 64 characters long, contain at least one upper case letter, one lower case letter, one number, and one character from this list: ! @ # $ ^ *.

Partner applications must use this signingkey to verify the integrity of the webhooks they receive - by calculating their own SHA256 HMAC signature of the webhook request body and comparing it with the Elli-Signature webhook request header - containing the signature the EPC platform calculated upon webhook egress. This verification process is described in more detail in the section on working with webhooks.

After the webhook listener and signingkey are created, the transaction webhook subscription can be registered by invoking the https://api.ellieme.com/partner/v2/products partner REST API endpoint. Update the request JSON body in Postman and click the Send button.

{
    "name": "ZipRight",
    "listingName": "Zipcode Validator",
    "interfaceUrl": "https://3d5e2d38.ngrok.io",
    "requestTypes": [
        "ZIP Code Validation"
    ],
    "webhooks": [
        {
            "resource": "urn:elli:epc:transaction",
            "events": [
                "created",
                "updated"
            ],
            "signingkey": "SWITCH_THIS_WITH_YOUR_HMAC_KEy1@",
            "url": "https://db0a1b1c.ngrok.io"
        }
    ]
}

The following response from EPC indicates successful registration:

{
    "id": "562a9740-2e27-44fd-8ff6-8731de6aa0fc",
    "partnerId": "YOUR_PARTNER_ID",
    "name": "ZipRight",
    "listingName": "Zipcode Validator",
    "requestTypes": [
        "ZIP Code Validation"
    ],
    "environment": "sandbox",
    "status": "development",
    "interfaceUrl": "https://3d5e2d38.ngrok.io",
    "integrationType": "ASYNC",
    "entitlements": {
        "access": {
            "allow": [],
            "deny": []
        },
        "data": {
            "origin": {
                "fields": []
            },
            "transactions": [],
            "created": "2019-11-18T23:57:14Z",
            "createdBy": "urn:elli:partner:007001:environment:test",
            "extensionCount": 0
        }
    },
    "webhooks": [
        {
            "subscriptionId": "b8fb8b38-22b4-46a5-b019-418c1fa61a7b",
            "url": "",
            "events": [
                "created",
                "updated"
            ],
            "resource": "urn:elli:epc:transaction"
        }
    ],
    "created": "2019-11-18T23:57:14Z",
    "createdBy": "urn:elli:partner:007001:environment:test"
}

The next section illustrates how to add more configuration options to the registered product.