Direct Debits v1.0.0

Contents

Version Control

Version
Date
Author
Comments
1.0.001 March 2019Payments NZ API Working GroupBaseline specification for Direct Debits resource

Endpoints

Endpoints for the resource - and available methods.


ResourceHTTP OperationEndpointMandatory?ScopeGrant TypeIdempotentParametersRequest ObjectResponse Object
1direct-debitsGETGET /accounts/{AccountId}/direct-debitsOptionalaccountsAuthorization Code



OBReadDirectDebit1
2direct-debitsGETGET /direct-debitsOptionalaccountsAuthorization Code

Pagination


OBReadDirectDebit1

GET /accounts/{AccountId}/direct-debits

An API Provider must provide this endpoint for Third Parties to retrieve the direct-debits for a specific account identified by AccountId.

GET /direct-debits

An API Provider may provide this endpoint for Third Parties to retrieve direct-debits for all accounts that the Customer has consented to. This will retrieve the direct-debit resources for all authorised accounts linked to the account-request.

Data Model

Resource 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.

UML Diagram

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadDirectDebit1
OBReadDirectDebit1
OBReadDirectDebit1

Data1..1OBReadDirectDebit1/Data
OBReadDataDirectDebit1

DirectDebit0..nOBReadDirectDebit1/Data/DirectDebit
OBDirectDebit1

AccountId1..1OBReadDirectDebit1/Data/DirectDebit/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

DirectDebitId0..1OBReadDirectDebit1/Data/DirectDebit/DirectDebitIdA unique and immutable identifier used to identify the direct debit resource. This identifier has no meaning to the account owner.Max40Text

MandateIdentification1..1OBReadDirectDebit1/Data/DirectDebit/MandateIdentificationDirect Debit reference.Max35Text

DirectDebitStatusCode0..1OBReadDirectDebit1/Data/DirectDebit/DirectDebitStatusCodeSpecifies the status of the direct debit in code form.OBExternalDirectDebitStatus1CodeActive
Inactive

Name1..1OBReadDirectDebit1/Data/DirectDebit/NameName of Service User.Max70Text

PreviousPaymentDateTime0..1OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentDateTimeDate of most recent direct debit collection.ISODateTime

PreviousPaymentAmount0..1OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmountThe amount of the most recent direct debit collection.OBActiveOrHistoricCurrencyAndAmount

Amount1..1OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmount/AmountA 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}$
Currency1..1OBReadDirectDebit1/Data/DirectDebit/PreviousPaymentAmount/CurrencyA 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 
OBExternalDirectDebitStatus1CodeActiveThe direct debit is active.
OBExternalDirectDebitStatus1CodeInactiveThe direct debit is inactive.

Usage Examples

Specific Account

Request

Get Accounts Direct Debits Request
GET /accounts/22289/direct-debits 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

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/v1.0/accounts/22289/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Bulk

Request

Get Direct Debits Request
GET /direct-debits 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

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/v1.0/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}