Offers v2.0.0
Version Control
Version | Date | Author | Comments |
---|---|---|---|
2.0-rc2 | Open Banking Read/Write API Team | This is the first Release Candidate with Split from One Page Specification Updates:
| |
2.0-rc3 | Open Banking Read/Write API Team | This is the initial version for release candidate 3. Updates:
| |
2.0.0 | Open Banking Read/Write API Team | This is the baseline version. No changes from v2.0-rc3. |
Endpoints
Endpoints for the resource - and available methods.
Resource | HTTP Operation | Endpoint | Mandatory? | Scope | Grant Type | Idempotent | Parameters | Request Object | Response Object | |
---|---|---|---|---|---|---|---|---|---|---|
1 | offers | GET | GET /accounts/{AccountId}/offers | Conditional | accounts | Authorization Code | OBReadOffer1 | |||
2 | offers | GET | GET /offers | Optional | accounts | Authorization Code | Pagination | OBReadOffer1 |
GET /accounts/{AccountId}/offers
An AISP may retrieve the offers resource for a specific AccountId (which is retrieved in the call to GET /accounts).
GET /offers
If an ASPSP has implemented the bulk retrieval endpoints - an AISP may optionally retrieve the offers in bulk.
This will retrieve the resources for all authorised accounts linked to the account-request.
Data Model
The OBReadOffer1 object will be used for the call to:
- GET /accounts/{AccountId}/offers
- GET /offers
Resource Definition
A resource that contains a set of elements that describes the list of offers available to a specific account (AccountId).
- Generic features (and pricing) for the account product will be not be available via the offers resources. These generic features will be available via the product resource.
- The outcome of any offer (or product feature) uptake will not be reported via the offers resource. The benefits, interest, cash-back for any account will be available via the statements resource (if this is available to PSUs in the existing ASPSP online channel).
An account (AccountId) may have no offers available, or may have multiple offers available.
UML Diagram
Notes:
- Offers (or promotions) for a specific AccountId, which may be viewable in the ASPSP online banking interface, may have a complicated offer structure (which cannot be expressed using a flat Amount, Fee, Rate, or Value structure). In this case, the ASPSP must use the Description field to describe the nature of the offer in free-text
Data Dictionary
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBReadOffer1 | OBReadOffer1 | OBReadOffer1 | ||||
Data | 1..1 | OBReadOffer1/Data | OBReadDataOffer1 | |||
Offer | 0..n | OBReadOffer1/Data/Offer | OBOffer1 | |||
AccountId | 1..1 | OBReadOffer1/Data/Offer/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
OfferId | 0..1 | OBReadOffer1/Data/Offer/OfferId | A unique and immutable identifier used to identify the offer resource. This identifier has no meaning to the account owner. | Max40Text | ||
OfferType | 0..1 | OBReadOffer1/Data/Offer/OfferType | Offer type, in a coded form. | OBExternalOfferType1Code | BalanceTransfer LimitIncrease MoneyTransfer Other PromotionalRate | |
Description | 0..1 | OBReadOffer1/Data/Offer/Description | Further details of the offer. | Max500Text | ||
StartDateTime | 0..1 | OBReadOffer1/Data/Offer/StartDateTime | Date and time at which the offer starts. | ISODateTime | ||
EndDateTime | 0..1 | OBReadOffer1/Data/Offer/EndDateTime | Date and time at which the offer ends. | ISODateTime | ||
Amount | 0..1 | OBReadOffer1/Data/Offer/Amount | Amount of money associated with the offer type. | ActiveOrHistoricCurrencyAndAmount | ||
Currency | 1..1 | OBReadOffer1/Data/Offer/Amount/Currency | A 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}$ | |
Fee | 0..1 | OBReadOffer1/Data/Offer/Fee | Fee associated with the offer type. | ActiveOrHistoricCurrencyAndAmount | ||
Currency | 1..1 | OBReadOffer1/Data/Offer/Fee/Currency | A 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}$ | |
Rate | 0..1 | OBReadOffer1/Data/Offer/Rate | Rate associated with the offer type. | Max10Text | ^(-?\d{1,3}){1}(\.\d{1,4}){0,1}$ | |
Value | 0..1 | OBReadOffer1/Data/Offer/Value | Value associated with the offer type. | Number | ||
Term | 0..1 | OBReadOffer1/Data/Offer/Term | Further details of the term of the offer. | Max500Text | ||
URL | 0..1 | OBReadOffer1/Data/Offer/URL | URL (Uniform Resource Locator) where the document can be found | Max256Text |
Enumerations
This section gives the definitions for enumerations used.
Code Class | Name | Definition |
---|---|---|
OBExternalOfferType1Code | BalanceTransfer | Offer is a balance transfer. |
OBExternalOfferType1Code | LimitIncrease | Offer is a limit increase. |
OBExternalOfferType1Code | MoneyTransfer | Offer is a money transfer. |
OBExternalOfferType1Code | Other | Offer is of an other type. |
OBExternalOfferType1Code | PromotionalRate | Offer is a promotional rate. |
Usage Examples
Specific Account
Request
GET /accounts/22289/offers 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 UTC x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json
Response
HTTP/1.1 200 OK x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Content-Type: application/json { "Data": { "Offers": [ { "AccountId": "22289", "OfferId": "Offer1", "OfferType": "LimitIncrease", "Description": "Credit limit increase for the account up to £10000.00", "Amount": { "Amount": "10000.00", "Currency": "GBP" } }, { "AccountId": "22289", "OfferId": "Offer2", "OfferType": "BalanceTransfer", "Description": "Balance transfer offer up to £2000", "Amount": { "Amount": "2000.00", "Currency": "GBP" } } ] }, "Links": { "Self": "https://api.alphabank.com/open-banking/v2.0/accounts/22289/offers/" }, "Meta": { "TotalPages": 1 } }
Bulk
Request
GET /offers 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 UTC x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json
Response
HTTP/1.1 200 OK x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Content-Type: application/json { "Data": { "Offers": [ { "AccountId": "22289", "OfferId": "Offer1", "OfferType": "LimitIncrease", "Description": "Credit limit increase for the account up to £10000.00", "Amount": { "Amount": "10000.00", "Currency": "GBP" } }, { "AccountId": "22289", "OfferId": "Offer2", "OfferType": "BalanceTransfer", "Description": "Balance transfer offer up to £2000", "Amount": { "Amount": "2000.00", "Currency": "GBP" } }, { "AccountId": "32515", "OfferId": "Offer3", "OfferType": "LimitIncrease", "Description": "Credit limit increase for the account up to £50000.00", "Amount": { "Amount": "50000.00", "Currency": "GBP" } } ] }, "Links": { "Self": "https://api.alphabank.com/open-banking/v2.0/offers/" }, "Meta": { "TotalPages": 1 } }
© Open Banking Limited 2019 | https://www.openbanking.org.uk/open-licence | https://www.openbanking.org.uk