Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 01 March 2019 | Payments NZ API Working Group | Baseline specification for Offers resource |
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 | Optional | accounts | Authorization Code | OBReadOffer1 | |||
2 | offers | GET | GET /offers | Optional | accounts | Authorization Code | Pagination | OBReadOffer1 |
A Third Party may retrieve the offers resource for a specific AccountId (which is retrieved in the call to GET /accounts).
If an API Provider has implemented the bulk retrieval endpoints - a Third Party may optionally retrieve the offers in bulk.
This will retrieve the resources for all authorised accounts linked to the account-request.
The OBReadOffer1 object will be used for the call to:
A resource that contains a set of elements that describes the list of offers available to a specific account (AccountId).
An account (AccountId) may have no offers available, or may have multiple offers available.
Notes:
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 | ||
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 | ||
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}$ |
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. |
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": "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/v1.0/accounts/22289/offers/" }, "Meta": { "TotalPages": 1 } } |
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": "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/v1.0/offers/" }, "Meta": { "TotalPages": 1 } } |