Transactions for a specified account and period. Data providers should return an empty list if there are no hits. Must support pagination on large result sets (min 1000).
The principles are defined in Principles for delivery of information via DSOP Control information common standard.
Input parameters
Values set by data consumer.
It is the data providers responsibility to validate all requests from the data consumers and to make sure that all requests are validated well enough. See some recommendations regarding validation of requests in Control API.
| Parameter | Description | Comment |
|---|---|---|
| accountReference (M) | A unique reference to the account, but should not be the account number and not simply decoded to an account number. | - |
| AccountInfoRequestID (M) | Consumers case reference id/number | Link to Overall description of the DSOP Control API |
| CorrelationID (M) | Unique identifier for the technical request | Link to Overall description of the DSOP Control API |
| Legal-Mandate* (M) | Legal basis the data providers should validate. Formatted encoded text. | See the specific DSOP Service documentation for the valid legal mandates |
| AdditionalReferenceID* (O) | Reference ID when Legal-Mandate is not adequate alone, or to identify requester at data consumer. Should be validated according to the Legal-Mandate. Formatted encoded text. | Required for some DSOP Services. More information in More information in Overall description of the DSOP Control API |
| AdditionalReferenceIDType* (O) | What type of reference to expect in AdditionalReferenceID | Required for some DSOP Services. More information in More information in Overall description of the DSOP Control API |
| RequesterID (O) | RequesterID identifies the user who makes the request at the public agency. The public agencies are free to pseudonymise RequesterID so that the financial institutions cannot link this ID to the agency’s user or natural person. In turn, the public agency must be able to link RequesterID to a user in the public agency. It is important that RequesterID remains constant per user and is not reused for new users. | Even though this parameter is technically optional, it could become logically mandatory for a given DSOP service. |
| fromDate (M) | Date (included) from which the time period for the data delivery starts. | - |
| toDate (M) | Date (included) from which the time period for the data delivery ends. | - |
*It is recommended to validate AdditionalReferenceID and AdditionalReferenceIDType according to the legal-mandate. Legal-mandate should always be logged with belonging AdditionalReferenceID.
Responses
Values in response from the data providers.
All fields are to be provided as long as the data provider holds the data, regardless of whether the fields are marked as mandatory or not. This is according to the legal basis.
Description of all response elements in the API
responseDetails
Deliver
Status that informs the data consumer of the degree of completeness of the response from the data provider.
responseDetails.status
Deliver
Indicates whether the data delivery this is a complete answer, or whether there is data offline the data provider is aware of that cannot be retrieved through the API.
- partial: If there is any data the data provider is aware of that can be retrieved manually and is not part of the API response, or if the provider wishes to be contacted via another channel by the consumer.
- complete: If there is no more available data the data provider is aware of that can be retrieved manually. All known data has been returned in the response.
responseDetails.status is not to be used as an indicator for paginating.
| [partial, complete] |
responseDetails.message
Deliver
In case of responseDetails.status = partial, responseDetails.message must be used and will indicate the reason why not all data has been delivered through the API in order to inform the data consumers about the situation, and enable them to decide if it is necessary to send a digital letter to the Data provider or not. A description of the different messages to return is available in the document DSOP Control - Functional specification - Messages in relation with partial.pdf.
transactions
Deliver
Overview of all transactions on to the account/agreement related to the control object.
transactions.transactionidentifier
Mandatory conditional
A unique identifier for each transaction within each financial institution, following the data providers own standard. This value is what the data consumer will use as a reference when contacting the financial institution via alternate channels to request more information about a transaction, if necessary.
transactions.references
Deliver
A set of references associated with a transaction at the reporting bank.
transactions.references.value
Mandatory conditional
Reference number associated with type.
transactions.references.type
Mandatory conditional
Type of reference value. For KID number, the value “messageIdentification” must be used.
Use otherReference if no other value can apply.
| [accountServicerReference, archiveReference, chequeNumber, endToEndIdentification, instructionIdentification, invoiceNumber, mandateIdentification, messageIdentification, otherReference, paymentInformationIdentification, remittanceReference] |
transactions.creditDebitIndicator
Mandatory conditional
Indicates whether the transaction added funds to the account (credit) or removed funds from the account (debit).
| [credit, debit] |
transactions.reversalIndicator
Deliver
Indicates whether the transaction is a correction of a previous transaction.
transactions.status
Mandatory conditional
Status of the transaction. Shows whether the transaction is booked or pending. All other transactions’ statuses can be mapped to info.
| [booked, pending, info] |
transactions.transactionCode
Mandatory conditional
Structure where the transaction type is to be returned.
transactions.transactionCode.domain
Deliver
Business area: High level definition of the business activity. See document “BANK TRANSACTION CODE COMBINATIONS AND DESCRIPTION” in ISO20022 standard.
| [accountManagement, cashManagement, foreignExchange, payments, securities, tradeServices, extended] |
transactions.transactionCode.family
Deliver
Product family definition. See document “BANK TRANSACTION CODE COMBINATIONS AND DESCRIPTION” in ISO20022 standard.
| [additionalMiscellaneousCreditOperations, additionalMiscellaneousDebitOperations, miscellaneousCreditOperations, miscellaneousDebitOperations, openingAndClosing, accountBalancing, cashPooling, notAvailable, customerCardTransactions, counterTransactions, drafts, issuedCashConcentrationTransactions, issuedCreditTransfers, issuedCheques, issuedDirectDebits, lockboxTransactions, merchantCardTransactions, other, receivedCashConcentrationTransactions, receivedCreditTransfers, receivedCheques, receivedDirectDebits, corporateAction, documentaryCollection, standByLetterOfCredit] |
transactions.transactionCode.subFamily
Deliver
Detailed product specification See document “BANK TRANSACTION CODE COMBINATIONS AND DESCRIPTION” in ISO20022 standard.
| [valueDate, chargesGeneric, commissions, interestsGeneric, other, accountClosing, notAvailable, sweeping, topping, zeroBalancing, cashWithdrawal, debitCardPayment, crossBorderCashWithdrawal, cashDeposit, debitAdjustmentGeneric, travellersChequesDeposit, settlementAtMaturity, intraCompanyTransfer, corporateOwnAccountTransfer, crossBorderIntraCompanyTransfer, achDebit, achReturn, achTransactionAtxn, automaticTransfer, bankCheque, booked, domesticCreditTransfer, dividend, sepaCreditTransfer, financialInstitutionCreditTransfer, principalPayment, priorityCreditTransfer, reversalDueToPaymentReturn, achTransactionSala, sameDayValueCreditTransfer, standingOrder, taxes, creditTransferWithAgreedCommercialInformation, crossBorderCreditTransfer, cashLetter, cheques, chequesReversal, openCheque, unpaidCheque, crossBorderCheque, sepaCoreDirectDebit, directDebitPayment, reversalDueToPayment, reversalDueToPaymentCancellationRequest, reversalDueToReturnUnpaidDirectDebit, debit, deposit, adjustments, fees, creditCardPayment, pointOfSalePosPayment, creditAdjustment, settlementAfterCollection] |
transactions.transactionCode.freeText
Deliver
If it is not possible to map the transaction using ISO transactionCode domain and family, freetext can be used. Freetext must be a standard code set used by the bank to categorize the transaction. Code set must be shared with consumers.
Examples: Payment types (codes) like; Nettgiro, Varekjøp, Visa Varekjøp, Avtalegiro, Straksutbetaling, Kontoregulering etc.
transactions.bookingDate
Mandatory conditional
Date for when a transaction was booked ISO Date (yyyy-mm-ddThh:mm:ss).
transactions.valueDate
Mandatory conditional
Date for when the booked transaction is interest-bearing ISO Date (yyyy-mm-ddThh:mm:ss).
transactions.counterParties
Deliver
Counterparty related to the transaction and from which payment is made or from which payment is received.
transactions.counterParties.accountIdentifier
Deliver
Counterparty’s account number.
transactions.counterParties.identifier
Deliver
transactions.counterParties.identifier.countryOfResidence
Deliver
CountryCode. The country the counterparty belongs to. In ISO 3166-1/Alpha-2 code format.
transactions.counterParties.identifier.value
Mandatory conditional
Personal identification number, D-number or organization number of the counterparty.
transactions.counterParties.identifier.type
Mandatory conditional
- countryIdentificationCode: The national registration code for businesses, enterprises, organizations and companies that is retrieved from the National register for organizations. In Norway this would be from BRREG.
- nationalIdentityNumber: Used for persons. The national identity code for persons. In Norway this would be P or D numbers from FREG.
| [countryIdentificationCode, nationalIdentityNumber] |
transactions.counterParties.name
Deliver
Counterparty’s name.
transactions.counterParties.type
Mandatory conditional
Counterparty’s role in the transaction.
Debtor: The party that is responsible for making the payment to the creditor.
Creditor: The party that is entitled to receive the payment from the debtor.
UltimateDebtor: The final party that truly owes the money to the ultimate creditor. This is different from the immediate debtor when someone makes a payment on behalf of another party.
UltimateCreditor: The final party that is ultimately entitled to receive the money. This is different from the immediate creditor when someone receives payment on behalf of another party.
| [ debtor, creditor, ultimateDebtor, ultimateCreditor ] |
transactions.counterParties.postalAddress
Deliver
Counterparty’s address.
transactions.counterParties.postalAddress.postCode
Deliver
Registered postal code for the Counterparty’s address.
transactions.counterParties.postalAddress.type
Mandatory conditional
Type of registered address for the Counterparty.
| [residential, business, mailTo, deliveryTo] |
transactions.counterParties.postalAddress.streetName
Deliver
Street address registered on the Counterparty.
transactions.counterParties.postalAddress.buildingNumber
Deliver
Building number for the street address registered on the Counterparty.
transactions.counterParties.postalAddress.townName
Deliver
Postal code location name, referring to the Postal code and street address for the Counterparty.
transactions.counterParties.postalAddress.country
Deliver
Country code for the registered address of the Counterparty. Country code In ISO 3166-1/Alpha-2 code format.
transactions.counterParties.postalAddress.addressLines
Deliver
Additional address information, freetext.
transactions.additionalInfo
Deliver
Any other descriptive text that can be added to the transaction. Typically, information from the issuer of the transaction. This should not replace any structured elements in the API, e.g.: merchant, counterpartParties, transactionCode, references and various dates.
transactions.currencyExchange
Deliver
If there has been any currency conversion during the transaction, these fields describe the details of the currency exchange. To convert an amount from a source currency to a target currency, you use the exchange rate to multiply or divide the original amount.
transactions.currencyExchange.originalAmount
Deliver
Starting amount in original currency before conversion.
transactions.currencyExchange.sourceCurrency
Mandatory conditional
The currency to convert the amount from, ISO Standard 4217.
transactions.currencyExchange.targetCurrency
Mandatory conditional
The currency to which an amount is to be converted, ISO Standard 4217.
transactions.currencyExchange.unitCurrency
Deliver
unitCurrency indicates the base currency used for the currency calculation, ISO Standard 4217.
transactions.currencyExchange.exchangeRate
Mandatory conditional
The price of one currency in terms of another. This value is used to perform the conversion.
transactions.merchant
Deliver
Information about the merchant where the transaction was performed.
transactions.paymentCard
Deliver
Information about the payment card used for the transaction if the transaction is a card transaction.
transactions.paymentCard.cardIdentifier
Mandatory conditional
Card number. Must be masked by following the best practices given by PCI DSS. It is recommended at least to follow this standard: The first six and last four digits are the maximum number of digits that can be delivered. The rest must be filled with ‘X‘s and no spaces.
transactions.paymentCard.holderName
Mandatory conditional
Name of the card holder.
transactions.paymentCard.startDate
Mandatory conditional
| Start date on the card’s validity, regardless of the time period in the request (pattern: ^[0-9]+-([0][1-9] | 1[0-2])$): YYYY-MM. |
transactions.paymentCard.expiryDate
Mandatory conditional
| Expiration date of the card, regardless of the time period in the request (pattern: ^[0-9]+-([0][1-9] | 1[0-2])$): YYYY-MM. |
transactions.paymentCard.cardIssuerName
Mandatory conditional
Name of the financial institution that issued the card.
transactions.paymentCard.type
Mandatory conditional
Type of card.
| [creditCard, debitCard] |
transactions.paymentCard.cardStatus
Mandatory conditional
Current status of the card on the request date:
- active: The card is still active.
- blocked: The card is blocked.
| [active, blocked] |
transactions.paymentCard.versionNumber
Mandatory conditional
If the card number is reused when reissuing a card, then each reissued card gets a separate version number. Version of a card [1 to 9].
transactions.paymentCard.cardIssuerIdentifier
Deliver
transactions.paymentCard.cardIssuerIdentifier.countryOfResidence
Deliver
Country code. The country the card issuer belongs to in ISO 3166-1/Alpha-2 code format.
transactions.paymentCard.cardIssuerIdentifier.value
Mandatory conditional
Organization number of the card issuer.
transactions.paymentCard.cardIssuerIdentifier.type
Mandatory conditional
- countryIdentificationCode: The national registration code for businesses, enterprises, organizations and companies that is retrieved from the National register for organizations. In Norway this would be from BRREG.
- nationalIdentityNumber: Used for persons. The national identity code for persons. In Norway this would be P or D numbers from FREG.
| [countryIdentificationCode, nationalIdentityNumber] |
transactions.registered
Deliver
Date and time when the transaction was performed by Payer, in ISO Date: YYYY-MM-DDThh:mm:ssZ for UTC eller YYYY-MM-DDThh:mm:ss+hh for other timezones.
For example, +02 for CEST. 2020-05-07T12 :00 :00Z = 2020-05-07T14 :00 :00+02
transactions.amount
Mandatory conditional
The actual amount transacted. The amount should be stated in the currency of the account (ref. transactions.currency). Use transactions.creditDebitIndicator to indicate if the amount in the transaction is positive (credit) or negative (debit).
transactions.currency
Mandatory conditional
The currency used in the transactions.amount, ISO Standard 4217.
links
Deliver
To be used in relation to large result sets using pagination. Se further information here
links.rel
Mandatory conditional
Information about which page the url in href is about. Paginating as in; next, last.
For ‘next’: Next page in the result set. Absence of ‘next’ will be interpreted as this being the last page in the result set, and must therefore be empty if that is the case. Se futher information here.
links.href
Mandatory conditional
Link to the ‘rel’ page.
Change log
| Date | Change |
|---|---|
| 16.01.26 | Improved specification language for multiple data fields to ensure better interpretability. No behaviour or interface changes. Refer to the linked PDF for details. |
| 26.09.25 | Added clarification on how KID numbers should be returned with transactions.references.type. |
| 13.05.25 | Added clearer definition of transactions.creditDebitIndicator |
| 20.03.24 | New version of the DSOP Control API generating extensive changes throughout all documentation. |
| 03.05.23 | Added data model for V.1.2, includes responseDetails |