# Direct Debits - v4.0

# 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 Pagination 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

# Reused Classes

# OBMandateRelatedInformation1

The OBMandateRelatedInformation1 class is defined in the account-and-transaction-api-profile page.

Note: OBMandateRelatedInformation1/MandateIdentification should contain the Direct Debit reference. For AUDDIS service users provide Core Reference. For non AUDDIS service users provide Core reference if possible or last used reference

# 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

# 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..* 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
DirectDebitStatusCode 0..1 OBReadDirectDebit2/Data/DirectDebit/DirectDebitStatusCode Specifies the status of the direct debit in code form. For a full list of enumeration values refer to External_CodeSet here (opens new window) ExternalMandateStatus1Code
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
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,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}$
MandateRelatedInformation 0..1 OBReadDirectDebit2/Data/DirectDebit/MandateRelatedInformation OBMandateRelatedInformation1

# 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",
        "MandateRelatedInformation": {
            "MandateIdentification": "Caravanners",
            "Classification": "FIXE",
            "CategoryPurposeCode": "BONU",
            "FirstPaymentDateTime": "2024-04-25T12:46:49.425Z",
            "RecurringPaymentDateTime": "2024-04-25T12:46:49.425Z",
            "FinalPaymentDateTime": "2024-04-25T12:46:49.425Z",
            "Reason": "To pay monthly membership",
            "Frequency": {
              "Type": "WEEK",
              "CountPerPeriod": 1
          }
        },
        "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/v4.0/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",
        "MandateRelatedInformation": {
            "MandateIdentification": "Caravanners",
            "Classification": "FIXE",
            "CategoryPurposeCode": "BONU",
            "FirstPaymentDateTime": "2024-04-25T12:46:49.425Z",
            "RecurringPaymentDateTime": "2024-04-25T12:46:49.425Z",
            "FinalPaymentDateTime": "2024-04-25T12:46:49.425Z",
            "Reason": "To pay monthly membership",
            "Frequency": {
              "Type": "MNTH",
              "CountPerPeriod": 1
          }
        },
        "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",
        "MandateRelatedInformation": {
          "MandateIdentification": "Golfers",
          "Classification": "FIXE",
          "CategoryPurposeCode": "BONU",
          "FirstPaymentDateTime": "2024-04-25T12:46:49.425Z",
          "RecurringPaymentDateTime": "2024-04-25T12:46:49.425Z",
          "FinalPaymentDateTime": "2024-04-25T12:46:49.425Z",
          "Frequency": { 
            "Type": "MNTH",
            "CountPerPeriod": 1
          }
        },
        "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/v4.0/aisp/direct-debits/"
  },
  "Meta": {
    "TotalPages": 1
  }
}