Electronic Property Settlement for banks

This is a brief description of the API calls most commonly used by banks. For full details about the request and response payloads, se the swagger documentation.

Find settlement

There are multiple ways of querying the Settlement API for an existing settlement.

Query by buyer

Finds settlements by buyers SSN

Query by buyer and property key

Finds settlements by buyers SSN and PropertyKey

Get by financial source

New feature

For settlement created with a list of financial sources (a list of organizations), each of the given financial sources may query settlements where they have been added without knowing the buyers ID. Read more about this feature here.

Get by unique identifier

Each settlement have a globally unique ID that may be used for getting a specific settlement.

Send intention

The flow for intentions could be something like this:

• Search settlement with buyerID

• If settlement exists

  1. The settlement contains information on the broker intention (and much more) and can be used in deciding flow and sending intention back to the broker

  2. Send the intention on that settlement as shown above

• If no settlement exists

  1. Build a complex intention request, containing the properties, buyers and organizationID of the broker, based on the purchase contract

  2. Send the intention to our intention endpoint (as shown below)

     When sending a complex intention, the service try’s to find a matching settlement. If no match is found, a proxy settlement is created. A proxy settlement is a bank created settlement that will serve as a handler for future communication with broker through AFPant. The service will check AKELDO to verify that the organization is able to consume intention messages from bank, or returns an error message.

  3. The request will return a response immediately with the settlementID of the proxy settlement

  4. In the background

     • This service will send the bank intention to the broker and wait for response

     • Once the response is received, the result will be populated onto the proxy settlement and a event is created to notify the bank about the response.

  5. Wait for broker response (polling for events or getting status of proxy settlement)

     This process is dependent on the polling frequency of both the producer and consumer of messages on the Altinn channel. Response is expected within a few seconds (at least 3 seconds)

  6. Once the response from the broker is available, the response will be available on the proxy settlement created.

  7. Use the intention response from the broker to decide further steps

Intention from Bank

The bank will assess a settlement, and provide an intention. The intention contains information whether the bank supports a digital flow or not as well as priority and amount information.

Note that the intention itself does not contain the mortgage documentation

Example request body:

{
    "capability": {
        "flow": "DIGITAL"
    }
}

Intention from Bank on non-existent settlement

Upcoming feature

For brokers not using Ambita’s services there will not exist any settlements when searching. In these cases, you can still communicate your intention and send the mortgage document to the broker, but the sequence of events are a bit different.

To be able to get the broker’s intention, you must first send the bank’s intention. You must therefore produce a full, more complex intention containing both the broker’s organizationID, the property and one or more of the buuyers to be able to send it. The response will contain a reference to a settlement, either from the broker (if match is found) or a created proxy settlement as described here.

This could be for all cases, as is searches for settlements first. However it requires more data. This could be used in a combination with the search for settlement for avoid requesting unnecessary information from the users, like brokers organizationID and properties.

Provide mortgage document

The document resource is used by the bank to upload mortgage documents. If a settlement was found in step two, the settlementuid should be given as a query parameter. The mortgage document will then be included in that settlement. For settlements not known to EPS, it is possible to give the broker’s organization number in the request body, and if EPS is not able to identify a settlement, the mortgage document will be uploaded to Afpant. This enable banks to collaborate with brokers even if the broker is not using Ambita’s services for electronic registration and settlement services.

For customers integrating etinglysing.no, this step is handled by “send to broker”.

Add attachment

Attachments are documents that relate to a document resource, like a prerequisite/term document. The resource has its own endpoint, but must be linked to the document.

For customers integrating etinglysing.no, this step handled by “send prerequisites”.