Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

This page is for banks that will collaborate with a broker and have not (or will not) start the collaboration process by requesting purchase contract from the broker.

Before you can start

EPS uses Oauth2 Bearer token for authentication.. If you do not have been issued a client_id, contact Ambita to get one. If you already have a client, the client must be granted access to EPS by Ambita.

Se Token-based authentication - quick start for more information about how to create an access token and use it in requests to EPS.

Terms used in this page

Term

Norwegian

Description

Intention

Flow

Intensjon

Flyt

These two are both used to declare how each party (broker and bank) wants to/is able to do the registration (Paper or Digital)

Registration

Tinglysing

Having the documents accepted into the official Land Registry

Mortgage document

Pantedokument

Deed

Skjøte

Document for transfer of ownership

Settlement

Oppgjør

A representation of the broker’s data in EPS.

Prerequisite letter

Forutsetningskrav

An attachment to the pantedokument that is sent to the broker stating the bank’s requirement (having first priority, and so on).

Why sending intentions

The bank and broker have to agree on the registration process, whether it is on paper or digital documents since the deed and mortgage document must be sent together to the registration authority (Statens Kartverk). Both parties must know this in order to print contract and have them signed “manually” or have the digital documents generated and signed with Bankid.

Intentions are the way bank and broker communicates their preferred registration method to each other. Note that both parties must be capable of doing this digitally in order to be a digital registration. If one or both parties reports paper, both parties must proceed in the “old fashion way”.

Notifying the other party about changes

If the bank or the broker changes their intentions, either from digital to paper or paper to digital, this can change the business flow on both sides and must be communicated to the other party. Both parties must check for changes regularly and act correspondingly. When a broker changes it’s intention, EPS will generate an event (INTENTION_CHANGED) for the bank. The bank must take appropriate actions when receiving this event.

About references

Sending an intention to the broker

Sending an intention to the broker is done using EPS' bankintentions endpoint.

POST /eps/v1/bankintentions

The basic information you need is:

  • Contact information in the bank

  • One or more buyers

  • The property

  • The broker’s organization number

For a detailed description of required and optional fields in the input and response bodies, see the technical information at https://beta-api.ambita.com/eps/#tag/BankIntention/operation/createBankIntention.

Response

The http status code of the response will determine the flow:

  • 201 : The intention data matches a settlement in Ambita and the response is ready

  • 202 : The intention is sent to the (non-Ambita) broker and an event (INTENTION_RESPONSE_RECEIVED) will be generated when the response is ready.

  • 400 : Bad request. Either the data in the request is invalid or the intention data didn’t match any settlements. Se below for error description.

Both 201 and 202 status codes will have a payload containing a settlementUniqueIdentifier. This is the unique identifier of a settlement that you must keep for later retrieval of data. Also all events will reference a settlement (NOTE: if requesting a purchase contract, some new events will not have this settlement identifier).

Handling 201 status code

A status code of 201 is return when the intention data matches a settlement for an Ambita broker. Since we already have the settlement data, a synchronous response is given. The broker’s intended registration method can be found in the response body in the field flowCapability and the possible values are "PAPER" or "DIGITAL". In the future a third value for Not determined yet can be added.

Now the broker knows the bank’s intention and the bank knows the broker’s intention. Again. both parties must agree on DIGITAL for it to be a digital process.

Also keep in mind that the intention can be changed later on in the process. The bank does this by again sending a bankintention but with the new flowCapability. The bank is notified by reading events and receiving an INTENTION_CHANGED event referencing the settlement unique identifier.

Handling 202 status code

Receiving a 202 means that EPS has sent the intention asynchronously to the broker. The bank receives an immediately response containing the settlement unique identifier for later reference and data retrieval. Nothing is known about the broker’s intention before a response is received later on and an event (INTENTION_RESPONSE_RECEIVED) is generated referencing this settlement. The data returned in the immediate response is the bank’s data from the intention until a successful match is done and the settlement is updated with some more data from the broker.

Handling 400 status code (bad request)

A bad request signals a failed validation of the input data or, in case of an Ambita broker, the intention didn’t match any settlements. The error object returned in EPS all contains a field message that we work hard on being human understandable. In case of a bad request, this message should be presented to the person in the bank handling the case as either the input must be changed or the broker must be contacted to find out what went wrong.

States and codes

<todo>

Listening for events

It is essential that the bank has a kind of scheduled batch job that fetches the latest list of events, processes them and takes action on relevant events like INTENTION_RESPONSE_RECEIVED and INTENTION_CHANGED. Unknown or uninteresting events can be ignored.

Relevant event types are described here: Events for banks.

More information about how to listen to events can be found here: Monitoring settlements

Generating pantedokument (digital registration process)

Generating a pantedokument to a broker is pretty similar to generating one that should be sent straight to the Registration authority (Statens kartverk) for registration (tinglysing). The most important difference is that the element <dokumentflyt> should be changed to <dokumentflyt>DOKUMENT_TIL_OPPGJOER</dokumentflyt>. Se more details at: https://ambita.atlassian.net/wiki/spaces/DOC/pages/1202192544/Generate+pantedokument#How-to-set-document-flow

Generating a forutsetningsbrev

If the bank would generate a forutsetningsbrev outlining the requirements to the broker, the new webservice generateForutsetningsbrev must be used as the old one generatePrerequisite is deprecated. Se more: Generate forutsetningsbrev

  • No labels