# # Direct Debits - v4.0-draft1

- Overview
- Endpoints
  - GET /accounts/{AccountId}/direct-debits
  - GET /direct-debits
- Data Model
  - Reused Classes
    - OBMandateRelatedInformation1
  - Resource Definition
  - UML Diagram
  - Permission Codes
  - Data Dictionary
  - Reused Classes
    - OBMandateRelatedInformation1
- Usage Examples
  - Specific Account
    - Get Accounts Direct Debits Request
    - Get Accounts Direct Debits Response
  - Bulk
    - Get Direct Debits Request
    - Get Direct Debits Response

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

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

### # Reused Classes

#### # OBMandateRelatedInformation1

The OBMandateRelatedInformation1 class is defined in the payment-initiation-api-profile page. MandateIdentification contains 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

## # 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",
                "Frequency": {
                  "Type": "WEEK",
                  "CountPerPeriod": 1,
                  "PointInTime": "00"
              }
            },
            "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",
            "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",
                "Frequency": {
                  "Type": "MNTH",
                  "CountPerPeriod": 1,
                  "PointInTime": "00"
              }
            },
            "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,
                "PointInTime": "00"
              }
            },
            "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
      }
    }