Statements - v3.1.2

  1. Overview
  2. Endpoints
    1. GET /accounts/{AccountId}/statements
    2. GET /accounts/{AccountId}/statements/{StatementId}
    3. GET /accounts/{AccountId}/statements/{StatementId}/file
    4. GET /accounts/{AccountId}/statements/{StatementId}/transactions
    5. GET /statements
  3. Data Model
    1. Resource Definition
    2. UML Diagram
    3. Notes
    4. Filtering
      1. Filtering Examples
    5. Permission Codes
    6. Data Dictionary
  4. Usage Examples
    1. Specific Account
      1. Get Account Statements Request
      2. Get Account Statements Response
    2. Bulk
      1. Get Statements Request
      2. Get Statements Response

Overview

The statements resource is used by an AISP to retrieve the

  • statements information
  • statement information for a StatementId in json and non-json(file) format.
  • transactions for a selected StatementId

for a specific account identified by AccountId or retrieve statement information for all accounts that the PSU has consented to.

This resource description should be read in conjunction with a compatible Account Information Services API Profile.

Endpoints

Endpoints for the resource and available methods.

 ResourceHTTP OperationEndpointMandatory?ScopeGrant TypeIdempotency KeyParametersRequest ObjectResponse Object
1statementsGETGET /accounts/{AccountId}/statementsConditionalaccountsAuthorization CodeNoPagination Filtering OBReadStatement2
2statementsGETGET /accounts/{AccountId}/statements/{StatementId}ConditionalaccountsAuthorization CodeNo  OBReadStatement2
3statementsGETGET /accounts/{AccountId}/statements/{StatementId}/fileOptionalaccountsAuthorization CodeNo  File
4transactionsGETGET /accounts/{AccountId}/statements/{StatementId}/transactionsConditionalaccountsAuthorization CodeNoPagination OBReadTransaction5
5statementsGETGET /statementsOptionalaccountsAuthorization CodeNoPagination Filtering OBReadStatement2

GET /accounts/{AccountId}/statements

An ASPSP may provide this endpoint for AISPs to retrieve the statements information resource for the AccountId (which is retrieved in the call to GET /accounts).

GET /accounts/{AccountId}/statements/{StatementId}

An ASPSP may provide this endpoint for AISPs to retrieve the statement information resource for a specific statement in the AccountId (which is retrieved in the call to GET /accounts).

GET /accounts/{AccountId}/statements/{StatementId}/file

An ASPSP may provide this endpoint for AISPs to retrieve a non-json representation of a specific statement.

GET /accounts/{AccountId}/statements/{StatementId}/transactions

An ASPSP may provide this endpoint for AISPs to retrieve transactions that appear on the selected statement. The data model for the returned objects is documented in the transactions resource.

GET /statements

An ASPSP may provide this endpoint for AISPs to retrieve statement information for all accounts that the PSU has consented to. This will retrieve the statement resources for all authorised accounts linked to the account-request.

Data Model

The OBReadStatement2 object will be used for the call to:

  • GET /statements
  • GET /accounts/{AccountId}/statements
  • GET /accounts/{AccountId}/statements/{StatementId}

The call to

  • GET /accounts/{AccountId}/statements/{StatementId}/file

will return unstructured data in binary (e.g., pdf, doc) or text (e.g., csv) formats. This will be specified in the Accept header by the AISP.

The OBReadTransaction3 object (documented in the transactions resource) will be used the call to:

  • GET /accounts/{AccountId}/statements/{StatementId}/transactions

Resource Definition

A resource that describes summary details for an account statement period. For a specific date range, an account (AccountId) may have no statements, or may have multiple statements. The /statements endpoint (if implemented by the ASPSP) must return all statements within the requested date range for all accounts selected during the authorisation of the account-request. If an AISP would like to access a specific statement (StatementId) to retrieve a formal statement download or transactions for a specific statement - the AISP must specify the account (the AccountId) via the URI request path i.e., via:

  • GET /accounts/{AccountId}/statements/{StatementId}/file - to download the statement.
  • GET /accounts/{AccountId}/statements/{StatementId}/transactions - to return the transactions relating to a statement.

UML Diagram

 OBReadStatement2.png

Notes

  • The statements resource must only be used for data that can be returned for a statement period.
  • StartDateTime, EndDateTime and CreationDateTime are mandatory for the statements resource. If an ASPSP does not display these dates in an online channel, the ASPSP must populate these dates with sensible values. E.g., the StartDateTime could be the day after the previous statement EndDateTime, and the CreationDateTime could be the day after the EndDateTime.

Filtering

Limited support for filtering is provided on the statements resource.

NameOccurrenceEnhanced DefinitionClass
fromStatementDateTime0..1Specifies start date and time for filtering of the Statements on the Statement/StartDateTime field. If this is not populated, the start date will be open endedISODateTime
toStatementDateTime0..1Specifies end date and time for filtering of the Statements on the Statement/StartDateTime field. If this is not populated, the end date will be open endedISODateTime

The ASPSP must treat the following as valid input:

  • non-working days (e.g. a Sunday or a Bank holiday) or any other days on which no transactions are recorded
  • dates that fall outside the range for which transaction information is provided through APIs
  • dates that fall outside the range for which a consent authorisation is available.

In the above situations, the ASPSP must return statements where the StartDateTime and EndDateTime are both between the fromStatementDateTime and toStatementDateTime parameters.

Filtering Examples

// All statements from 1st Jan, 2015
GET /statements?fromStatementDateTime=2015-01-01T00:00:00
 
// All statements in 2016
GET /statements?fromStatementDateTime=2016-01-01T00:00:00&toStatementDateTime=2016-12-31T23:59:59
 
// All statements in a specific account up to 31-Mar-2017
GET /accounts/1/statements?toStatementDateTime=2017-03-31T23:59:59

Permission Codes

The resource differs depending on the permissions (ReadStatementsBasic and ReadStatementsDetail) used to access resource (the OBReadStatement2 object). In the event the resource is accessed with both ReadStatementsBasic and ReadStatementsDetail, the most detailed level (ReadStatementsDetail) must be used.

  • These objects must not be returned without the ReadStatementsDetail permission:
  • OBReadStatement2/Data/Statement/StatementAmount
  • Calls to GET /accounts/{AccountId}/statements/{StatementId}/file

  • If the ReadStatementsDetail is granted by the PSU:
    • OBReadStatement2/Data/Statement/StatementAmount may be returned if applicable to the statement and ASPSP (0..n)

For the call toGET /accounts/{AccountId}/statements/{StatementId}/transactions:

  • The ReadTransactionsBasic or ReadTransactionsDetail (in addition to the appropriate ReadTransactionsCredits and/or ReadTransactionsDebits ) permission codes will be required. The ASPSP must apply the same access to GET /accounts/{AccountId}/statements/{StatementId}/transactions as GET /accounts/{AccountId}/transactions
  • If the ReadPAN permission is granted by the PSU - the ASPSP may choose to populate the unmasked PAN - if the PAN is being populated in the response for these fields:
    • OBReadTransaction3/Data/Transaction/CreditorAgent/Identification
    • OBReadTransaction3/Data/Transaction/DebtorAccount/Identification
    • OBReadTransaction3/Data/Transaction/CardInstrument/Identification

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadStatement2 OBReadStatement2 OBReadStatement2  
Data1..1OBReadStatement2/Data OBReadDataStatement2  
Statement0..nOBReadStatement2/Data/StatementProvides further details on a statement resource.OBStatement2  
AccountId1..1OBReadStatement2/Data/Statement/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text  
StatementId0..1OBReadStatement2/Data/Statement/StatementIdUnique identifier for the statement resource within an servicing institution. This identifier is both unique and immutable.Max40Text  
StatementReference0..1OBReadStatement2/Data/Statement/StatementReferenceUnique reference for the statement. This reference may be optionally populated if available.Max35Text  
Type1..1OBReadStatement2/Data/Statement/TypeStatement type, in a coded form.OBExternalStatementType1CodeAccountClosure AccountOpening Annual Interim RegularPeriodic 
StartDateTime1..1OBReadStatement2/Data/Statement/StartDateTimeDate and time at which the statement period starts.ISODateTime  
EndDateTime1..1OBReadStatement2/Data/Statement/EndDateTimeDate and time at which the statement period ends.ISODateTime  
CreationDateTime1..1OBReadStatement2/Data/Statement/CreationDateTimeDate and time at which the resource was created.ISODateTime  
StatementDescription0..nOBReadStatement2/Data/Statement/StatementDescriptionOther descriptions that may be available for the statement resource.Max500Text  
StatementBenefit0..nOBReadStatement2/Data/Statement/StatementBenefitSet of elements used to provide details of a benefit or reward amount for the statement resource.OBStatementBenefit1  
Type1..1OBReadStatement2/Data/Statement/StatementBenefit/TypeBenefit type, in a coded form.OBExternalStatementBenefitType1Code  
Amount1..1OBReadStatement2/Data/Statement/StatementBenefit/AmountAmount of money associated with the statement benefit type.OBActiveOrHistoricCurrencyAndAmount  
Amount1..1OBReadStatement2/Data/Statement/StatementBenefit/Amount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.OBActiveCurrencyAndAmount_SimpleType ^\d{1,13}.\d{1,5}$
Currency1..1OBReadStatement2/Data/Statement/StatementBenefit/Amount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 “Codes for the representation of currencies and funds”.ActiveOrHistoricCurrencyCode ^[A-Z]{3,3}$
StatementFee0..nOBReadStatement2/Data/Statement/StatementFeeSet of elements used to provide details of a fee for the statement resource.OBStatementFee2  
Description0..1OBReadStatement2/Data/Statement/StatementFee/DescriptionDescription that may be available for the statement fee.Max128Text  
CreditDebitIndicator1..1OBReadStatement2/Data/Statement/StatementFee/CreditDebitIndicatorIndicates whether the amount is a credit or a debit. Usage: A zero amount is considered to be a credit amount.OBCreditDebitCodeCredit Debit 
Type1..1OBReadStatement2/Data/Statement/StatementFee/TypeFee type, in a coded form.OBExternalStatementFeeType1Code  
Rate0..1OBReadStatement2/Data/Statement/StatementFee/RateRate charged for Statement Fee (where it is charged in terms of a rate rather than an amount)OBRate1  
RateType0..1OBReadStatement2/Data/Statement/StatementFee/RateTypeDescription that may be available for the statement fee rate type.OBExternalStatementFeeRateType1CodeUK.OBIE.AER UK.OBIE.EAR 
Frequency0..1OBReadStatement2/Data/Statement/StatementFee/FrequencyHow frequently the fee is applied to the Account.OBExternalStatementFeeFrequency1CodeUK.OBIE.ChargingPeriod UK.OBIE.PerTransactionAmount UK.OBIE.PerTransactionPercentage UK.OBIE.Quarterly UK.OBIE.StatementMonthly UK.OBIE.Weekly 
Amount1..1OBReadStatement2/Data/Statement/StatementFee/AmountAmount of money associated with the statement fee type.OBActiveOrHistoricCurrencyAndAmount  
Amount1..1OBReadStatement2/Data/Statement/StatementFee/Amount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.OBActiveCurrencyAndAmount_SimpleType ^\d{1,13}.\d{1,5}$
Currency1..1OBReadStatement2/Data/Statement/StatementFee/Amount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 “Codes for the representation of currencies and funds”.ActiveOrHistoricCurrencyCode ^[A-Z]{3,3}$
StatementInterest0..nOBReadStatement2/Data/Statement/StatementInterestSet of elements used to provide details of a generic interest amount related to the statement resource.OBStatementInterest2  
Description0..1OBReadStatement2/Data/Statement/StatementInterest/DescriptionDescription that may be available for the statement interest.Max128Text  
CreditDebitIndicator1..1OBReadStatement2/Data/Statement/StatementInterest/CreditDebitIndicatorIndicates whether the amount is a credit or a debit. Usage: A zero amount is considered to be a credit amount.OBCreditDebitCodeCredit Debit 
Type1..1OBReadStatement2/Data/Statement/StatementInterest/TypeInterest amount type, in a coded form.OBExternalStatementInterestType1Code  
Rate0..1OBReadStatement2/Data/Statement/StatementInterest/RateRate for Statement Interest (where it is applicable in terms of a rate rather than an amount)OBRate1  
RateType0..1OBReadStatement2/Data/Statement/StatementInterest/RateTypeDescription that may be available for the statement Interest rate type.OBExternalStatementInterestRateType1CodeUK.OBIE.BOEBaseRate UK.OBIE.FixedRate UK.OBIE.Gross UK.OBIE.LoanProviderBaseRate UK.OBIE.Net 
Frequency0..1OBReadStatement2/Data/Statement/StatementInterest/FrequencyHow frequently the Interest Rate is applied to the Account.OBExternalStatementInterestFrequency1CodeUK.OBIE.Daily UK.OBIE.HalfYearly UK.OBIE.Monthly UK.OBIE.PerStatementDate UK.OBIE.Quarterly UK.OBIE.Weekly UK.OBIE.Yearly 
Amount1..1OBReadStatement2/Data/Statement/StatementInterest/AmountAmount of money associated with the statement interest amount type.OBActiveOrHistoricCurrencyAndAmount  
Amount1..1OBReadStatement2/Data/Statement/StatementInterest/Amount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.OBActiveCurrencyAndAmount_SimpleType ^\d{1,13}.\d{1,5}$
Currency1..1OBReadStatement2/Data/Statement/StatementInterest/Amount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 “Codes for the representation of currencies and funds”.ActiveOrHistoricCurrencyCode ^[A-Z]{3,3}$
StatementAmount0..nOBReadStatement2/Data/Statement/StatementAmountSet of elements used to provide details of a generic amount for the statement resource.OBStatementAmount1  
CreditDebitIndicator1..1OBReadStatement2/Data/Statement/StatementAmount/CreditDebitIndicatorIndicates whether the amount is a credit or a debit. Usage: A zero amount is considered to be a credit amount.OBCreditDebitCodeCredit Debit 
Type1..1OBReadStatement2/Data/Statement/StatementAmount/TypeAmount type, in a coded form.OBExternalStatementAmountType1Code  
Amount1..1OBReadStatement2/Data/Statement/StatementAmount/AmountAmount of money associated with the amount type.OBActiveOrHistoricCurrencyAndAmount  
Amount1..1OBReadStatement2/Data/Statement/StatementAmount/Amount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.OBActiveCurrencyAndAmount_SimpleType ^\d{1,13}.\d{1,5}$
Currency1..1OBReadStatement2/Data/Statement/StatementAmount/Amount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 “Codes for the representation of currencies and funds”.ActiveOrHistoricCurrencyCode ^[A-Z]{3,3}$
StatementDateTime0..nOBReadStatement2/Data/Statement/StatementDateTimeSet of elements used to provide details of a generic date time for the statement resource.OBStatementDateTime1  
DateTime1..1OBReadStatement2/Data/Statement/StatementDateTime/DateTimeDate and time associated with the date time type.ISODateTime  
Type1..1OBReadStatement2/Data/Statement/StatementDateTime/TypeDate time type, in a coded form.OBExternalStatementDateTimeType1Code  
StatementRate0..nOBReadStatement2/Data/Statement/StatementRateSet of elements used to provide details of a generic rate related to the statement resource.OBStatementRate1  
Rate1..1OBReadStatement2/Data/Statement/StatementRate/RateRate associated with the statement rate type.OBExternalStatementRateType1Code ^(-?\d{1,3}){1}(.\d{1,4}){0,1}$
Type1..1OBReadStatement2/Data/Statement/StatementRate/TypeStatement rate type, in a coded form.Max40Text  
StatementValue0..nOBReadStatement2/Data/Statement/StatementValueSet of elements used to provide details of a generic number value related to the statement resource.OBStatementValue1  
Value1..1OBReadStatement2/Data/Statement/StatementValue/ValueValue associated with the statement value type.OBExternalStatementValueType1Code  
Type1..1OBReadStatement2/Data/Statement/StatementValue/TypeStatement value type, in a coded form.Max40Text  

Usage Examples

Specific Account

Get Account Statements Request

GET /accounts/22289/statements HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Get Account Statements Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
{
  "Data": {
    "Statement": [
    {
      "AccountId": "22289",
      "StatementId": "8sfhke-sifhkeuf-97813",
      "StatementReference": "002",
      "Type": "RegularPeriodic",
      "StartDateTime": "2017-08-01T00:00:00+00:00",
      "EndDateTime": "2017-08-31T23:59:59+00:00",
      "CreationDateTime": "2017-09-01T00:00:00+00:00",
      "StatementDescription": ["August 2017 Statement", "One Free Uber Ride"],
      "StatementAmount": [
      {
        "Amount": {
          "Amount": "400.00",
          "Currency": "GBP"
        },
		"CreditDebitIndicator": "Credit",        
		"Type": "ClosingBalance"        
      }, 
      {
        "Amount": {
          "Amount": "600.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "PreviousClosingBalance"
      }
      ]
    }, 
    {
      "AccountId": "22289",
      "StatementId": "34hj24u-324h33-31i3p4",
      "StatementReference": "003",
      "Type": "RegularPeriodic",
      "StartDateTime": "2017-09-01T00:00:00+00:00",
      "EndDateTime": "2017-09-30T23:59:59+00:00",
      "CreationDateTime": "2017-10-01T00:00:00+00:00",
      "StatementDescription": ["September 2017 Statement"],
      "StatementAmount": [
      {
        "Amount": {
          "Amount": "200.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "PreviousClosingBalance"
      },
      {
        "Amount": {
          "Amount": "400.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "PreviousClosingBalance"
      }
      ]
    }],
    "Links": {
      "Self": "https://api.alphabank.com/open-banking/v3.1/aisp/accounts/22289/statements/"
    },
    "Meta": {
      "TotalPages": 1
    }
  }
}

Bulk

Get Statements Request

GET /statements HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Get Statements Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
{
  "Data": {
    "Statement": [
    {
      "AccountId": "22289",
      "StatementId": "8sfhke-sifhkeuf-97813",
      "StatementReference": "002",
      "Type": "RegularPeriodic",
      "StartDateTime": "2017-08-01T00:00:00+00:00",
      "EndDateTime": "2017-08-31T23:59:59+00:00",
      "CreationDateTime": "2017-09-01T00:00:00+00:00",
      "StatementDescription": ["August 2017 Statement", "One Free Uber Ride"],
      "StatementAmount": [
      {
        "Amount": {
          "Amount": "400.00",
          "Currency": "GBP"
        },
		"CreditDebitIndicator": "Credit",        
		"Type": "ClosingBalance"        
      }, 
      {
        "Amount": {
          "Amount": "600.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "PreviousClosingBalance"
      }
      ]
    }, 
    {
      "AccountId": "22289",
      "StatementId": "34hj24u-324h33-31i3p4",
      "StatementReference": "003",
      "Type": "RegularPeriodic",
      "StartDateTime": "2017-09-01T00:00:00+00:00",
      "EndDateTime": "2017-09-30T23:59:59+00:00",
      "CreationDateTime": "2017-10-01T00:00:00+00:00",
      "StatementDescription": ["September 2017 Statement"],
      "StatementAmount": [
      {
        "Amount": {
          "Amount": "200.00",
          "Currency": "GBP"
        },
		"CreditDebitIndicator": "Credit",        
		"Type": "ClosingBalance"        
      }, 
      {
        "Amount": {
          "Amount": "400.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "PreviousClosingBalance"
      }
      ]
    }, 
    {
      "AccountId": "32389",
      "StatementId": "9034ee-4ewa4e-342er6",
      "StatementReference": "002",
      "Type": "RegularPeriodic",
      "StartDateTime": "2017-09-01T00:00:00+00:00",
      "EndDateTime": "2017-09-30T23:59:59+00:00",
      "CreationDateTime": "2017-10-01T00:00:00+00:00",
      "StatementAmount": [
      {
        "Amount": {
          "Amount": "2700.00",
          "Currency": "GBP"
        },
		"CreditDebitIndicator": "Credit",        
		"Type": "ClosingBalance"        
      }, 
      {
        "Amount": {
          "Amount": "4060.00",
          "Currency": "GBP"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "PreviousClosingBalance"
      }
      ]
    }
    ],
    "Links": {
      "Self": "https://api.alphabank.com/open-banking/v3.1/aisp/statements/"
    },
    "Meta": {
      "TotalPages": 1
    }
  }
}