Versions Compared

Old Version 2

changes.mady.by.user Freddi Gyara

Saved on

compared with

New Version Current

changes.mady.by.user Freddi Gyara

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
outlinetrue
stylenone

...

VersionDateAuthorComments
3.0-draft118-Apr-2018OB R/W API Team

Initial draft for Version 3.0

  • Consolidated enumerations from child pages in Data Model / Enumerations
  • Removed Overview/Scope and Overview/Out of Scope sections
3.0-draft318-May-2018OB R/W API Team

Renamed "Account Request" to "Account Access Consent"

renamed AccountRequestId to ConsentId

In Endpoint section - removed reference to "must respond with a 404 (Not Found) for requests to that URL." and moved to Read Write API page.

3.0-draft4 OB R/W API Team

Draft4 changes:

  • Spelling errors
  • Clarified with sending the Basic permission and Detail permission together that "While it is duplication for a TPP to request a "Basic" permission code and the corresponding "Detail" permission code, it is not a malformed request, and the ASPSP must not reject solely on the basis of duplication."
  • Changed guidance to "The permissions array must contain at least ReadAccountsBasic or ReadAccountsDetail."

3.0-draft5

 OB R/W API Team

Errata:

  • Spelling errors
  • Removed reference to a non-existent section "- which is clarified in the "RTS and SCA Exemptions" section"
  • Updated Consent Elements/Permissions section to reflect /accounts/{AccountId}/statements/{StatementId}/transactions endpoint behaviour is also under control of ReadTransactions* permissions
  • Updated ISO 20022 OBAddressTypeCode code from "DeliverTo" to "DeliveryTo"

Draft5 changes:

  • Included status values in overview sequence diagram.
  • Enumeration definitions updated for:
    • Balance/Type - InterimCleared, OpeningCleared, ClosingCleared
    • StatementAmount/Type - PendingTransactionsBalance
    • StatementFee/Type - ForeignCashTransaction
    • CardInstrument/AuthorisationType - ConsumerDevice
3.0-draft6 OB R/W API Team
  • Fixed incorrect reference to v2.0 in introduction.
  • Added Release Management in Basics section
3.0-draft7 OB R/W API Team

Errata:

  • In the Release Management Section, GET account-access consent updated:

An AISP must not access a Consent on a newer older version, via a ConsentId created in a previous newer version

E.g., Consent created in v3 accessed via v2 account-request"

Updates:

  • Incorporated Decision: 159. Name-spaced enumeration for following types:
    • OBReadStatement1/Data/Statement/StatementBenefit/Type
    • OBReadStatement1/Data/Statement/StatementFee/Type
    • OBReadStatement1/Data/Statement/StatementInterest/Type
    • OBReadStatement1/Data/Statement/StatementAmount/Type
    • OBReadStatement1/Data/Statement/StatementDateTime/Type
    • OBReadStatement1/Data/Statement/StatementRate/Type
    • OBReadStatement1/Data/Statement/StatementValue/Type
3.0-RC2 OB R/W API Team

Errata:

  • In the Release Management Section, DELETE account-access consent updated.
  • In the Release Management Section, GET account-access consent updated (token rule not relevant as resource protected with client credentials).

Updates:

  • Changes to cater for CIBA
    • Modified Basics / Overview / Steps
    • Added  alternative Sequence Diagram for Decoupled Flow
    • Updated Grant Types
  • Consistent language across the Release Management section.
  • Added Swagger specification.
3.0-RC3 OB R/W API Team

Added a section on Security / Consent Authorisation / Consent Re-authentication to clarify that PSUs can be re-authenticated as per definitions in the root document.

Updated Security / Consent Authorisation / Changes to Selected Accounts to reflect that selected accounts may change at the point of re-authentication

Updated references to consent "re-authorisation" to consent "re-authentication"

Added Swagger-based API specification files encoded in JSON and YAML.

3.0 OB R/W API Team

This is the baseline version. No change from RC3.

Swagger URLs updated to point to latest stable version.

Overview

This specification describes the Account Information and Transaction API flows and payloads.

...

GET

  • An AISP must not access a Consent on an older version, via the Id for a Consent created in a newer version
    • E.g., An account-access-consent created in v3 accessed via v2 account-request
  • An ASPSP must allow a Consent to be accessed in a newer version
  • An ASPSP must ensure Permissions set associated with a Consent are unchanged when accessed in a different version
    • E.g., An account-request created in v2 will have the same details when accessed via v2 and v3 (as an account-access-consent)
  • An ASPSP must ensure a Consent's fields are unchanged when accessed in a different version
  • An ASPSP may allow expired Consents to be accessed in a newer version
  • An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all (if not mandatory)
    • E.g., OBReadResponse1/Data/StatusUpdateDateTime introduced in v2 accessed with v1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records

...

Account Information Resources

GET

  • An AISP may use a token that is bound to a Consent in a previous version, to access an endpoint of a newer version
  • An AISP may use an Id for a Consent created in a previous version to retrieve Account Information resources in a newer version
    • E.g., AccountRequestId from v2 can be used as ConsentId in v3, to GET /accounts
  • An AISP must not use an Id for a Consent from a newer version to access Account Information resources in a previous version
    • E.g., ConsentId for an account-access-consent created in v3, must not be used to access v2 Account Information endpoints
  • An AISP must not use an Id for a Consent from a previous version to access a resource introduced in a newer version (as the Consent will not have Permissions required to access the new resource)
  • An ASPSP must allow an AISP to use an Id for a Consent from a previous version to access Account Information resource endpoints in a newer version
    • E.g., AccountRequestId created in v2 must be allowed to access Account Information resource endpoints in v3
  • An ASPSP must reject the request to access a resource, for which a Consent's Permissions set doesn't permit
  • An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all
    • E.g., OBReadResponse1/Data/StatusUpdateDateTime introduced in Version2 accessed with V1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records

...

PermissionsEndpointsBusiness LogicData Cluster Description
ReadAccountsBasic

/accounts

/accounts/{AccountId}


Ability to read basic account information
ReadAccountsDetail

/accounts

/accounts/{AccountId}

Access to additional elements in the payloadAbility to read account identification details
ReadBalances

/balances

/accounts/{AccountId}/balances


Ability to read all balance information
ReadBeneficiariesBasic

/beneficiaries

/accounts/{AccountId}/beneficiaries


Ability to read basic beneficiary details
ReadBeneficiariesDetail

/beneficiaries

/accounts/{AccountId}/beneficiaries

Access to additional elements in the payloadAbility to read account identification details for the beneficiary
ReadDirectDebits

/direct-debits

/accounts/{AccountId}/direct-debits


Ability to read all direct debit information
ReadStandingOrdersBasic

/standing-orders

/accounts/{AccountId}/standing-orders


Ability to read basic standing order information
ReadStandingOrdersDetail

/standing-orders

/accounts/{AccountId}/standing-orders

Access to additional elements in the payloadAbility to read account identification details for beneficiary of the standing order
ReadTransactionsBasic

/transactions

/accounts/{AccountId}/transactions

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

Permissions must also include at least one of:

  • ReadTransactionsCredits
  • ReadTransactionsDebits

Ability to read basic transaction information

ReadTransactionsDetail

/transactions

/accounts/{AccountId}/transactions

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

Access to additional elements in the payload

Permissions must also include at least one of

  • ReadTransactionsCredits
  • ReadTransactionsDebits

Ability to read transaction data elements which may hold silent party details

ReadTransactionsCredits

/transactions

/accounts/{AccountId}/transactions

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

Access to credit transactions.

Permissions must also include one of:

  • ReadTransactionsBasic
  • ReadTransactionsDetail
Ability to read only credit transactions
ReadTransactionsDebits

/transactions

/accounts/{AccountId}/transactions

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

Access to debit transactions.

Permissions must also includeone of:

  • ReadTransactionsBasic
  • ReadTransactionsDetail
Ability to read only debit transactions
ReadStatementsBasic

/statements

/accounts/{AccountId}/statements


Ability to read basic statement details
ReadStatementsDetail

/statements

/accounts/{AccountId}/statements

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

Access to additional elements in the payload

Access to download the statement file (if the ASPSP makes this available).

Ability to read statement data elements which may leak other information about the account
ReadProducts

/products

/accounts/{AccountId}/product


Ability to read all product information relating to the account
ReadOffers

/offers

/accounts/{AccountId}/offers


Ability to read all offer information
ReadParty/accounts/{AccountId}/party
Ability to read party information on the account owner.
ReadPartyPSU/party
Ability to read party information on the PSU logged in.
ReadScheduledPaymentsBasic

/scheduled-payments

/accounts/{AccountId}/scheduled-payments


Ability to read basic statement details
ReadScheduledPaymentsDetail

/scheduled-payments

/accounts/{AccountId}/scheduled-payments

Access to additional elements in the payload
ReadPANAll API endpoints where PAN is available as a structured fieldRequest to access to PAN in the clear

Request to access PAN in the clear across the available endpoints. 

If this permission code is not in the account-access-consent, the AISP will receive a masked PAN.

While an AISP may request to access PAN in the clear, an ASPSP may still respond with a masked PAN if:

  • The ASPSP does not display PAN in the clear in existing online channels
  • The ASPSP takes a legal view to respond with only the masked PAN

...

Permission - Detail CodesData Element NameOccurrenceXPath
ReadAccountsDetailAccount0..1OBReadAccount2/Data/Account/Account
ReadAccountsDetailServicer0..1OBReadAccount2/Data/Account/Servicer
ReadBeneficiariesDetailCreditorAgent0..1OBReadBeneficiary2/Data/Beneficiary/CreditorAgent
ReadBeneficiariesDetailCreditorAccount0..1OBReadBeneficiary2/Data/Beneficiary/CreditorAccount
ReadStandingOrdersDetailCreditorAgent0..1OBReadStandingOrder3/Data/StandingOrder/CreditorAgent
ReadStandingOrdersDetailCreditorAccount0..1OBReadStandingOrder3/Data/StandingOrder/CreditorAccount
ReadTransactionsDetailTransactionInformation0..1OBReadTransaction3/Data/Transaction/TransactionInformation
ReadTransactionsDetailBalance0..1OBReadTransaction3/Data/Transaction/Balance
ReadTransactionsDetailMerchantDetails0..1OBReadTransaction3/Data/Transaction/MerchantDetails
ReadTransactionsDetailCreditorAccount0..1

OBReadTransaction3/Data/Transaction/CreditorAccount

ReadTransactionsDetailDebtorAccount0..1OBReadTransaction3/Data/Transaction/DebtorAccount
ReadStatementsDetailStatementAmount0..*OBReadStatement1/Data/Statement/StatementAmount
ReadScheduledPaymentsDetailCreditorAgent0..1OBReadScheduledPayment1/Data/ScheduledPayment/CreditorAgent
ReadScheduledPaymentsDetailCreditorAccount0..1OBReadScheduledPayment1/Data/ScheduledPayment/CreditorAccount

In addition the ReadStatementsDetail is required to access the statement file download via: /accounts/{AccountId}/statements/{StatementId}/file

...

  • The camt.052 header section and trailer sections have been removed - as these are not required for a RESTful API
  • Resources have been identified, and payload structures have been designed for these resources - rather than a full message (i.e., camt.052) that encompasses all resources in a report format. This has meant we've designed separate endpoints and payloads to cover:
    • accounts
    • balances
    • beneficiaries
    • direct-debits
    • offers
    • party
    • products
    • standing-orders
    • statements
    • transactions
    • scheduled-payments
  • New payloads have been designed for beneficiaries, direct-debits, standing-orders, and products resources - as these are not in the ISO 20022 standard (or the camt.052 message)
  • A DateTime element has been used instead of a complex choice element of Date and DateTime (across all API endpoints). Where time elements do not exist in ASPSP systems - the expectation is the time portion of the DateTime element will be defaulted to 00:00:00+00:00
  • Variations for the accounts structure include: 
    • Standardised inline with the Payment API account structures
    • Contains elements to identify an account Nickname, SecondaryIdentification
  • Variations for the balances structure include:
    • Adding a Type into the CreditLine section - to allow for multiple credit line types affecting the available balance
    • DateTime element has been specified instead of a complex choice of Date and DateTime

  • Variations for the transactions structure include:

    • Renaming "entry" to "transaction" for consistency - as this is the language used in the CMA Order, and PSD2

    • DateTime elements used instead of a complex choice of Date and DateTime

    • Flattening of the structure for BankTransactionCode and ProprietaryBankTransactionCode

    • Additional information for an AddressLine, MerchantDetails, and a running Balance

...




OBExternalStatementAmountType1CodeUK.OBIE.ArrearsClosingBalanceThe balance that is in arrears at the end of the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.AvailableBalanceThe available balance is the difference between the credit limit and the account balance – how much is avaialble to spend.
OBExternalStatementAmountType1CodeUK.OBIE.AverageBalanceWhenInCreditThe average daily balance when the account is in crebit during the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.AverageBalanceWhenInDebitThe average daily balance when the account is in debit during the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.AverageDailyBalanceThe average daily balance during the statement period. An average daily balance adds the closing balances at the end of each day in a given period of time and divides the sum by the number of calendar days in that period.
OBExternalStatementAmountType1CodeUK.OBIE.BalanceTransferClosingBalanceThe component of balance that relates to balance transfers at the end of the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.CashClosingBalanceThe component of balance that relates to cash at the end of the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.ClosingBalanceThe ending balance or closing balance at the end of the current statement period.
OBExternalStatementAmountType1CodeUK.OBIE.CreditLimitThe credit limit is the total amount of credit available to a borrower, including any amount already borrowed.
OBExternalStatementAmountType1CodeUK.OBIE.CurrentPaymentThe total payments received since the last period.
OBExternalStatementAmountType1CodeUK.OBIE.DirectDebitPaymentDueThe total direct debit payments due for current statement period.
OBExternalStatementAmountType1CodeUK.OBIE.FSCSInsuranceThe amount under which the FSCS scheme will protect consumers when authorised financial services firms fail.
OBExternalStatementAmountType1CodeUK.OBIE.MinimumPaymentDueThe minimum payment required for the current statement period.
OBExternalStatementAmountType1CodeUK.OBIE.PendingTransactionsBalanceThe total pending transactions balance at the end of the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.PreviousClosingBalanceThe closing balance of the previous statement.
OBExternalStatementAmountType1CodeUK.OBIE.PreviousPaymentThe previous payment amount in the last statement period.
OBExternalStatementAmountType1CodeUK.OBIE.PurchaseClosingBalanceThe component of balance that relates to purchases at the end of the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.StartingBalanceThe new balance or starting balance carried forward since last statement period.
OBExternalStatementAmountType1CodeUK.OBIE.TotalAdjustmentsTotal adjustments to the account during the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.TotalCashAdvancesA cash advance is a short-term loan from a bank or alternative lender. The term also refers to a service provided by many credit card issuers allowing cardholders to withdraw a certain amount of cash. 
OBExternalStatementAmountType1CodeUK.OBIE.TotalChargesThe total charges including interest, late payment fee during the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.TotalCreditsTotal amount credited in the account during the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.TotalDebitsTotal amount debited (money taken out from account) from the account during the statement period.
OBExternalStatementAmountType1CodeUK.OBIE.TotalPurchasesThe total transactions made during that statement period.
OBExternalStatementBenefitType1CodeUK.OBIE.CashbackCash back amount received during the statement period.
OBExternalStatementBenefitType1CodeUK.OBIE.InsuranceInsurance amount during the statement period.
OBExternalStatementBenefitType1CodeUK.OBIE.TravelDiscountTrave discound amount received during the statement period.
OBExternalStatementBenefitType1CodeUK.OBIE.TravelInsuranceTravel insurance amount during the statement period.
OBExternalStatementDateTimeType1CodeUK.OBIE.BalanceTransferPromoEndThe date the balance transfer promo rate will end.
OBExternalStatementDateTimeType1CodeUK.OBIE.DirectDebitDueThe date that the direct debit payment is due for the current statement. 
OBExternalStatementDateTimeType1CodeUK.OBIE.LastPaymentThe date than an account holder must make the payment for the previous statement period. 
OBExternalStatementDateTimeType1CodeUK.OBIE.LastStatementThe date on which the last statement was made available to account holder.
OBExternalStatementDateTimeType1CodeUK.OBIE.NextStatementThe date on which the next statement will be made available to account holder.
OBExternalStatementDateTimeType1CodeUK.OBIE.PaymentDueThe date than an account holder must make the payment for the current statement period. 
OBExternalStatementDateTimeType1CodeUK.OBIE.PurchasePromoEndThe date the purchase promo rate will end.
OBExternalStatementDateTimeType1CodeUK.OBIE.StatementAvailableThe date on which the current statement was made available to account holder.
OBExternalStatementFeeType1CodeUK.OBIE.AnnualAnnual fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.BalanceTransferBalance transfer fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.CashAdvanceCash advance fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.CashTransactionCash transaction fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.ForeignCashTransactionForeign cash transaction fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.ForeignTransactionForeign transaction fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.GamblingGambling transaction fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.LatePaymentLate payment fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.MoneyTransferMoney transfer fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.MonthlyMonthly account fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.OverlimitOver limit fees charged during the statement period..
OBExternalStatementFeeType1CodeUK.OBIE.PostalOrderPostal order fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.PrizeEntryPrize entry fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.StatementCopyStatement copy fees charged during the statement period.
OBExternalStatementFeeType1CodeUK.OBIE.TotalTotal fees charges during the statement period.
OBExternalStatementInterestType1CodeUK.OBIE.BalanceTransferInterest on balance transfers.
OBExternalStatementInterestType1CodeUK.OBIE.CashInterest on cash advances.
OBExternalStatementInterestType1CodeUK.OBIE.EstimatedNextThe estimated interest that will be charged if the closing balance is not paid in full.
OBExternalStatementInterestType1CodeUK.OBIE.PurchaseInterest on purchases.
OBExternalStatementInterestType1CodeUK.OBIE.TotalTotal interest charges during the statement period.
OBExternalStatementRateType1CodeUK.OBIE.AnnualBalanceTransferAnnual interest rate charged on balance transfer from other service provider.
OBExternalStatementRateType1CodeUK.OBIE.AnnualBalanceTransferAfterPromoAnnual interest rate charged on balance transfer from other service provider after promotional period.
OBExternalStatementRateType1CodeUK.OBIE.AnnualBalanceTransferPromoAnnual interest rate charged on balance transfer from other service provider during promotional period.
OBExternalStatementRateType1CodeUK.OBIE.AnnualCashAnnual interest rate charged on cash advance.
OBExternalStatementRateType1CodeUK.OBIE.AnnualPurchaseAnnual interest rate charged on purchases.
OBExternalStatementRateType1CodeUK.OBIE.AnnualPurchaseAfterPromoAnnual interest rate charged on purchases from after promotional period.
OBExternalStatementRateType1CodeUK.OBIE.AnnualPurchasePromoAnnual interest rate charged on purchases from during promotional period.
OBExternalStatementRateType1CodeUK.OBIE.MonthlyBalanceTransferMonthly interest rate charged on balance transfer from other service provider.
OBExternalStatementRateType1CodeUK.OBIE.MonthlyCashMonthly interest rate charged on cash advance.
OBExternalStatementRateType1CodeUK.OBIE.MonthlyPurchaseMonthly interest rate charged on purchases.
OBExternalStatementValueType1CodeUK.OBIE.AirMilesPointsAir miles points at the end of the statement period.
OBExternalStatementValueType1CodeUK.OBIE.AirMilesPointsBalanceAir miles points at the end of the statement period.
OBExternalStatementValueType1CodeUK.OBIE.CreditsTotal number of credits in statement period.
OBExternalStatementValueType1CodeUK.OBIE.DebitsTotal number of debits in statement period.
OBExternalStatementValueType1CodeUK.OBIE.HotelPointsHotel points at the end of the statement period.
OBExternalStatementValueType1CodeUK.OBIE.HotelPointsBalanceHotel points at the end of the statement period.
OBExternalStatementValueType1CodeUK.OBIE.RetailShoppingPointsRetail shopping points at the end of the statement period.
OBExternalStatementValueType1CodeUK.OBIE.RetailShoppingPointsBalanceRetail shopping points at the end of the statement period.

...

The Swagger Specification for Account Information APIs can be downloaded from the following links: