Account Information Service Provider API
New version 1.1.0 - enrichment of data for balances
- GET/accounts?withBalance - interimAvailable balance
- GET/accounts/account-id?withBalance - interimAvailable balance
- GET/accounts/account-id/balances - interimAvailable and openingBooked balances - new
- GET/accounts/account-id/transactions?withBalance - openingBooked and closingBooked balances - new
Update information:
1. The definition of SingleBalance has been changed - the referenceDate attribute has been added and the description of balanceType has been changed - type enum: interimAvailable, openingBooked, closingBooked.
2. Added the ability to retrieve transactions from account with a list of balances for the days in the specified period: start day (openingBooked) and end day (closingBooked) for each business day of the referenced period in which there are transactions when there is a call with parameter ?withBalance
3. A new balance type has been added to the account balance array: openingBooked in GET / accounts / account-id / balances.
Paths
/accounts
Read account list
Read the list of all accessible accounts relative to a granted consent. It is assumed that a consent of the PSU to this access is already given and stored on the Postbank system. The addressed list of accounts depends then on the PSU ID and OAuth2 access token. Returns all identifiers of the accounts, to which an account access has been granted to through the /consents endpoint by the PSU. In addition, relevant information about the accounts and hyperlinks to corresponding account information resources are provided if a related consent has been already granted.
ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initialed by the PSU.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}With balance flag.
OK
{
"schema": {
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"$ref": "#\/definitions\/Account"
}
}
},
"example": {
"accounts": [
{
"resourceId": "BG77BPBI000001",
"iban": "BG77BPBI000001",
"currency": "BGN",
"product": "Postbank Product",
"name": "salary",
"_links": {
"balances": {
"href": "\/v1.1.0\/accounts\/BG77BPBI000001\/balances"
},
"transactions": {
"href": "\/v1.1.0\/accounts\/BG77BPBI000001\/transactions"
}
}
},
{
"resourceId": "BG77BPBI000002",
Bad Request
Unauthorized
Forbidden
Internal Server Error
/accounts/{account-id}
Read Account Details
Reads details about the addressed account. It is assumed that a consent of the PSU to this access is already given and stored on the Postbank system. The addressed details of this account depends then on the stored consent addressed by the OAuth2 access token.
The account-id is retrieved by using a "Read Account List" call. The account-id is the "resourceId" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initialed by the PSU.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}With balance flag.
OK
{
"schema": {
"type": "object",
"properties": {
"account": {
"$ref": "#\/definitions\/Account"
}
},
"example": {
"account": {
"resourceId": "BG77BPBI000001",
"iban": "BG77BPBI000001",
"currency": "BGN",
"product": "Postbank Product",
"name": "salary",
"balances": [
{
"balanceType": "interimAvailable",
"balanceAmount": {
"currency": "BGN",
"amount": 120.9
},
"referenceDate": "2021-10-01"
}
],
"_links": {
"balances": {
"href": "\/v1.1.0\/accounts\/BG77BPBI000001\/balances"
},
"transactions": {
Bad Request
Unauthorized
Forbidden
Internal Server Error
/accounts/{account-id}/balances
Read Balance
Reads the balance list for a given account addressed by "account-id".
The account-id is retrieved by using a "Read Account List" call. The account-id is the "resourceId" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initialed by the PSU.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}OK
{
"schema": {
"type": "object",
"properties": {
"account": {
"$ref": "#\/definitions\/AccountReference"
},
"balances": {
"type": "array",
"items": {
"$ref": "#\/definitions\/SingleBalance"
}
}
},
"example": {
"account": {
"iban": "BG77BPBI000001"
},
"balances": [
{
"balanceType": "interimAvailable",
"balanceAmount": {
"currency": "BGN",
"amount": 123.45
},
"referenceDate": "2021-10-01"
},
{
"balanceType": "openingBooked",
"balanceAmount": {
"currency": "BGN",
"amount": 200.45
},
Bad Request
Unauthorized
Forbidden
Internal Server Error
/accounts/{account-id}/transactions
Read Transaction List
Read transaction lists of a given account аddressed by "account-id", depending on the steering parameter "bookingStatus" and the attributes "dateFrom" and "dateTo".
The account-id is retrieved by using a "Read Account List" call. The account-id is the "resourceId" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}Starting date (inclusive the date dateFrom) of the transaction list. Within 30 minutes after validation of PSU's consent, it is possible to request information for more than 90 days back. There is information available for a 5 year period.
{
"pattern": "([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))"
}End date (inclusive the data dateTo) of the transaction list, default is now if not given.
{
"pattern": "([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))"
}Permitted codes are “booked”.
{
"pattern": "(booked)"
}The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initialed by the PSU.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}OK
{
"schema": {
"type": "object",
"required": [
"account",
"transactions",
"_links"
],
"properties": {
"account": {
"$ref": "#\/definitions\/AccountReference"
},
"transactions": {
"$ref": "#\/definitions\/AccountReport"
},
"balances": {
"type": "array",
"items": {
"$ref": "#\/definitions\/SingleBalance"
}
},
"_links": {
"$ref": "#\/definitions\/Links"
}
},
"example": {
"account": {
"iban": "BG77BPBI000001"
},
"transactions": {
"booked": [
{
"debtorAccount": {
"iban": "BG77BPBI000001"
},
"creditorName": "Иван Bad Request
Unauthorized
Forbidden
Internal Server Error
/consents
/consents/{consent-id}
/consents/{consent-id}/status
Definitions
{
"type": "object",
"required": [
"currency",
"amount"
],
"properties": {
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}",
"description": "ISO 4217 code"
},
"amount": {
"pattern": "^[0-9]\\d{0,13}(\\.\\d{1,2})?$",
"type": "string"
}
}
}
{
"type": "object",
"required": [
"currency",
"resourceId",
"iban",
"name",
"product"
],
"properties": {
"resourceId": {
"type": "string",
"description": "This is the data element to be used in the path when retrieving data from a dedicated account."
},
"iban": {
"type": "string",
"description": "IBAN of account"
},
"name": {
"type": "string",
"description": "Name given by the bank or the PSU in OnlineBanking."
},
"product": {
"type": "string",
"description": "Product Name of the Bank for this account"
},
"currency": {
"type": "string",
"description": "ISO 4217 code"
},
"balances": {
"type": "array",
"items": {
"$ref": "#\/definitions\/SingleBalance"
}
},
"_links": {
"$ref": "#\/definitions\/Links",
"description": "Links to the account, which can be directly used for retrieving account information from this dedicated account. Links to “balances” and\/or “transactions”"
}
}
}
{
"type": "object",
"required": [
"booked"
],
"properties": {
"booked": {
"type": "array",
"items": {
"$ref": "#\/definitions\/Transactions"
}
}
}
}
{
"type": "object",
"properties": {
"interimAvailable": {
"$ref": "#\/definitions\/SingleBalance",
"description": "Available balance calculated in the course of the account ’ervicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time\/period specified."
}
}
}
{
"type": "object",
"required": [
"balanceType",
"balanceAmount",
"referenceDate"
],
"properties": {
"balanceType": {
"type": "string",
"enum": [
"interimAvailable",
"openingBooked",
"closingBooked"
]
},
"balanceAmount": {
"$ref": "#\/definitions\/Amount"
},
"referenceDate": {
"type": "string",
"format": "ISODate"
}
}
}
{
"type": "object",
"required": [
"transactionAmount"
],
"properties": {
"transactionId": {
"type": "string",
"description": "Can be used as access-id in the API, where more details on an transaction is offered."
},
"bookingDate": {
"type": "string",
"format": "date"
},
"valueDate": {
"type": "string",
"format": "date"
},
"transactionAmount": {
"$ref": "#\/definitions\/Amount"
},
"creditorName": {
"type": "string",
"description": "Name of the creditor if a “Debited” transaction"
},
"creditorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"debtorName": {
"type": "string",
"description": "Name of the debtor if a “Credited” transaction"
},
"debtorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"remittanceInformationUnstructured": {
"type": "string"
}
}
}
{
"type": "object",
"properties": {
"scaRedirect": {
"$ref": "#\/definitions\/Href",
"description": "A link to a Postbank site where SCA is performed within the Redirect SCA approach."
},
"self": {
"$ref": "#\/definitions\/Href",
"description": "The link to the resource created by the undergoing request. This link can be used to retrieve the resource data."
},
"status": {
"$ref": "#\/definitions\/Href"
},
"account": {
"$ref": "#\/definitions\/Href",
"description": "A link to an account, which can be directly used for retrieving account information from this dedicated account."
},
"balances": {
"$ref": "#\/definitions\/Href",
"description": "A link to the resource providing the balance of a dedicated account."
},
"transactions": {
"$ref": "#\/definitions\/Href",
"description": "A link to the resource providing the transaction history of a dedicated account."
},
"first": {
"$ref": "#\/definitions\/Href",
"description": "Navigation link for account reports."
},
"next": {
"$ref": "#\/definitions\/Href",
"description": "Navigation link for account reports."
},
"previous": {
"$ref": "#\/definitions\/Href",
"description": "Navigation link for account reports."
},
"last": {
"$ref": "#\/definitions\/Href",
"description": "Navigation link for account reports."
}
}
}
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"type": "string"
},
"code": {
"type": "string"
},
"text": {
"type": "string"
}
}
}
}
}
}
{
"type": "object",
"required": [
"access",
"frequencyPerDay",
"recurringIndicator",
"validUntil"
],
"properties": {
"access": {
"type": "object",
"properties": {
"balances": {
"type": "array",
"items": {
"type": "string"
}
},
"transactions": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"recurringIndicator": {
"type": "string",
"format": "boolean",
"description": "TRUE, if the consent is for recurring access to the account data. FALSE, if the consent is for one access to the account data.",
"pattern": "(true|false)"
},
"validUntil": {
"type": "string",
"format": "date",
"description": "This parameter is requesting a valid until date for the requested consent. Max validity is 180 day. If the consent is for one access to the account data value is current date.The content is the local Postbank date in ISODate Format, e.g. 2018-11-25",
"pattern": "([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))"
},
"frequencyPerDay": {
"type": "string",
"format": "integer",
"description": "This field indicates the requested maximum frequency for an access per day. For a one-off access, this attribute is set to “1”. Max value is “4”.",
"pattern": "[1-4]"
}
}
}
{
"required": [
"access",
"recurringIndicator",
"validUntil",
"frequencyPerDay",
"consentStatus",
"_links"
],
"type": "object",
"properties": {
"access": {
"$ref": "#\/definitions\/AccountAccess"
},
"recurringIndicator": {
"type": "boolean",
"description": "TRUE, if the consent is for recurring access to the account data FALSE, if the consent is for one access to the account data"
},
"validUntil": {
"type": "string",
"format": "date",
"description": "This parameter is requesting a valid until date for the requested consent. The content is the local Postbank date in ISODate Format, e.g. 2017-10-30"
},
"frequencyPerDay": {
"type": "integer",
"description": "Max value is \"4\"."
},
"consentStatus": {
"$ref": "#\/definitions\/ConsentStatus"
},
"_links": {
"$ref": "#\/definitions\/Links"
}
},
"example": {
"access": {
"balances": [
{
"iban": "BG77BPBI000001"
}
],
"transactions": [
{
"iban": "BG77BPBI000001"
},
{
"iban": "BG77BPBI000002"
}
]
},
"recurringIndicator": true,
"validUntil": "2018-12-25",
"frequencyPerDay": 2,
"consentStatus": "valid",
"_links": {
"account": {
"href": "\/v1.1.0\/accounts\/"
}
}
}
}
{
"properties": {
"iban": {
"type": "string"
},
"bban": {
"type": "string"
}
},
"additionalProperties": false
}
The following code values are permitted “received”, “rejected”, “valid”, “revokedByPsu”, “expired”, “terminatedByTpp”
{
"type": "string",
"enum": [
"received",
"rejected",
"valid",
"revokedByPsu",
"expired",
"terminatedByTpp"
],
"additionalProperties": false
}
{
"properties": {
"balances": {
"type": "array",
"items": {
"$ref": "#\/definitions\/AccountReference"
}
},
"transactions": {
"type": "array",
"items": {
"$ref": "#\/definitions\/AccountReference"
}
}
},
"additionalProperties": false
}
{
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}