/
Offers v3.0.1

Offers v3.0.1

Version Control

 

Version

Date

Author

Comments

Version

Date

Author

Comments

3.0.0-draft1

May 3, 2022

Payments NZ API Working Group

Baseline

3.0.0-draft1

 

 

Jun 26, 2022

 

 

@Gavin Wong (Unlicensed)

 

Updates to Accounts:

 

3.0.0-draft2

Jan 17, 2023

@Nigel Somerfield

Baseline for v3.0.0-draft2

3.0.0-draft2

Apr 6, 2023

@Nigel Somerfield

Updated length of resource Id fields from 40 to 128 characters as agreed in https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1610940428

3.0.0-rc1

May 5, 2023

@Nigel Somerfield

Baselined for release candidate 1

Updated PhoneNumber (used in Phone and Mobile date fields) regular expression as per https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1616445441

3.0.0-rc1

Jun 16, 2023

@Nigel Somerfield

Corrected Account examples to match the enumerated values for AccountSubType

3.0.0-rc2

Sep 12, 2023

@Nigel Somerfield

Baseline for v3.0.0-rc2

3.0.0-rc2

Sep 25, 2023

@Nigel Somerfield

Updated:

  • Transactions link to ISO External Code Sets (used in BankTransactionCode)

  • Filtering guidance when filter dates partially overlap consent transaction date range

3.0.0-rc2

Oct 9, 2023

@Nigel Somerfield

Updated:

3.0.0

Nov 13, 2023

@Nigel Somerfield

Version 3.0.0 baseline release

3.0.0

Jan 31, 2024

@Nigel Somerfield

Updated to reflect OpenAPI release in Github (pull request merge)

3.0.1

Jun 6, 2024

@Nigel Somerfield

Patch update to clarify the explanation of BookingDateTime:

  • The BookingDateTime is the date the transaction is booked (or posted)
    and becomes immutable - which is not the date the transaction took place

was replaced with:

  • The BookingDateTime is the date the transaction is booked (or posted)
    and becomes immutable - which is not necessarily the date the transaction
    took place

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.

Max128Text





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.

Max128Text





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

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" } }, { "AccountId": "32515", "OfferId": "Offer3", "OfferType": "LimitIncrease", "Description": "Credit limit increase for the account up to $50000.00", "Amount": { "Amount": "50000.00", "Currency": "NZD" } } ] }, "Links": { "Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/offers" }, "Meta": { "TotalPages": 1 } }