MeR TPP sustav digitalnog bankarstva

v1/getTransactions - POST

Opis: Iniciranje dohvata informacija o prometu po računima

URL (test): https://testapi.e-plati.hr/api/v1/getTransactions

URL (produkcija): ../v1/getTransactions

Specifikacija requesta - JSON:

Parametri: NEMA

	Opis	Tip podatka	Uvjet	Obavezno
.
header				DA
Content-Type	application/json	string		DA
X-Request-ID	Jedinstveni identifikator REST zahtjeva (requesta), jedinstven za svaki REST poziv.	UUID		DA
body				DA
username	Jedinstveni identifikator korisnika	string		DA
password	Password	string		DA
companyId	OIB pravne osobe	string		DA
companyBu	Oznaka podružnice ili druge izdvojene poslovne jedinice.	string		NE
softwareId	Jedinstvena oznaka poslovnog sustava (ERP)	string		DA
bookingStatus	Status transakcija: booked Ovaj status podržavaju sve banke. Odnosi se na transakcije i promet po računu koji je proknjižen u knjizi od banke. pending Ovaj status ne podržavaju sve banke. Odnosi se na transakcije koje su u tijeku, tj. još nisu proknjižene u knjizi banke. both Ovaj status se odnosi na booked i pending transakcije. Ukoliko je parametar both, sustav će vratiti izvještaj u JSON formatu koji će sadržavati knjižene transakcije i transakcije u tijeku. Naravno, dostupnost informacija ovisi i o PSD2 API kanalu pojedine banke. information Ovisno o implementaciji banke, ovdje je moguće dobiti jedino informacije o trajnim nalozima. Sustav će vratiti podatke ukoliko su dostupni na PSD2 kanalu od banke, i ukoliko se parametar eksplicitno postavi na information ili all. all Vraća sve dostupne podatke.	string		DA
merDateFrom	Datum od u ISO formatu YYYY-MM-DD. Dohvat prometa prema datumu knjiženja ako su transakcije proknjižene, tj. u statusu booked. Dohvat prometa prema datumu kreiranja za transakcije koje su u tijeku, tj. u statusu pending. Datum od će se ignorirati ako se radi o transakcijama koje su u statusu information. Datum od će se ignorirati ako postoji valjani parametar entryReferenceFrom. Opcionalnost ovog parametra je Conditional iz razloga što parametar mora biti dostavljen, ako nije dostavljen parametar entryReferenceFrom. Paramater merDateFrom mora biti dostavljen ukoliko je dostavljen parametar merDateTo.	ISODate	DA	NE
merDateTo	Datum do u ISO formatu YYYY-MM-DD. Dohvat prometa prema datumu knjiženja ako su transakcije proknjižene, tj. u statusu booked. Dohvat prometa prema datumu kreiranja za transakcije koje su u tijeku, tj. u statusu pending. Datum do će se ignorirati ako se radi o transakcijama koje su u statusu information. Datum do će se ignorirati ako postoji valjani parametar entryReferenceFrom. Opcionalnost ovog parametra je Conditional iz razloga što parametar mora biti dostavljen, ako nije dostavljen parametar entryReferenceFrom. Paramater merDateTo mora biti dostavljen ukoliko je dostavljen parametar merDateFrom.	ISODate	DA	NE
merDebCre	Vrsta prometa. Priljev, Odljev ili Priljev i Odljev Odljev (Isplata/Debited transaction) = -1; Priljev (Uplata/Credited transaction ) = 1 ; Priljev i Odljev = 0 (Default) Ukoliko se ne pošalje ovaj parametar, sustav ga automatski postavlja na merDebCre = 0, tj. uvijek vraća i priljev i odljev. Parametar mora biti dostavljen, ukoliko je dosavljen parametar counterAccount.	integer	DA	NE
consentStatus	Ima li račun aktivnu privolu. 1 – Filtrira samo transakcije za račune koji imaju aktivnu privolu (defaultno ponašanje) 0 – Filtrira samo transakcije za račune koji nemaju aktivnu privolu 2 – Filtrira sve transakcije Parametar je opcionalan, a ukoliko se parametar ne dostavi, sustav defaultno filtrira samo transakcije za račune koji imaju aktivnu privolu. Ovo ima za posljedicu da sustav neće po defaultu vraćati podatke o računima, u ovom slučaju podatke o transakcijama, za koje nema aktivnu privolu.	integer		NE
ownerAccount:	Pretraživanje po računu vlasnika, tj. dohvat prometa po točno zadanom računu (IBAN + valuta ili samo IBAN). Ukoliko se želi pregled prometa po određenom računu onda se specificira IBAN u ownerAccount parametru. Ukoliko se ne pošalje ovaj parametar, servis vraća sve promet po svim dostupnim računima, sukladno ostalim parametrima u requestu. Ovaj parametar mora biti dostavljen ukoliko je dostavljen parametar entryReferenceFrom.	Account Reference	DA	NE
{ iban	IBAN računa vlasnika	string	DA	NE
currency }	Valuta IBAN-a računa vlasnika	string	DA	NE
counterAccount:	Pretraživanje po elementima debtorAccount ili creditorAccount iz transactionDetails JSON strukture. Ukoliko se dostavi ovaj parametar, potrebno je obavezno dostaviti i merDebCre sa vrijednostima 1 ili -1. Ukoliko se dostavi merDebcre = 1, filtrirat će se po debtorAccount. Drugim riječima, filtriraju se priljevi sredstava na račun od platitelja s IBAN-om dostavljenim u counterAccount. Uvjet counterAccount = debtorAccount. Ukoliko se dostavi merDebCre = -1, filtrirat će se po creditorAccount. Drugim riječima, filtriraju se odljevi sredstava na račun primatelja s IBAN-om dostavljenim u counterAccount. Uvjet counterAccount = creditorAccount. Ukoliko se uz counterAccount dostavi i valuta, onda će se dodatno filtrirati po valuti transakcije.	Account Reference		NE
{ iban	IBAN računa	string		NE
currency }	Valuta IBAN-a računa	string		NE
entryReferenceFrom	Ovaj parametar je za implementaciju delta pristupa. Traže se sve transakcije nakon transakcije koja ima entryReference = entryReferenceFrom. Drugim riječima, dohvat transakcija kojima je entryReference strogo veći od entryReferenceFrom. Ukoliko se ne navede ovaj parametar, onda je potrebno navesti merDateFrom i merDateTo. Ukoliko se navede i entryReferenceFrom, i datumi: merDateFrom i merDateTo, dohvat transakcija će se raditi prema entryReferenceFrom parametru, a ignorirat će se dostavljeni datumi. Dohvat transakcija putem delta pristupa, tj. koristeći parametre entryReferenceFrom i entryReferenceTo, može funkcionirati samo ukoliko banka kreira entryReference podatak u izvodu na slijedan način, tj. tako da je ovaj podatak numeričkog tipa i da se inkrementalno povećava, na način da nove transakcije imaju veći entryReference broj. Primjerice, ukoliko banka generira entryReference sa nekom random funkcijom, onda to može onemogućiti ispravan način rada delta pristupa. Ukoliko ovaj pristup nije podržan na sučelju od neke banke, onda će sustav vratiti HTTP 400 – Bad request. U tom slučaju je potrebno pristupiti podacima putem zadavanja parametara merDateFrom i merDateTo.	integer	DA	NE
entryReferenceTo	Ovaj parametar je za implementaciju delta pristupa. Traže se sve transakcije prije transakcije koja ima entryReference = entryReferenceTo. Drugim riječima, dohvat transakcija kojima je entryReference strogo manji od entryReferenceTo. Ukoliko je dostavljen ovaj parametar onda obavezno mora biti dostavljen i parametar entryReferenceFrom, jer zbog, potencijalno velike količine transakcija, mora biti dostavljena i donja granica uvjeta za dohvat transakcija prema entryReference elementu. Ukoliko se dostavi samo entryReferenceFrom, a izostavi entryReferenceTo, sustav će vratiti sve transakcije kojima je entryReference veći od entryReferenceFrom.	integer		NE

Specifikacija response - JSON:

	Opis	Tip podatka	Uvjet	Obavezno
.
header				DA
Content-Type	application/json	string		DA
X-Request-ID	Jedinstveni identifikator requesta, jedinstven za svaki REST poziv. Ovo je identifikator koji je MeR TPP zaprimio od ERP sustava. Dostavlja se u neizmijenjenom obliku u odgovoru na zahtjev kod svih važnijih transakcija. Npr. iniciranje plaćanja i sl.	UUID		DA
body				DA
accountReport	Lista tipa accountTransactionReport Primjer: [{accountTransactionReport1},{accountTransactionReport2},..]	Array of accountTransactionReport		DA
accountTransactionReport				DA
account:	Identfikator računa. Svi transakcijski računi u HR bankama imaju IBAN, a to je ujedno i najčešći identifikator. U odgovoru je moguće dobiti više identifikatora poput bban, pan, maskedPan, msisdn, cashAccountType, ispod su navedeni najčešći i oni koje ćemo koristiti iban i currency.	Account Reference		DA
{ iban	IBAN računa	string		DA
currency }	Valuta IBAN-a računa	string		DA
balances:	Lista stanja po računu tipa balance. Stanje po računu se dostavlja ukoliko privola ima uključenu opciju koja dozvoljava dohvat stanja po računu. Primjer: [{balance1},{balance2}]	Array of Balance		NE
[ balanceAmount:	Stanje po računu tipa balance.	Array of balanceAmount		NE
{ currency	Valuta	string		NE
amount }]	Iznos	string		NE
transactions	Izvještaj o prometu po računu u JSON formatu. Ovaj izvještaj sadrži listu transakcija tipa transactionDetails. Ovisno o parametru bookingStatus, report može sadržavati transakcije koje su: booked Ovdje je promet po računu koji je proknjižen u knjigama od banke. pending Ovdje je promet po računu i plaćanja koja još nisu proknjižena u knjigama banke. Podrška za ove transakcije ovisi o PSD2 API kanalu banke. Ako je bookingStatus parametar “booked” ili “both” onda ove transakcije neće biti uvrštene u report. information Ovo transakcije će biti uvrštene u odgovor samo ako je bookingStatus parametar “information”. Ovu vrstu transakcija ne podržavaju sve banke. Trenutno bi prema dostupnim opisajama na PSD2 kanalima banaka ovdje bilo moguće dobiti informacije o trajnim nalozima (standing orders transakcije) Primjer: "transactions": { "booked": [ {transactionDetail1}, {transactionDetail2}, ... {transactionDetail20} ], "pending": [ {transactionDetail21}, {transactionDetail21}, ... ] }	Account Report		NE
transactionDetails				NE
transactionId	Can be used as access-ID in the API, where more details on a transaction is offered. If this data attribute is provided this shows that the AIS can get access on more details about this transaction using the GET Transaction.	string		NE
entryReference	Is the identification of the transaction as used e.g. for reference for delta function on application level? The same identification as for example used within camt.05x messages.	string		NE
endToEndId	Unique end to end identity.	string		NE
batchIndicator	If this indicator equals true, then the related entry is a batch entry.	boolean		NE
batchNumberOfTransactions	Shall be used if and only if the batch Indicator is contained and equals true.	integer		NE
mandateId	Identification of Mandates, e.g. a SEPA Mandate ID	string		NE
checkId	Identification of a Cheque.	string		NE
creditorId	Identification of Creditors, e.g. a SEPA Creditor ID.	string		NE
bookingDate	The Date when an entry is posted to an account on the ASPSPs books.	ISODate		NE
valueDate	The Date at which assets become available to the account owner in case of a credit.	ISODate		NE
transactionAmount:	Transaction amount.	Amount		DA
{ currency	Currency	string		DA
amount }	Amount	string		DA
currencyExchange:	Exchange rate	Array of Report Exchange Rate		NE
{ sourceCurrency	Source currency	string		NE
exchangeRate	Exchange rate	string		NE
unitCurrency	Unit currency	string		NE
targetCurrency	Target currency	string		NE
quotationDate }	Quotation date	ISODateTime		NE
creditorName	Name of the creditor if a "Debited" transaction.	string		NE
creditorAccount:	Creditor Account Reference	Account Reference	DA	NE
{ iban	Creditor IBAN	string	DA	NE
currency }	Creditor IBAN currency	string	DA	NE
creditorAgent	BICFI	stirng		NE
ultimateCreditor	Ultimate creditor	stirng		NE
debtorName	Name of the debtor if a "Credited" transaction	stirng		NE
debtorAccount:	Debtor Account Reference	Account Reference	DA	NE
{ iban	Debtor IBAN	string	DA	NE
currency }	Debtor IBAN Currency	string	DA	NE
debtorAgent	BICFI	stirng		NE
ultimateDebtor	Ultimate Debtor	stirng		NE
remittanceInformationUnstructured	Remittance Information Unstructured	stirng		NE
remittanceInformationUnstructuredArray	example: List [ "Ref Number Merchant", "Some Other Text" ]	stirng		NE
remittanceInformationStructured	Reference to be transported in the field.	stirng		NE
remittanceInformationStructuredArray	Array of structured remittance information. remittanceInformationStructured { reference* string -maxLength: 35 referenceType string -maxLength: 35 referenceIssuer string -maxLength: 35 }	Array of Remittance		NE
entryDetails	Array of EntryDetailsElement	EntryDetailsElement		NE
additionalInformation	Might be used by the ASPSP to transport additional transaction related information to the PSU.	string		NE
additionalInformationStructured	Is used if and only if the bookingStatus entry equals "information". Every active standing order related to the dedicated payment account result into one entry.	StructuredAdditionalInformation		NE
purposeCode	Purpose Code	string		NE
bankTransactionCode	Bank transaction code as used by the ASPSP and using the sub elements of this structured code defined by ISO20022. For standing order reports the following codes are applicable: "PMNT-ICDT-STDO" for credit transfers, "PMNT-IRCT-STDO" for instant credit transfers "PMNT-ICDT-XBST" for cross-border credit transfers "PMNT-IRCT-XBST" for cross-border real time credit transfers and "PMNT-MCOP-OTHR" for specific standing orders which have a dynamical amount to move left funds e.g. on month end to a saving account.	string		NE
proprietaryBankTransactionCode	Proprietary bank transaction code as used within a community or within an ASPSP e.g. for MT94x based transaction reports.	string		NE
balanceAfterTransaction:	This is the balance after this transaction. Recommended balance type is interimBooked.	Balance		NE
{ currency	Currency	string		NE
amount }	Amount	string		NE
merChangeTime	Datum i vrijeme kada je transakcija zadnji put ažurirana putem komunikacije sa PSD2 API kanalom od banke.	ISODateTime		DA

Primjer 1 JSON - POST request:

	
	POST /api/v1/getTransactions HTTP/1.1
	Host: irpsd2.dynu.net:8040
	X-Request-ID: 2852900f-55ce-497b-b8cb-5bbf485a10a2
	Content-Type: application/json
	Content-Length: 371
	{
		"username": "clUser",
		"password": "clUser123%",
		"companyId": "99999999927",
		"companyBu": "",
		"softwareId": "Test-001",
		"merDateFrom": "2021-06-20",
		"merDateTo": "2021-08-31",
		"bookingStatus": "all",
		"merDebCre": 0,
		"consentStatus": 2,
		"debtorAccount": {
			"iban": "HR5023400093000000003"
		}
	}

Primjer 1 JSON - response:

	

	HTTP/1.x 200 OK
	X-Request-ID: 2852900f-55ce-497b-b8cb-5bbf485a10a2
	Content-Type: application/json
	{
 		"accountReport": {
 			"account": {
 				"iban": "HR9323400093000000005"
 			},
 			"transactions": {
 				"booked": [
 					{
						"transactionId": "BT2072514295",
						"entryReference": "10469142704756",
						"endToEndId": "HR99",
						"bookingDate": "2021-05-21",
						"valueDate": "2021-05-21",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -1109.04
						},
						"creditorName": "PRIVREDNA BANKA ZAGREB D.D.",
						"creditorAccount": {
							"iban": "HR6423400091000000013",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "Naplata kredita ",
						"remittanceInformationStructured": "HR1038130-1497979",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2069624958",
						"entryReference": "16137407219006",
						"endToEndId": "-",
						"bookingDate": "2021-05-21",
						"valueDate": "2021-05-21",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -7
						},
						"creditorName": "-",
						"creditorAccount": {
							"iban": "-",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "NAKNADA ZA VOĐENJE TEKUĆEG RAČUNA",
						"remittanceInformationStructured": "-",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2069624948",
						"entryReference": "69378309729359",
						"endToEndId": "-",
						"bookingDate": "2021-05-21",
						"valueDate": "2021-05-21",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -78.19
						},
						"creditorName": "-",
						"creditorAccount": {
							"iban": "-",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "KAMATA PO PREKORAČENJU",
						"remittanceInformationStructured": "-",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2062589604",
						"entryReference": "439470978156",
						"endToEndId": "HR00457418-0000002003",
						"bookingDate": "2021-05-12",
						"valueDate": "2021-05-12",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -1000
						},
						"creditorName": "IME885190 PREZIME835687",
						"creditorAccount": {
							"iban": "1000000013",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "PBZ ATM PBZ POSLOVNICA 480 PAKRAC PAKRAC",
						"remittanceInformationStructured": "HR3914519-4100346007-8642",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2062589590",
						"entryReference": "290374581217",
						"endToEndId": "HR00457418-0000002003",
						"bookingDate": "2021-05-12",
						"valueDate": "2021-05-12",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -88.88
						},
						"creditorName": "IME101600 PREZIME510603",
						"creditorAccount": {
							"iban": "1000000013",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "PBZ POS PBZTKTC PAKRAC",
						"remittanceInformationStructured": "HR4754607-6530380856-7114",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2053312934",
						"entryReference": "25048088124435-396352-215057",
						"endToEndId": "HR7818946217048-87490-6",
						"bookingDate": "2021-04-29",
						"valueDate": "2021-04-29",
						"transactionAmount": {
							"currency": "HRK",
							"amount": 4000
						},
						"ultimateCreditor": "-",
						"debtorName": "PODUZEĆE477252",
						"debtorAccount": {
							"iban": "HR6623400091161331010",
							"currency": "HRK"
						},
						"ultimateDebtor": "-",
						"purposeCode": "SALA",
						"remittanceInformationUnstructured": "PLAĆANJE PO RAČUNU BR. 7828164599751782",
						"remittanceInformationStructured": "HR2665780-55911511143-715",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2052201681",
						"entryReference": "35746181315103-466699-436062",
						"endToEndId": "HR00200-190107-00050014029",
						"mandateId": "64-29/1039574-02031",
						"bookingDate": "2021-04-27",
						"valueDate": "2021-04-27",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -222.53
						},
						"creditorName": "PODUZEĆE294591",
						"creditorAccount": {
							"iban": "HR7923400091161567700",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "PLAĆANJE PO RAČUNU BR. 5301775351082843",
						"remittanceInformationStructured": "HR0011190089879",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2052201669",
						"entryReference": "1042923468596-24924186",
						"endToEndId": "HR99",
						"bookingDate": "2021-04-27",
						"valueDate": "2021-04-27",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -2.23
						},
						"creditorName": "PRIVREDNA BANKA ZAGREB D.D.",
						"creditorAccount": {
							"iban": "HR6423400091000000013",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "Naknada za plaćanje izravnim terećenjem; Suglasnost broj ",
						"remittanceInformationStructured": "HR4733980-7758-1857170",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2028669724",
						"entryReference": "26352828415314",
						"endToEndId": "HR99",
						"bookingDate": "2021-04-20",
						"valueDate": "2021-04-20",
						"transactionAmount": {
							"currency": "HRK",
							"amount": -1109.04
						},
						"creditorName": "PRIVREDNA BANKA ZAGREB D.D.",
						"creditorAccount": {
							"iban": "HR6423400091000000013",
							"currency": "HRK"
						},
						"ultimateCreditor": "-",
						"ultimateDebtor": "-",
						"remittanceInformationUnstructured": "Naplata kredita ",
						"remittanceInformationStructured": "HR7028441-1423216",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					},
					{
						"transactionId": "BT2005834462",
						"entryReference": "29757833015933-777409-133584",
						"endToEndId": "HR3268767618661-79263-3",
						"bookingDate": "2021-03-26",
						"valueDate": "2021-03-26",
						"transactionAmount": {
							"currency": "HRK",
							"amount": 4000
						},
						"ultimateCreditor": "-",
						"debtorName": "PODUZEĆE574247",
						"debtorAccount": {
							"iban": "HR6623400091146694988",
							"currency": "HRK"
						},
						"ultimateDebtor": "-",
						"purposeCode": "SALA",
						"remittanceInformationUnstructured": "PLAĆANJE PO RAČUNU BR. 8455132830513346",
						"remittanceInformationStructured": "HR1817026-45848122575-771",
						"merChangeTime": "2021-04-21T12:20:45.046Z"
					}
				]
			}
		}
	}