Offers v2.3.0

Owned by Matthew Bell
Jun 23, 2022
4 min read

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020 

@Gavin Wong (Unlicensed)

Updated:

  • Usage Example version from v2.0 to v2.1

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 not be available via the offers 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 Customers in the existing API Provider online channel).

An account (AccountId) may have no offers available, or may have multiple offers available.

Endpoints

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

offers

GET /accounts/{AccountId}/offers

Optional

accounts

Redirect Flow; or

Decoupled Flow

No





OBReadOffer1

offers

GET /offers

Optional

accounts

Redirect Flow; or

Decoupled Flow

No

Pagination



OBReadOffer1

GET /accounts/{AccountId}/offers

The API endpoint allows a Third Party to retrieve the offers for a specific account identified by AccountId.

  • The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 

GET /offers

The API endpoint allows a Third Party to retrieve offers in bulk, if an API Provider has implemented the bulk retrieval endpoints.

  • The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 

  • This will retrieve the offers for all accounts linked to the account-access-consent.

Data Model

The OBReadOffer1 object will be used for the call to: 

  • GET /accounts/{AccountId}/offers

  • GET /offers

UML Diagram

Notes

  • Offers (or promotions) for a specific AccountId, which may be viewable in the API Provider 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 API Provider must use the Description field to describe the nature of the offer in free-text

Permission Codes

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

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

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





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





Fee

0..1

OBReadOffer1/Data/Offer/Fee

Fee associated with the offer type.

OBActiveOrHistoricCurrencyAndAmount





Amount

1..1

OBReadOffer1/Data/Offer/Fee/Amount

A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.

ActiveCurrencyAndAmount_SimpleType

^\d{1,13}\.\d{1,5}$



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}$



Amount

0..1

OBReadOffer1/Data/Offer/Amount

Amount of money associated with the offer type.

OBActiveOrHistoricCurrencyAndAmount





Amount

1..1

OBReadOffer1/Data/Offer/Amount/Amount

A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.

ActiveCurrencyAndAmount_SimpleType

^\d{1,13}\.\d{1,5}$



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}$



Enumerations

This section gives the definitions for enumerations used.

Code Class

Name 

Definition 

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

Retrieving offers for a specific account.

Request

Get Offers Request

GET /accounts/22289/offers HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-auth-date: 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": "NZD" } }, { "AccountId": "22289", "OfferId": "Offer2", "OfferType": "BalanceTransfer", "Description": "Balance transfer offer up to $2000", "Amount": { "Amount": "2000.00", "Currency": "NZD" } } ] }, "Links": { "Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/accounts/22289/offers" }, "Meta": { "TotalPages": 1 } }

Bulk

Retrieving offers for all accounts linked to the account-access-consent.

Request

Get Offers Request

GET /offers HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-auth-date: 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