Version Control
Version | Date | Author | Comments |
|---|---|---|---|
| 1.0.0 | 01 March 2019 | Payments NZ API Working Group | Baseline specification for Direct Debits resource |
| v2.0-draft1 | Updates:
Added:
| ||
| v2.0-draft3 | Gavin Wong (Unlicensed) | Errata:
|
Definition
A resource that contains a set of elements that describes the list of direct-debits that have been set up on a specific account (AccountId).
An account (AccountId) may have no direct debits set up, or may have multiple direct debits set up.
Endpoints
Resource | Endpoint | Mandatory? | Scope | Grant Type | Idempotency Key | Parameters | Request Object | Response Object |
|---|---|---|---|---|---|---|---|---|
| direct-debits | GET /accounts/{AccountId}/direct-debits | Optional | accounts | Redirect Flow; or Decoupled Flow | No | OBReadDirectDebit1 | ||
| direct-debits | GET /direct-debits | Optional | accounts | Redirect Flow; or Decoupled Flow | No | Pagination | OBReadDirectDebit1 |
GET /accounts/{AccountId}/direct-debits
The API endpoint allows a Third Party to retrieve the direct-debits resource 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 /direct-debits
The API endpoint allows a Third Party to retrieve direct-debits resources 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 resources for all accounts linked to the account-access-consent.
Data Model
The OBReadDirectDebit1 object will be used for the call to:
- GET /accounts/{AccountId}/direct-debits
- GET /direct-debits
UML Diagram
Permission Codes
The resource requires the ReadDirectDebits permission. The resource response payload does not differ depending on the permissions granted.
Data Dictionary
| Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
|---|---|---|---|---|---|---|
| OBReadDirectDebit1 | OBReadDirectDebit1 | OBReadDirectDebit1 | ||||
| Data | 1..1 | OBReadDirectDebit1/Data | OBReadDataDirectDebit1 | |||
| DirectDebit | 0..n | OBReadDirectDebit1/Data/DirectDebit | OBDirectDebit1 | |||
| AccountId | 1..1 | OBReadDirectDebit1/Data/DirectDebit/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner. | Max40Text | ||
| DirectDebitId | 0..1 | OBReadDirectDebit1/Data/DirectDebit/DirectDebitId | A unique and immutable identifier used to identify the direct debit resource. This identifier has no meaning to the account owner. | Max40Text | ||
| MandateIdentification | 1..1 | OBReadDirectDebit1/Data/DirectDebit/MandateIdentification | Direct Debit reference. | Max35Text | ||
| DirectDebitStatusCode | 0..1 | OBReadDirectDebit1/Data/DirectDebit/DirectDebitStatusCode | Specifies the status of the direct debit in code form. | OBExternalDirectDebitStatus1Code | Active Inactive | |
| Name | 1..1 | OBReadDirectDebit1/Data/DirectDebit/Name | Name of Service User. | Max70Text | ||
| PreviousPaymentDateTime | 0..1 | OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentDateTime | Date of most recent direct debit collection. | ISODateTime | ||
| PreviousPaymentAmount | 0..1 | OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmount | The amount of the most recent direct debit collection. | OBActiveOrHistoricCurrencyAndAmount | ||
| Amount | 1..1 | OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmount/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 | OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmount/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 |
|---|---|---|
| OBExternalDirectDebitStatus1Code | Active | The direct debit is active. |
| OBExternalDirectDebitStatus1Code | Inactive | The direct debit is inactive. |
Usage Examples
Specific Account
Retrieving resources for a specific account.
Request
Get Accounts Direct Debits Request
GET /accounts/22289/direct-debits HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-customer-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 Accounts Direct Debits Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
{
"Data": {
"DirectDebit": [
{
"AccountId": "22289",
"DirectDebitId": "DD03",
"MandateIdentification": "Caravanners",
"DirectDebitStatusCode": "Active",
"Name": "Towbar Club 3 - We Love Towbars",
"PreviousPaymentDateTime": "2017-04-05T10:43:07+00:00",
"PreviousPaymentAmount": {
"Amount": "0.57",
"Currency": "GBP"
}
}
]
},
"Links": {
"Self": "https://api.examplebank.co.nz/open-banking-nz/v2.0/accounts/22289/direct-debits"
},
"Meta": {
"TotalPages": 1
}
}
Bulk
Retrieving resources for all accounts linked to the account-access-consent.
Request
Get Direct Debits Request
GET /direct-debits 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 Direct Debits Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
{
"Data": {
"DirectDebit": [
{
"AccountId": "22289",
"DirectDebitId": "DD03",
"MandateIdentification": "Caravanners",
"DirectDebitStatusCode": "Active",
"Name": "Towbar Club 3 - We Love Towbars",
"PreviousPaymentDateTime": "2017-04-05T10:43:07+00:00",
"PreviousPaymentAmount": {
"Amount": "0.57",
"Currency": "GBP"
}
},
{
"AccountId": "31820",
"DirectDebitId": "DD77",
"MandateIdentification": "Golfers",
"DirectDebitStatusCode": "Active",
"Name": "Golf Club",
"PreviousPaymentDateTime": "2017-05-06T09:00:00+00:00",
"PreviousPaymentAmount": {
"Amount": "22.30",
"Currency": "GBP"
}
}
]
},
"Links": {
"Self": "https://api.examplebank.co.nz/open-banking/v2.0/direct-debits"
},
"Meta": {
"TotalPages": 1
}
}
Add Comment