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 party linked to a specific account (AccountId).
The response to GET /accounts/{AccountId}/party and GET /party (if available) must contain at most one party.
Endpoints
Resource | Endpoint | Mandatory? | Scope | Grant Type | Idempotency Key | Parameters | Request Object | Response Object |
|---|---|---|---|---|---|---|---|---|
party | GET /accounts/{AccountId}/party | Mandatory | accounts | Redirect Flow; or Decoupled Flow | No | OBReadParty1 | ||
party | GET /party | Mandatory | accounts | Redirect Flow; or Decoupled Flow | No | OBReadParty1 |
GET /accounts/{AccountId}/party
The API endpoint allows a Third Party to retrieve details on the account owner for a specific account identified by AccountId.
In the case of a business - this will be the details of the business
In the case of a joint account - this will be the party that has given authorisation to the Third Party to view the account. If the Third Party wishes to access details of other parties linked to the AccountId, the Third Party must go through an authorisation flow with the other parties.
The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).
GET /party
The API endpoint allows a Third Party to retrieve details on the user that has authorised the account-access-consent with the API Provider.
In the case of a business account - this will be the details of the party that has given authorisation to the Third Party to view the account
In the case of a joint account - this will be the party that has given authorisation to the Third Party to view the account
Data Model
The OBReadParty1 object will be used for the call to:
GET /accounts/{AccountId}/party
GET /party
UML Diagram
Permission Codes
The ReadParty permission is required to access GET /accounts/{AccountId}/party. The resource response payload does not differ depending on the permissions granted.
The ReadPartyAuthUser permission is required to access GET /party. The resource response payload does not differ depending on the permissions granted.
Data Dictionary
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
|---|---|---|---|---|---|---|
OBReadParty1 | OBReadParty1 | OBReadParty1 | ||||
Data | 1..1 | OBReadParty1/Data | OBReadDataParty1 | |||
Party | 0..1 | OBReadParty1/Data/Party | OBParty1 | |||
PartyId | 1..1 | OBReadParty1/Data/Party/PartyId | A unique and immutable identifier used to identify the customer resource. This identifier has no meaning to the account owner. | Max40Text | ||
PartyNumber | 0..1 | OBReadParty1/Data/Party/PartyNumber | Number assigned by an agent to identify its customer. | Max35Text | ||
PartyType | 0..1 | OBReadParty1/Data/Party/PartyType | Party type, in a coded form. | OBExternalPartyType1Code | Delegate | |
Name | 0..1 | OBReadParty1/Data/Party/Name | Name by which a party is known and which is usually used to identify that party. | Max70Text | ||
EmailAddress | 0..1 | OBReadParty1/Data/Party/EmailAddress | Address for electronic mail (e-mail). | Max256Text | ||
Phone | 0..1 | OBReadParty1/Data/Party/Phone | Collection of information that identifies a phone number, as defined by telecom services. | PhoneNumber | \+[0-9]{1,3}-[0-9()+\-]{1,30} | |
Mobile | 0..1 | OBReadParty1/Data/Party/Mobile | Collection of information that identifies a mobile phone number, as defined by telecom services. | PhoneNumber | \+[0-9]{1,3}-[0-9()+\-]{1,30} | |
Address | 0..n | OBReadParty1/Data/Party/Address | Postal address of a party. | OBPostalAddress8 | ||
AddressType | 0..1 | OBReadParty1/Data/Party/Address/AddressType | Identifies the nature of the postal address. | OBAddressTypeCode | Business | |
AddressLine | 0..5 | OBReadParty1/Data/Party/Address/AddressLine | Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. | Max70Text | ||
StreetName | 0..1 | OBReadParty1/Data/Party/Address/StreetName | Name of a street or thoroughfare. | Max70Text | ||
BuildingNumber | 0..1 | OBReadParty1/Data/Party/Address/BuildingNumber | Number that identifies the position of a building on a street. | Max16Text | ||
PostCode | 0..1 | OBReadParty1/Data/Party/Address/PostCode | Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. | Max16Text | ||
TownName | 0..1 | OBReadParty1/Data/Party/Address/TownName | Name of a built-up area, with defined boundaries, and a local government. | Max35Text | ||
CountrySubDivision | 0..1 | OBReadParty1/Data/Party/Address/CountrySubDivision | Identifies a subdivision of a country eg, state, region, county. | Max35Text | ||
Country | 1..1 | OBReadParty1/Data/Party/Address/Country | Nation with its own government, occupying a particular territory. | CountryCode | ^[A-Z]{2,2}$ |
Enumerations
This section gives the definitions for enumerations used.
Code Class | Name | Definition |
|---|---|---|
OBAddressTypeCode | Business | Address is the business address. |
OBAddressTypeCode | Correspondence | Address is the address where correspondence is sent. |
OBAddressTypeCode | DeliveryTo | Address is the address to which delivery is to take place. |
OBAddressTypeCode | MailTo | Address is the address to which mail is sent. |
OBAddressTypeCode | POBox | Address is a postal office (PO) box. |
OBAddressTypeCode | Postal | Address is the complete postal address. |
OBAddressTypeCode | Residential | Address is the home address. |
OBAddressTypeCode | Statement | Address is the address where statements are sent. |
OBExternalPartyType1Code | Delegate | Party that has delegated access. |
OBExternalPartyType1Code | Joint | Party is a joint owner of the account. |
OBExternalPartyType1Code | Sole | Party is a sole owner of the account. |
Usage Examples
Account Owner
Retrieving the account owner for a specific account.
Request
Get Party Request
GET /accounts/22289/party 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 Party Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
{
"Data": {
"Party": {
"PartyId": "PABC123",
"PartyType": "Sole",
"Name": "Semiotec",
"Email": "contact@semiotec.co.uk",
"Address": {
"AddressType": "Business",
"StreetName": "Street",
"BuildingNumber": "15",
"PostCode": "1024",
"TownName": "Auckland",
"Country": "NZ"
}
}
},
"Links": {
"Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/accounts/22289/party"
},
"Meta": {
"TotalPages": 1
}
}
Authorised User
Retrieving the authorised user.
Request
Get Party Request
GET /party 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 Party Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
{
"Data": {
"Party": {
"PartyId": "PXSIF023",
"PartyType": "Delegate",
"Name": "Mr D User",
"Email": "d.user@semiotec.co.uk"
}
},
"Links": {
"Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/party"
},
"Meta": {
"TotalPages": 1
}
}