Direct Debits v3.1

Version Control

VersionDateAuthorComments
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.
3.1-draft1 OB R/W API Team

This is the initial draft version for 3.1

Errata

  • Grammatical Fixes
3.1-draft2 OB R/W API Team

Draft2 Changes:

  • Updated example URLs to version 3.1.
3.1-draft3 OB R/W API TeamDraft3 Changes:

Errata

  • Fixed the type for ../Amount/Amount field from ActiveCurrencyAndAmount_SimpleType to OBActiveCurrencyAndAmount_SimpleType
3.1OB R/W API Team

Version 3.1 final release.

No changes from Version 3.1 RC1.

Endpoints

Endpoints for the resource and available methods.


ResourceHTTP OperationEndpointMandatory?ScopeGrant TypeIdempotency KeyParametersRequest ObjectResponse Object
1direct-debitsGETGET /accounts/{AccountId}/direct-debitsConditionalaccountsAuthorization CodeNo



OBReadDirectDebit1
2direct-debitsGETGET /direct-debitsOptionalaccountsAuthorization CodeNo

Pagination


OBReadDirectDebit1

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

Permission Codes

The resource requires the ReadDirectDebits permission. The resource response payload does not differ depending on the permissions granted.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern

OBReadDirectDebit1


OBReadDirectDebit1


OBReadDirectDebit1



Data

1..1

OBReadDirectDebit1/Data


OBReadDataDirectDebit1



DirectDebit

0..n

OBReadDirectDebit1/Data/DirectDebit

Account to or from which a cash entry is made.

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

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.

OBActiveCurrencyAndAmount_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}$


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