Skip to end of banner
Go to start of banner

Direct Debits v2.2.3

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

Version Control

Version

Date

Author

Comments

2.0.0

Payments NZ API Working Group

Baseline

2.1-draft1

 

Gavin Wong (Unlicensed)

Updated:

Removed:

2.1-rc2

Gavin Wong (Unlicensed)

Updated:

  • Scope definition based on Business WG feedback

2.2-draft1

Gavin Wong (Unlicensed)

Updated:

  • Updated statements and party endpoints to be mandatory as per v2.2 scope

2.2.1

Nigel Somerfield

Patch update to Swagger specification to BECSRemittance - DebtorReference and CreditorReference - specify additionalProperties: false

2.2.2

Nigel Somerfield

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

Nigel Somerfield

Patch update to clarify the explanation of BookingDateTime:

  • The BookingDateTime is the date the transaction is booked (or posted)
    and becomes immutable - which is not the date the transaction took place

was replaced with:

  • The BookingDateTime is the date the transaction is booked (or posted)
    and becomes immutable - which is not necessarily the date the transaction
    took place

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
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 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/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": "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

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": "NZD"
        }
      },
      {
        "AccountId": "31820",
        "DirectDebitId": "DD77",
        "MandateIdentification": "Golfers",
        "DirectDebitStatusCode": "Active",
        "Name": "Golf Club",
        "PreviousPaymentDateTime": "2017-05-06T09:00:00+00:00",
        "PreviousPaymentAmount": {
          "Amount": "22.30",
          "Currency": "NZD"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.examplebank.co.nz/open-banking/v2.1/direct-debits"
  },
  "Meta": {
    "TotalPages": 1
  }
}
  • No labels