Direct Debits v2.3.0
- Matthew Bell
- 1 Version Control
- 2 Definition
- 3 Endpoints
- 4 Data Model
- 4.1 UML Diagram
- 4.2 Permission Codes
- 4.3 Data Dictionary
- 4.4 Enumerations
- 5 Usage Examples
- 5.1 Specific Account
- 5.2 Bulk
- 5.2.1 Request
- 5.2.1.1 Get Direct Debits Request
- 5.2.2 Response
- 5.2.2.1 Get Direct Debits Response
- 5.2.1 Request
Version Control
Version | Date | Author | Comments |
|---|---|---|---|
2.0.0 | Apr 30, 2020 | Payments NZ API Working Group | Baseline |
2.1-draft1 | Jun 15, 2020 | @Gavin Wong (Unlicensed) | Updated:
|
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 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 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 direct-debits 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 | |
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 direct-debits 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/jsonResponse
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": "NZD"
}
}
]
},
"Links": {
"Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/accounts/22289/direct-debits"
},
"Meta": {
"TotalPages": 1
}
}Bulk
Retrieving direct-debits 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