Direct Debits - v3.1.3

# Overview

The direct-debits resource is used by an AISP to retrieve the direct debits for a specific account identified by AccountId or to retrieve direct debits for all accounts that the PSU has consented to.

This resource description should be read in conjunction with a compatible Account Information Services API Profile.

# Endpoints

Endpoints for the resource and available methods.

Resource HTTP Operation Endpoint Mandatory? Scope Grant Type Idempotency Key Parameters Request Object Response Object
1 direct-debits GET GET /accounts/{AccountId}/direct-debits Conditional accounts Authorization Code No OBReadDirectDebit2
2 direct-debits GET GET /direct-debits Optional accounts Authorization Code No Pagination OBReadDirectDebit2

# GET /accounts/{AccountId}/direct-debits

An ASPSP must provide this endpoint for AISPs to retrieve the direct-debits for a specific account identified by AccountId.

# GET /direct-debits

An ASPSP may provide this endpoint for AISPs to retrieve direct-debits for all accounts that the PSU 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

OBReadDirectDebit2.png

# 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
OBReadDirectDebit2 OBReadDirectDebit2 OBReadDirectDebit2
Data 1..1 OBReadDirectDebit2/Data OBReadDataDirectDebit2
DirectDebit 0..n OBReadDirectDebit2/Data/DirectDebit Account to or from which a cash entry is made. OBDirectDebit2
AccountId 1..1 OBReadDirectDebit2/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 OBReadDirectDebit2/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 OBReadDirectDebit2/Data/DirectDebit/MandateIdentification Direct Debit reference. For AUDDIS service users provide Core Reference. For non AUDDIS service users provide Core reference if possible or last used reference. Max35Text
DirectDebitStatusCode 0..1 OBReadDirectDebit2/Data/DirectDebit/DirectDebitStatusCode Specifies the status of the direct debit in code form. OBExternalDirectDebitStatus1Code Active Inactive
Name 1..1 OBReadDirectDebit2/Data/DirectDebit/Name Name of Service User. Max70Text
PreviousPaymentDateTime 0..1 OBReadDirectDebit2/Data/DirectDebit/PreviousPaymentDateTime Date of most recent direct debit collection. ISODateTime
Frequency 0..1 OBReadDirectDebit2/Data/DirectDebit/Frequency Regularity with which direct debit instructions are to be created and processed OBExternalDirectDebitFrequency1Code
PreviousPaymentAmount 0..1 OBReadDirectDebit2/Data/DirectDebit/PreviousPaymentAmount The amount of the most recent direct debit collection. OBActiveOrHistoricCurrencyAndAmount
Amount 1..1 OBReadDirectDebit2/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. OBActiveCurrencyAndAmount_SimpleType ^\d{1,13}.\d{1,5}$
Currency 1..1 OBReadDirectDebit2/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}$

# Usage Examples

# Specific Account

# Get Accounts Direct Debits Request

GET /accounts/22289/direct-debits HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

# 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.alphabank.com/open-banking/v3.1/aisp/accounts/22289/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

# Bulk

# Get Direct Debits Request

GET /direct-debits HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

# 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.alphabank.com/open-banking/v3.1/aisp/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}