Bank intentions
- Bjørn Hamre
Then /eps/v1/bankintentions endpoint is for communicating the bank’s intended registration method (paper or digital) to the broker and also get the same intent from the broker. In addition, this endpoint will also be used to to update the registration method if circumstances change on the bank’s side.
The broker can also change their intent, and any changes from the broker will be made available to the bank by the event INTENTION_CHANGED.
Intention vs. Intention changed
The bank will send an intention message to the broker. The response can be accepted by the broker (it matches one settlement) or rejected. From the moment an intention is accepted by the broker, the broker expects an intention changed message from the bank if the bank has to change it’s registration method from PAPER to DIGITAL or vice versa. If the bank posts another bank intention with the same flow/registration method as the previous accepted intention, a response with 400 Bad request will be returned with an error message like “Invalid input: Intention with flow capability ELEKTRONISK_TINGLYSING is already sent. New intention must contain flow capability PAPIRTINGLYSING”. Note that currently the flow capabilities in the error message are ELEKTRONISK_TINGLYSING and PAPIRTINGLYSING, this will change to DIGITAL and PAPER in a future release.
Until a bank intentions is accepted/matched by a broker, another intention with the same flow/registration method can be sent multiple times.
Communicating with an Ambita broker
When posting a Bankintention (/v1/bankintentions/) is sent to an Ambita broker,
the response status code will be 201 (created). The response data will contain
a property called settlementUniqueIdentifier which can be used to fetch
the settlement data and check the broker's intention (flow).
If sending the bankintention to an Ambita broker and there is no match with a
settlement, the response code will be 400 (bad request). The response object has
a property named message that is a user friendly explanation of what went wrong.
Example response:
{
"timestamp" : "2022-02-17T11:28:59.438424000",
"status" : 400,
"error" : "Bad Request",
"exception" : "com.ambita.eps.service.exception.NotFoundSettlementForRealestate",
"message" : "Fant ikke noe oppgjør for eiendomsnøkkel",
"path" : "/eps/v1/bankintentions"
}Example of messages are:
"Fant ikke noe oppgjør for eiendomsnøkkel", no settlement found for the given property key and broker organization number.
"Det finnes ingen eiendomsoppgjør på denne kjøperen(e). Ta kontakt med megler for å avklare hva som skal gjøres.", found a settlement but the given buyer didn’t match the actual buyer.
"For mange oppgjør funnet hos ${organizationNumber}.", if more than one matching settlement was found for the given broker’s organization number.
Communicating wit a Non-Ambita broker
When a bank intention should be sent to a non-Ambita broker, additional validation of the input data will be performed. If any errors are found, a response of 400 Bad request will be returned with a message describing the error.
If no errors are found in the input, the intentions will be sent to the broker via Altinn (the AfPant channel) and the response status code will be 202 Accepted. The response data will contain a settlementUniqueIdentifier
that later can be used to fetch the settlement data and check the broker's intention.
When a response from the broker is received from Altinn (later), an event of typeINTENTION_RESPONSE_RECEIVED is created. In the event data you can use the property eventCode. An event code of EPS_EV0001 means the intention was successfully accepted by the broker. The broker's intentions can now be found by fetching the settlement data using the previous mentioned settlement uid or using the link in the event data named "settlement".
An event code of EPS_EV0002 means the intention was rejected by the broker. A human friendly description of why this is can be found in the events description property. Ambita forwards this description to the bank as it’s given by the remote broker’s system. An example:
"description: "Intensjon feilet. Melding fra megler: Registerenhet treff, men ikke treff på kjøper: fant ingen oppdrag i meglersystemet der minst 1 kjøper fra oversendt intensjonsforespørsel stemmer med kjøper(e) i megleroppdrag (fikk følgende registerenhet treff: 316/31-21-0350). Vennligst påse at riktig(e) kjøper(e) er registrert i intensjonsmeldingen.."
Example of INTENTION_RESPONSE_RECEIVED event that was accepted by the broker (slightly anonymized):
{
"eventId": 1348417,
"type": "INTENTION_RESPONSE_RECEIVED",
"text": "Intention response from broker received",
"description": "Intensjonsvar fra 'XXXXXXXXXX AS' (xxxxxxxxx) til 'YYYYYYYYY AS' (yyyyyyyyy). Flyten er 'DIGITAL'.",
"created": "2023-01-17T13:02:40.788244",
"settlementUid": "SET-cf05876a-1234-47aa-9438-0b78316f0ab1",
"externalReference": "195/34-22-1421 Buen 34",
"resources": [],
"eventCode": {
"code": "EPS_EV0001",
"templateNo": "Intensjonsvar fra 'XXXXXXXXXX AS' (xxxxxxxxx) til 'YYYYYYYYY AS' (yyyyyyyyy). Flyten er 'DIGITAL'.",
"templateValues": {
"flyt": "DIGITAL",
"meglernavn": "XXXXXXXXXX AS",
"megler_organisasjonsnr": "xxxxxxxxx",
"bank_organisasjonsnr": "yyyyyyyyy",
"banknavn": "YYYYYYYYY AS"
}
},
"links": [
{
"rel": "self",
"href": "http://api.ambita.com/eps/v1/events/1348417"
},
{
"rel": "settlement",
"href": "http://api.ambita.com/eps/v1/settlements/SET-cf05876a-1234-47aa-9438-0b78316f0ab1"
}
]
}
Example of INTENTION_RESPONSE_RECEIVED event that didn’t match a unique settlement or was rejected by the broker:
General error messages
Response code 400 (Bad request) is returned for cases where there is a problem with the input data (broker’s organization number, buyer’s personal number (or organization number), or the property key.