Versions Compared

Key

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


Page Properties
hiddentrue


Resourceproducts
Endpoints

GET /accounts/{AccountId}/product

GET /products

Mandatory?

Conditional

Optional

SortOrder08


Table of Contents
outlinetrue
stylenone

Version Control

VersionDateAuthorComments
3.0-draft118-Apr-2018OB R/W API TeamInitial draft for Version 3.0
3.0-draft4 OB R/W API TeamClarified use of Idempotency Key in endpoint table.
3.0-draft5 OB R/W API TeamUpdated examples to change UTC to GMT to be in line with https://tools.ietf.org/html/rfc7231#page-66
3.0-draft6/rc1 OB R/W API Team

Draft6 Changes:

  • For consistency - added a Permission Codes section to clarify expected behaviour.
3.0-draft7 OB R/W API TeamNo Change
3.0-RC2 OB R/W API Team

RC2 changes:

  • Added appropriate constraints to Data Model
3.0-RC3 OB R/W API Team

Updated fields lengths to align with Open Data standard:

  • MarketingStateId to Max35Text (without a reg-ex)
  • ProductName to Max350Text
    • OtherProductType/Name
    to Max350Text
    • to Max350Text3.
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.

Endpoints

Endpoints for the resource - and available methods.


ResourceHTTP OperationEndpointMandatory?ScopeGrant TypeIdempotency KeyParametersRequest ObjectResponse Object
1productsGETGET /accounts/{AccountId}/productConditionalaccountsAuthorization CodeNo

OBReadProduct2
2productsGETGET /productsOptionalaccountsAuthorization CodeNoPagination
OBReadProduct2


GET /accounts/{AccountId}/product

An AISP may retrieve the account product information for a specific AccountId (which is retrieved in the call to GET /accounts).

While this endpoint is marked as Conditional, it will be Mandatory for ASPSPs and account types covered in the CMA Order.

GET /products

If an ASPSP has implemented the bulk retrieval endpoints for products - an AISP may optionally retrieve the products information in bulk.

This endpoint will retrieve the products resources for all authorised accounts linked to a specific account-request.

Data Model

The OBReadProduct2 object will be used for the call to: 

  • GET /accounts/{AccountId}/product
  • GET /products

Resource Definition

A resource that contains a set of elements that describes the product details specific to the account (AccountId) - which will include any pricing, fees, interest rates and product features for the account.

An account (AccountId) must only have a single product.

Notes:

  • The product resource must be available for all PSD2 in scope accounts (if the product information is also available to the logged in PSU)
  • Detailed product information is only available for BCA and PCA products
  • High level product information for other products (other than BCA and PCA products) may be available via a reference to the Open Data APIs

UML Diagram

Notes:

  • All PSD2 in-scope accounts are expected to return a response to the product resource. However, the BCA and PCA objects only apply to current account products (which are a CMA Order requirement).
  • Product/ProductIdentifier and Product/SecondaryProductIdentifier are renamed to Product/ProductId and Product/SecondaryProductId respectively
  • The APIs are split in to 2 broad groups based on respective security requirements:-

    • Open Data includes an API which provides Marketed PCA/BCA/Other Information

    • Read-Write (aka “Closed Data”) includes an API which provides Operated PCA/BCA/Other Information.

  • Open Data Product information covers:- Core Product, Eligibility, Credit Interest, Overdraft, Features & Benefits, Other Fees & Charges

  • In July 2017, as part of Open Data-Account Information design workshop, it was agreed that the Products endpoint should contain a reference to Open Data AND subset of Open Data model (Decision 039 – option 4)
  • Approach to supplying product information via the Account and Transaction Information API for v2.x:
    • An optional “Open Data Product ID” link to the Open Data APIs should be retained, so that marketed product information is made available where this is available (this could be more than “Front book” if a bank has decided to retain marketed product information for “Back book” products on the Open Data API.
    • In addition to the “Open Data Product ID” link, we should focus on fields that are provided by price comparison websites today. Although overdraft rates are typically marked as “Negotiable” on PCWs, we feel that it would be useful to provide information about the actual overdraft rate(s) that the account holder is on, even if this cannot easily be used for comparison with other products.
    • If there is a reference to “Open Data Product ID”, then TPP may lookup product features from Open Data. If any element/field of products endpoint are populated, then this should override the default in Open Data (Decision 039 & 100). 
    • The “Open Data Product ID” should be populated by the ASPSP in the products resource if there is a corresponding entry in the Open Data APIs
    • Information supplied in the Account and Transaction Information API v2.x product section must come from account operating platforms.
    • ProductType enumeration matches to types available in Open Data APIs, and ASPSPs may chose to provide any additional product type by closing value=Other in ProductType, and providing a brief type details in OtherProductType data fields, and reference to their Open Data product. At this moment, we don't have detailed Product Info structure for product types other than PCA/BCA.

Permission Codes

The resource requires the ReadProducts permission. The resource response payload does not differ depending on the permissions granted.

Data Dictionary

Common Payload

Data Dictionary for Common Payload between PCA, BCA and other product types.

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadProduct2
OBReadProduct2
OBReadProduct2

Data1..1OBReadProduct2/Data
OBReadDataProduct2

Product0..nOBReadProduct2/Data/Product
OBProduct2

ProductName0..1OBReadProduct2/Data/Product/ProductNameThe name of the product used for marketing purposes from a customer perspective. I.e. what the customer would recognise.Max350Text

ProductId0..1OBReadProduct2/Data/Product/ProductIdIdentifier within the parent organisation for the product. Must be unique in the organisation.Max40Text

AccountId1..1OBReadProduct2/Data/Product/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

SecondaryProductId0..1OBReadProduct2/Data/Product/SecondaryProductIdIdentifier within the parent organisation for the product. Must be unique in the organisation.Max70Text

ProductType1..1OBReadProduct2/Data/Product/ProductTypeDescriptive code for the product category.
If ProductType - "Other" is chosen, the object OtherProductType must be populated with name, and description for the ASPSP's 
OBExternalProductType1Code

PersonalCurrentAccount

BusinessCurrentAccount

CommercialCreditCard

SMELoan

Other


MarketingStateId

0..1

OBReadProduct2/Data/Product/MarketingStateId

Unique and unambiguous identification of a Product Marketing State.

Max35Text



OtherProductType0..1OBReadProduct2/Data/Product/OtherProductType

This field provides extension to the ProductType enumeration.

If ProductType - "Other" is chosen, this field must be populated with name, and description for ASPSP specific product type

OB_OtherProductType1

Name1..1OBReadProduct2/Data/Product/OtherProductType/Name
Max350Text

Description1..1OBReadProduct2/Data/Product/OtherProductType/Description
Max350Text

PCA

0..1

OBReadProduct2/Data/Product/PCA


OBPCAData1



BCA0..1OBReadProduct2/Data/Product/BCA
OBBCAData1

PCA & BCA Extensions

Child pages (Children Display)
styleh4

Usage Examples

Detailed usage examples for PCA, and BCA can be found in the Message Implementation Guide section of PCA and BCA sub pages.

Specific Account

Request

Code Block
languagejs
themeMidnight
titleGet Accounts Product Request
linenumberstrue
GET /accounts/22289/product HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  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


Response

Code Block
languagejs
themeMidnight
titleGet Accounts Product Response
linenumberstrue
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Product": [
      {
        "AccountId": "22289",
        "ProductId": "51B",
        "ProductType": "PersonalCurrentAccount",
        "ProductName": "321 Product",
        "PCA": {
         .... 
		} 
	  }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v2.0/accounts/22289/product"
  },
  "Meta": {
    "TotalPages": 1
  }
}



Bulk

Request

Code Block
languagejs
themeMidnight
titleGet Products Request
linenumberstrue
GET /products HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  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


Response

Code Block
languagejs
themeMidnight
titleGet Products Response
linenumberstrue
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Product": [
      {
        "AccountId": "22289",
        "ProductId": "51B",
        "ProductType": "PersonalCurrentAccount",
        "ProductName": "321 Product",
        "PCA": { .. } 
      },
      {
        "AccountId": "31820",
        "ProductId": "001",
        "ProductType": "BusinessCurrentAccount",
        "ProductName": "123 Product",
        "BCA": { .. } 
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v2.0/products/"
  },
  "Meta": {
    "TotalPages": 1
  }
}