PSD2 BG Account Information Service API (AIS) 1.0.6

No votes yet

Berlin Group, openbanking, AIS

Description

The AIS API implements the Account Information Service parts of the PSD2 specification, and provides the following services to authorised TPPs:

Accounts overview
Account balances
Account transactions
Accountdetails

Access to the Account Information Service API is controlled through the general onboarding/enrollment flow. I.e. the API is only accessible to valid TPPs, who have completed the enrollment in order to upload and verify their qualified certificates. By accessing the API, you confirm that you already have status as an authorized TPP - or (for sandbox access only) that your application has been submitted to a local NCA and is pending approval. Only TPPs who can document their authorization status are elegible for support.

The AIS API is part of the general PSD2 XS2A implementation and works in the same security context. In addition to the information contained below, all communication, headers and additional steps adhere to the general security model and flows. Refer to this link for up to date information on required security headers.

The API is implemented against Berlin Group XS2A version 1.3.

Note about this version This version of the AIS API now also supports testing of security, consent and SCA flows in sandbox with full security context.

The sandbox API works on (stateless) mocked account data, while SCA, security and consent flows are identical to production.
The security model for TPP enrollment and PSU authentication/authorization is implemented and enforced for both production and sandbox API

Access to API Endpoints

Production and sandbox access: Prior to calling the API the TPP must complete the (one-time) process for Onboarding on a per-bank basis. Separate API URL/host endpoints are required for each bank under the BEC Umbrella. Consult the Environments section for information on URL schemas in production and sandbox environments. See list of included ASPSPs and their corresponding urls by following this link. The X-IBM-Client-Id attribute is not required in this version.

Contact information

BEC PSD2 Support

psd2.support@bec.dk

https://apiportal.prod.bec.dk/openbanking/sandbox/

Support

Discuss this API in the forum

Endpoints

development

https://api.sandbox.openbanking.bec.dk

Paths

/accounts

Berlin Group, openbanking, AIS

Description

Read the identifiers of the available payment account together with booking balance information, depending on the consent granted.

Parameters

X-Request-ID

Required in header

string / uuid

ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).

Consent-ID

Required in header

string

consent identifier for the request

withBalance

Required in query

boolean

If contained, this function reads the list of accessible payment accounts including the booking balance, if granted by the PSU in the related consent and available by the ASPSP.

Optional in header

string

application/json

Responses

200

AccountsResponse

401

Unauthorized

403

Forbidden

404

Attribute description not found

tppMessages

Example Request

Example Response

Definition

GET https://api.sandbox.openbanking.bec.dk/bg/openbanking/v1/accounts

Response

/accounts/{resourceId}

Berlin Group, openbanking, AIS

Description

Reads details about an account, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed details of this account depends then on the stored consent addressed by consentId.

Parameters

X-Request-ID

Required in header

string / uuid

ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).

resourceId

Required in path

string

Unique identifier for the account

Consent-ID

Required in header

string

consent identifier for the request

withBalance

Required in query

boolean

If contained, this function reads the list of accessible payment accounts including the booking balance, if granted by the PSU in the related consent and available by the ASPSP.

Optional in header

string

application/json

Responses

200

AccountResponse

401

Unauthorized

403

Forbidden

404

Attribute description not found

tppMessages

Example Request

Example Response

Definition

GET https://api.sandbox.openbanking.bec.dk/bg/openbanking/v1/accounts/{resourceId}

Response

/accounts/{resourceId}/balances

Berlin Group, openbanking, AIS

Description

Reads balances data from a given account addressed by "resourceId".

Parameters

X-Request-ID

Required in header

string / uuid

ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).

resourceId

Required in path

string

Unique identifier for the account

Consent-ID

Required in header

string

consent identifier for the request

Optional in header

string

application/json

Responses

200

BalanceDetails

401

Unauthorized

403

Forbidden

404

Attribute description not found

tppMessages

Example Request

Example Response

Definition

GET https://api.sandbox.openbanking.bec.dk/bg/openbanking/v1/accounts/{resourceId}/balances

Response

/accounts/{resourceId}/transactions

Berlin Group, openbanking, AIS

Description

Read transaction reports or transaction lists of a given account addressed by "resource-id", depending on the steering parameter "bookingStatus" together with balances.

Parameters

X-Request-ID

Required in header

string / uuid

ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).

resourceId

Required in path

string

Unique identifier for the account

Consent-ID

Required in header

string

consent identifier for the request

bookingStatus

Optional in query

string

Permitted codes are "booked", "pending" and "both" "booked" shall be supported by the ASPSP.To support the "pending" and "both" feature is optional for the ASPSP, Error code if not supported in the online banking frontend. Currently only "booked" status is supported.

{
    "enum": [
        "booked",
        "pending",
        "both"
    ]
}

dateFrom

Required in query

string

Starting date (inclusive the date dateFrom) of the transaction list, mandated if no delta access is require. Example: 2018-12-24

dateTo

Optional in query

string

End date (inclusive the data dateTo) of the transaction list, default is now if not given. Example: 2018-12-29

deltaList

Optional in query

string

Delta List - not supported

entryReferenceFrom

Optional in query

string

Entry Reference From - not supported

Optional in header

string

application/json

Responses

200

TransactionsResponse

400

Attribute description not found

tppMessages

404

Attribute description not found

tppMessages

Example Request

Example Response

Definition

GET https://api.sandbox.openbanking.bec.dk/bg/openbanking/v1/accounts/{resourceId}/transactions

Response

/accounts/{resourceId}/transactions/{transactionId}

Berlin Group, openbanking, AIS

Summary

Read details for a given transaction (transactionId) addressed by the account (resourceId).

Parameters

X-Request-ID

Required in header

string / uuid

ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).

resourceId

Required in path

string

Unique identifier for the account

Consent-ID

Required in header

string

consent identifier for the request

transactionId

Required in path

string

transactionId for the account transaction

Optional in header

string

application/json

Responses

200

TransactionResponse

400

Attribute description not found

tppMessages

404

Attribute description not found

tppMessages

Example Request

Example Response

Definition

GET https://api.sandbox.openbanking.bec.dk/bg/openbanking/v1/accounts/{resourceId}/transactions/{transactionId}

Response

Definitions

AccountDetails

The ASPSP shall give at least one of the account reference identifiers:

iban
pan If the account is a multicurrency account currency code in "currency" is set to "XXX".

{
    "type": "object",
    "properties": {
        "resourceId": {
            "description": "Unique identifier for the account",
            "type": "string",
            "maxLength": 35
        },
        "iban": {
            "$ref": "#\/definitions\/Iban"
        },
        "currency": {
            "type": "string",
            "example": "DKK",
            "description": "The Currency code. This MUST be a valid ISO 4217 currency code. See the ASPSPs' documentation for details of supported currencies.",
            "minLength": 3,
            "maxLength": 3
        },
        "name": {
            "description": "Name of the account given by the bank or the PSU in online-banking.",
            "type": "string",
            "maxLength": 35
        },
        "product": {
            "description": "Product name of the bank for this account, proprietary definition.",
            "type": "string",
            "maxLength": 35
        },
        "ownerName": {
            "description": "Acount owner name. Returned only for the specific account details if the consent mandates 'allAccountsWithOwnerName' access type.",
            "type": "string",
            "maxLength": 35
        },
        "bic": {
            "$ref": "#\/definitions\/bicfi"
        },
        "balances": {
            "type": "array",
            "items": {
                "$ref": "#\/definitions\/Balance"
            }
        },
        "_links": {
            "$ref": "#\/definitions\/AisLinks"
        }
    }
}

AccountResponse

{
    "type": "object",
    "properties": {
        "account": {
            "$ref": "#\/definitions\/AccountDetails"
        }
    },
    "title": "AccountResponse"
}

AccountsResponse

{
    "type": "object",
    "properties": {
        "accounts": {
            "type": "array",
            "items": {
                "$ref": "#\/definitions\/AccountDetails"
            }
        }
    },
    "title": "AccountsResponse"
}

Amount

Monetary Amount, including currency code and value

{
    "type": "object",
    "required": [
        "amount",
        "currency"
    ],
    "properties": {
        "amount": {
            "type": "number",
            "example": 5864.85,
            "description": "The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. Negative amounts are signed by minus.\nThe decimal separator is a dot.: -?[0-9]{1,14}(\\.[0-9]{1,3})?"
        },
        "currency": {
            "type": "string",
            "example": "DKK",
            "description": "The Currency code. This MUST be a valid ISO 4217 currency code. See the ASPSPs' documentation for details of supported currencies.",
            "minLength": 3,
            "maxLength": 3
        }
    },
    "title": "Amount"
}

Balance

A single balance element

{
    "type": "object",
    "required": [
        "balanceAmount",
        "balanceType"
    ],
    "properties": {
        "balanceAmount": {
            "$ref": "#\/definitions\/Amount"
        },
        "balanceType": {
            "type": "string",
            "enum": [
                "closingBooked",
                "expected",
                "authorised",
                "openingBooked",
                "interimAvailable",
                "forwardAvailable"
            ]
        },
        "lastChangeDateTime": {
            "description": "This data element might be used to indicate e.g. with the expected or booked balance that no action is known \non the account, which is not yet booked.\n",
            "type": "string",
            "format": "date-time"
        }
    },
    "title": "Balance"
}

BalanceDetails

{
    "type": "object",
    "properties": {
        "account": {
            "$ref": "#\/definitions\/AccountReference"
        },
        "balances": {
            "type": "array",
            "items": {
                "$ref": "#\/definitions\/Balance"
            }
        }
    },
    "title": "BalanceDetails"
}

AccountReference

{
    "type": "object",
    "properties": {
        "iban": {
            "$ref": "#\/definitions\/Iban"
        },
        "resourceId": {
            "type": "string"
        }
    },
    "title": "AccountReference"
}

TransactionDetails

Transaction details

{
    "type": "object",
    "required": [
        "transactionAmount"
    ],
    "properties": {
        "bankTransactionCode": {
            "type": "string",
            "description": "Bank transaction code as used by the ASPSP"
        },
        "bookingDate": {
            "type": "string",
            "format": "date"
        },
        "creditorAccount": {
            "$ref": "#\/definitions\/AccountReference"
        },
        "creditorName": {
            "type": "string",
            "description": "creditor name"
        },
        "creditorId": {
            "type": "string",
            "description": "Identification of creditor used in payment slips"
        },
        "creditorAgent": {
            "$ref": "#\/definitions\/bicfi"
        },
        "ultimateCreditor": {
            "type": "string",
            "description": "Ultimate creditor used in foreign transfers"
        },
        "entryReference": {
            "type": "string",
            "description": "Is the identification of the transaction as used e.g. for reference for deltafunction on application level. \nThe same identification as for example used within camt.05x messages.\n",
            "maxLength": 35
        },
        "debtorName": {
            "type": "string",
            "description": "debtor name"
        },
        "debtorId": {
            "type": "string",
            "description": "Identification of debtor used in payment slips"
        },
        "debtorAccount": {
            "$ref": "#\/definitions\/AccountReference"
        },
        "mandateId": {
            "type": "string",
            "description": "Identifier for mandates used for example in Betaling Service."
        },
        "transactionAmount": {
            "$ref": "#\/definitions\/Amount"
        },
        "originalAmount": {
            "$ref": "#\/definitions\/Amount"
        },
        "transactionFees": {
            "$ref": "#\/definitions\/Amount"
        },
        "currencyExchange": {
            "$ref": "#\/definitions\/CurrencyExchange"
        },
        "transactionId": {
            "type": "string",
            "description": "Unique identifier for the transaction"
        },
        "valueDate": {
            "type": "string",
            "format": "date",
            "description": "The Date at which assets become available to the account owner in case of a credit."
        },
        "remittanceInformationStructured": {
            "$ref": "#\/definitions\/RemittanceInformationStructured"
        },
        "paymentIdentification": {
            "type": "string",
            "description": "Payment identification used for example in payment slips"
        },
        "paymentInformation": {
            "type": "string",
            "description": "Payment information"
        },
        "nemKontoId": {
            "type": "string"
        },
        "debtor": {
            "type": "string",
            "description": "Debtor information"
        },
        "clearingTime": {
            "type": "string"
        },
        "transferReceipt": {
            "type": "boolean"
        },
        "additionalInformation": {
            "type": "string",
            "description": "Payment additional information"
        },
        "remittanceInformationUnstructured": {
            "type": "string"
        },
        "endToEndId": {
            "type": "string",
            "description": "End to end payment identification"
        },
        "noteNumber": {
            "type": "string",
            "description": "Note number for foreign transfers"
        },
        "creditorAgentProprietary": {
            "$ref": "#\/definitions\/bicfi"
        },
        "creditorAgentName": {
            "type": "string",
            "description": "Agent name for foreign transfer"
        },
        "paymentType": {
            "type": "string",
            "description": "Payment type for foreign transfer"
        },
        "paymentTerms": {
            "type": "string",
            "description": "Terms of payment for foreign transfer"
        },
        "additionalTransactionInformationStructured": {
            "$ref": "#\/definitions\/AdditionalTransactionInformationStructured"
        }
    },
    "title": "TransactionDetails"
}

TransactionResponse

{
    "type": "object",
    "properties": {
        "transactionsDetails": {
            "$ref": "#\/definitions\/TransactionDetails"
        }
    },
    "title": "TransactionResponse"
}

TransactionsReference

{
    "type": "object",
    "properties": {
        "booked": {
            "type": "array",
            "items": {
                "$ref": "#\/definitions\/TransactionDetails"
            }
        },
        "pending": {
            "type": "array",
            "items": {
                "$ref": "#\/definitions\/TransactionDetails"
            }
        }
    },
    "title": "TransactionsReference"
}

TransactionsResponse

{
    "type": "object",
    "properties": {
        "_links": {
            "$ref": "#\/definitions\/AisLinks"
        },
        "account": {
            "$ref": "#\/definitions\/AccountReference"
        },
        "transactions": {
            "$ref": "#\/definitions\/TransactionsReference"
        }
    },
    "title": "TransactionsResponse"
}

AisLinks

{
    "type": "object",
    "properties": {
        "account": {
            "$ref": "#\/definitions\/Link"
        },
        "balances": {
            "$ref": "#\/definitions\/Link"
        },
        "self": {
            "$ref": "#\/definitions\/Link"
        },
        "transactions": {
            "$ref": "#\/definitions\/Link"
        }
    },
    "title": "AisLinks"
}

Link

Link to a resource

{
    "type": "object",
    "properties": {
        "href": {
            "type": "string",
            "example": "\/v1\/link\/to\/some\/resource",
            "description": "URL pointing to a resource"
        }
    },
    "title": "Link"
}

Iban

IBAN of an account [A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}

{
    "type": "string",
    "example": "FR7612345987650123456789014"
}

bicfi

BICFI '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}'

{
    "type": "string",
    "example": "AAAADEBBXXX"
}

CurrencyExchange

{
    "type": "object",
    "properties": {
        "sourceCurrency": {
            "type": "string",
            "example": "DKK",
            "description": "The Currency code. This MUST be a valid ISO 4217 currency code. See the ASPSPs' documentation for details of supported currencies.",
            "minLength": 3,
            "maxLength": 3
        },
        "exchangeRate": {
            "type": "number",
            "example": 0.85
        },
        "unitCurrency": {
            "type": "string",
            "example": "DKK",
            "minLength": 3,
            "maxLength": 3
        },
        "targetCurrency": {
            "type": "string",
            "example": "DKK",
            "minLength": 3,
            "maxLength": 3
        },
        "quotationDate": {
            "type": "string",
            "format": "date"
        }
    },
    "title": "CurrencyExchange"
}

RemittanceInformationStructured

Remittance information

{
    "type": "object",
    "properties": {
        "reference": {
            "type": "string"
        },
        "referenceType": {
            "type": "string"
        },
        "referenceIssuer": {
            "type": "string"
        }
    }
}

AdditionalTransactionInformationStructured

Additional Transaction Information Structured

{
    "type": "object",
    "properties": {
        "paymentStatus": {
            "type": "string",
            "description": "actual status of payment"
        },
        "transactionCreated": {
            "$ref": "#\/definitions\/TransactionAction"
        },
        "transactionAuthorized": {
            "type": "array",
            "items": {
                "$ref": "#\/definitions\/TransactionAction"
            }
        }
    }
}

TransactionAction

Information about payment creation, or signing

{
    "type": "object",
    "properties": {
        "user": {
            "$ref": "#\/definitions\/User"
        },
        "dateTime": {
            "type": "string",
            "format": "date-time"
        }
    }
}

User

Information about payment signer, creator identity

{
    "type": "object",
    "properties": {
        "id": {
            "type": "string"
        },
        "name": {
            "type": "string"
        }
    }
}

tppMessages

Error messages supplied for TPP

{
    "type": "object",
    "properties": {
        "tppMessages": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "category": {
                        "type": "string"
                    },
                    "code": {
                        "type": "string"
                    },
                    "text": {
                        "type": "string"
                    }
                }
            }
        }
    }
}