Offers v2.0.0

Version Control

VersionDateAuthorComments
2.0-rc2Open Banking Read/Write API Team

This is the first Release Candidate with Split from One Page Specification

Updates:

  • More detail in the Resource Definition to differentiate with the products resource, and statements resource
  • More detail in how complex offer structure will be expressed - using the free-text Description field
  • Added the URL field
  • Updated payloads for usage examples
2.0-rc3 Open Banking Read/Write API Team

This is the initial version for release candidate 3.

Updates:

  • For consistency - made the OfferId 0..1 
  • For consistency - defined the pattern for the Rate field as per Open Data
  • Updated mandatory, conditional or optional as per Design Principles
2.0.0Open Banking Read/Write API TeamThis 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
1offersGETGET /accounts/{AccountId}/offersConditionalaccountsAuthorization Code


OBReadOffer1
2offersGETGET /offersOptionalaccountsAuthorization 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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadOffer1
OBReadOffer1
OBReadOffer1

Data1..1OBReadOffer1/Data
OBReadDataOffer1

Offer0..nOBReadOffer1/Data/Offer
OBOffer1

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

OfferId0..1OBReadOffer1/Data/Offer/OfferIdA unique and immutable identifier used to identify the offer resource. This identifier has no meaning to the account owner.Max40Text

OfferType0..1OBReadOffer1/Data/Offer/OfferTypeOffer type, in a coded form.OBExternalOfferType1CodeBalanceTransfer
LimitIncrease
MoneyTransfer
Other
PromotionalRate

Description0..1OBReadOffer1/Data/Offer/DescriptionFurther details of the offer.Max500Text

StartDateTime0..1OBReadOffer1/Data/Offer/StartDateTimeDate and time at which the offer starts.ISODateTime

EndDateTime0..1OBReadOffer1/Data/Offer/EndDateTimeDate and time at which the offer ends.ISODateTime

Amount0..1OBReadOffer1/Data/Offer/AmountAmount of money associated with the offer type.ActiveOrHistoricCurrencyAndAmount

Currency1..1OBReadOffer1/Data/Offer/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}$
Fee0..1OBReadOffer1/Data/Offer/FeeFee associated with the offer type.ActiveOrHistoricCurrencyAndAmount

Currency1..1OBReadOffer1/Data/Offer/Fee/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}$
Rate0..1OBReadOffer1/Data/Offer/RateRate associated with the offer type.Max10Text
^(-?\d{1,3}){1}(\.\d{1,4}){0,1}$
Value0..1OBReadOffer1/Data/Offer/ValueValue associated with the offer type.Number

Term0..1OBReadOffer1/Data/Offer/TermFurther details of the term of the offer.Max500Text

URL0..1OBReadOffer1/Data/Offer/URLURL (Uniform Resource Locator) where the document can be foundMax256Text

Enumerations

This section gives the definitions for enumerations used.

Code ClassName Definition 
OBExternalOfferType1Code

BalanceTransfer

Offer is a balance transfer.
OBExternalOfferType1Code

LimitIncrease

Offer is a limit increase.
OBExternalOfferType1Code

MoneyTransfer

Offer is a money transfer.
OBExternalOfferType1CodeOtherOffer is of an other type.
OBExternalOfferType1Code

PromotionalRate

Offer is a promotional rate.

Usage Examples

Specific Account

Request

Get Offers 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

Get Offers 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 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

Get Offers 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
  }
}