Products v3.1

Version Control

VersionDateAuthorComments
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.
3.1-draft1 OB R/W API Team

This is the initial draft version for 3.1

Errata

  • Grammatical Fixes
3.1-draft2 OB R/W API Team

Draft2 Changes:

  • Updated example URLs to version 3.1.
3.1-draft3OB R/W API Team

Draft3 Changes

Errata

  • Typo in class name for Product/OtherProductType
3.1OB R/W API Team

Version 3.1 final release.

No changes from Version 3.1 RC1.

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 and 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 the TPP may lookup product features from Open Data. If any element/fields of the 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, ASPSPs may choose 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



Data

1..1

OBReadProduct2/Data


OBReadDataProduct2



Product

0..n

OBReadProduct2/Data/Product


OBProduct2



ProductName

0..1

OBReadProduct2/Data/Product/ProductName

The name of the product used for marketing purposes from a customer perspective. I.e. what the customer would recognise.

Max350Text



ProductId

0..1

OBReadProduct2/Data/Product/ProductId

Identifier within the parent organisation for the product. Must be unique in the organisation.

Max40Text



AccountId

1..1

OBReadProduct2/Data/Product/AccountId

A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.

Max40Text



SecondaryProductId

0..1

OBReadProduct2/Data/Product/SecondaryProductId

Identifier within the parent organisation for the product. Must be unique in the organisation.

Max70Text



ProductType

0..1

OBReadProduct2/Data/Product/ProductType

Descriptive code for the product category.

If ProductType - "Other" is chosen, the object OtherProductType must be populated with name, and description.

OBExternalProductType1Code

BusinessCurrentAccount

CommercialCreditCard

Other

PersonalCurrentAccount

SMELoan


MarketingStateId

0..1

OBReadProduct2/Data/Product/MarketingStateId

Unique and unambiguous identification of a Product Marketing State.

Max35Text



OtherProductType

0..1

OBReadProduct2/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.

OBOtherProductType1



Name

1..1

OBReadProduct2/Data/Product/OtherProductType/Name

Name of "Other" product type.

Max350Text



Description

1..1

OBReadProduct2/Data/Product/OtherProductType/Description

Description of "Other" product type.

Max350Text



BCA

0..1

OBReadProduct2/Data/Product/BCA


OBBCAData1



PCA

0..1

OBReadProduct2/Data/Product/PCA


OBPCAData1



PCA & BCA Extensions

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

Get Accounts Product Request
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

Get Accounts Product Response
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/v3.1/aisp/accounts/22289/product"
  },
  "Meta": {
    "TotalPages": 1
  }
}


Bulk

Request

Get Products Request
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

Get Products Response
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/v3.1/aisp/products/"
  },
  "Meta": {
    "TotalPages": 1
  }
}