Version Control
Version | Date | Author | Comments |
|---|---|---|---|
2.0.0 | Payments NZ API Working Group | Baseline | |
2.1-draft1 |
| Updated:
Removed:
| |
2.1-rc2 | Updated:
| ||
2.2-draft1 | Updated:
| ||
2.3.1 | Patch update to Swagger specification to BECSRemittance - DebtorReference and CreditorReference - specify | ||
2.3.2 |
| Patch update to Swagger to reflect /wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1455358006, which determined that the standard error response body should be included in all non-success HTTP responses. | |
2.3.3 |
| Patch update to clarify the explanation of BookingDateTime:
was replaced with:
|
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 |
|---|---|---|---|---|---|---|---|---|
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 |
|---|---|---|---|---|---|---|
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 | |
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 |
|---|---|---|
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
}
}