/
Domestic Standing Orders v3.0

Domestic Standing Orders v3.0

Sept 07, 2018

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

3.0-draft2

May 8, 2018 

OB R/W API Team

New resource.

 

3.0-draft3

May 16, 2018 

OB R/W API Team

Modified title from Standing Order Consents to Domestic Standing Orders (and merged Standing Order Consents and Standing Order pages)

Changes carried from the standing-orders resource page:

  • Removed references to the AwaitingFurtherAuthorisation status (used for multi auth scenarios).

  • Errata: GET /standing-orders/{StandingOrderId} made Conditional

Draft3 changes:

  • New field for NonWorkingDayAdjustment

  • New fields to specify the final payment for the domestic standing order: either the

    • NumberOfPayments or

    • FinalPaymentDateTime

  • The new Initiation payload allows a PISP to specify a domestic standing order with a different payment amount for the first payment, the recurring payment, and the final payment

  • The NextPaymentAmount has been renamed to RecurringPaymentAmount

  • The NextPaymentDateTime has been removed, because it can be derived with the help of FirstPaymentDateTime and Frequency

  • Aligned GET operations Mandatory? flag with the equivalent resource POST.

3.0-draft4

May 30, 2018 

OB R/W API Team

Draft4 changes:

Clarified use of Idempotency Key in endpoint table.

Added re-used class description for:

  • OBCharge1

For the domestic-standing-order-consent response:

  • Added optional CutOffDateTime as some payment schemes have a cut-off time

  • Added optional Charges array as ASPSPs may require the ability to communicate fees and charges

For the domestic-standing-order response:

  • Added optional Charges array as ASPSPs may require the ability to communicate fees and charges

3.0-draft5

Jun 15, 2018 

OB R/W API Team

Draft5 changes:

  • SchemeName fields to be Max40Text - so Agent SchemeName values and Account SchemeName values will not be enforced via codelist.

  • DebtorAccount/Identification field extended to Max256Text to allow for email and other identification schemes

  • CreditorAccount/Identification field extended to Max256Text to allow for email and other identification schemes

  • Removed NonWorkingDayAdjustment field as per 143

  • Added a RecurringPaymentDateTime as requested, and clarified usage of RecurringPaymentAmount and RecurringPaymentDateTime

  • Clarified that "All elements in the Initiation payload that are specified by the PISP must not be changed via the ASPSP."

  • Reworded section for clarity in POST /domestic-standing-orders to indicate "ASPSP may not warehouse the domestic standing order immediately (e.g. busy periods at the ASPSP)"

  • Usage Examples and Alternate flows are moved back to the individual specification pages

  • Errata: removed reference of "International" from International Payment Initiation, in relation to OBCharge1 definition 

3.0-draft6/rc1

Jun 21, 2018 

OB R/W API Team

Draft6 changes:

  • Updated the OBDomesticStandingOrder1 object guidance from "the ASPSP must Reject the Initiation request" to "the ASPSP must reject the domestic-standing-order-consent"

  • Clarified the behavioural difference in when ASPSP rejects the payment-order consent request and when ASPSP sets the status of payment-order consent to Rejected

  • Added section for State Model / Payment Order / Multiple Authorisation

  • Updated definition of Name field in the CreditorAccount and DebtorAccount objects for clarity. Have specified usage that it is "The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account."

  • Added reused classes for:

    • OBAuthorisation1

    • OBMultiAuthorisation1

  • Updated Data Model section to reflect:

    • Authorisation object in the payment-order consent request and response

    • MultiAuthorisation object in the payment-order resource response

  • Added Notes section to describe the content of the POST /domestic-standing-order-consent

  • Updated "PersonToPerson" to "PartyToParty" in Usage Examples

  • Linked GET Mandatory? status to resource POST implementation

3.0-draft7

Jul 5, 2018 

OB R/W API Team

Draft7 Changes:

  • Changed the Grant Type for GET Requests to be Client Credentials Only.

  • Moved definitions of reused classes - OBCharge1, OBAuthorisation1 and OBMultiAuthorisation1 to Payment Initiation API Specification page

  • Added Frequency Examples

  • Corrected Request/Response Object names in Endpoints table

  • Added namespace-prefixed enumerations to examples

3.0-RC2

Jul 19, 2018 

OB R/W API Team

RC2 Changes:

  • Updated notes on CutOffDateTime to refer to Payment Initiation API Specification, Section - Payment Restrictions -> CutOffDateTime API Behaviour

3.0-RC3

Aug 3, 2018 

OB R/W API Team

Errata:

  • Removed 'Permission' element from the payment order usage example.

3.0-RC3

Aug 6, 2018 

OB R/W API Team

No Change

3.0

Sep 7, 2018 

OB R/W API Team

This is the baseline version. No change from RC3.

Endpoints

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Message Signing

Idempotency Key

Request Object

Response Object

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Message Signing

Idempotency Key

Request Object

Response Object

domestic-standing-order-consents

POST

POST /domestic-standing-order-consents

Conditional

payments

Client Credentials

Signed Request

Signed Response

Yes

OBWriteDomesticStandingOrderConsent1

OBWriteDomesticStandingOrderConsentResponse1

domestic-standing-order-consents

GET

GET /domestic-standing-order-consents/{ConsentId}

Mandatory (if resource POST implemented)

payments

Client Credentials

Signed Response

No

NA

OBWriteDomesticStandingOrderConsentResponse1

domestic-standing-orders

POST

POST /domestic-standing-orders

Conditional

payments

Authorization Code

Signed Request

Signed Response

Yes

OBWriteDomesticStandingOrder1

OBWriteDomesticStandingOrderResponse1

domestic-standing-orders

GET

GET /domestic-standing-orders/{DomesticStandingOrderId}

Mandatory (if resource POST implemented)

payments

Client Credentials

Signed Response

No

NA

OBWriteDomesticStandingOrderResponse1

POST /domestic-standing-order-consents

POST /domestic-standing-order-consents

The API endpoint allows the PISP to ask an ASPSP to create a new domestic-standing-order-consent resource.

  • The POST action indicates to the ASPSP that a domestic standing order consent has been staged. At this point, the PSU may not have been identified by the ASPSP, and the request payload may not contain any information of the account that should be debited.

  • The endpoint allows the PISP to send a copy of the consent (between PSU and PISP) to the ASPSP for the PSU to authorise.

  • The ASPSP creates the domestic-standing-order-consent resource and responds with a unique ConsentId to refer to the resource.

Status

The default Status is "AwaitingAuthorisation" immediately after the domestic-standing-order-consent has been created.

Status

Status

AwaitingAuthorisation

GET /domestic-standing-order-consents/{ConsentId}

GET /domestic-standing-order-consents/{ConsentId}

A PISP can optionally retrieve a payment consent resource that they have created to check its status. 

Status

Once the PSU authorises the payment-consent resource - the Status of the payment-consent resource will be updated with "Authorised".

If the PSU rejects the consent or the domestic-standing-order-consent has failed some other ASPSP validation, the Status will be set to "Rejected".

Once a domestic-standing-order has been successfully created using the domestic-standing-order-consent, the Status of the domestic-standing-order-consent will be set to "Consumed".

The available Status codes for the domestic-standing-order-consent resource are:

Status

Status

AwaitingAuthorisation

Rejected

Authorised

Consumed

POST /domestic-standing-orders

POST /domestic-standing-orders

Once the domestic-standing-order-consent has been authorised by the PSU, the PISP can proceed to submitting the domestic-standing-order for processing:

  • This is done by making a POST request to the domestic-standing-orders endpoint.

  • This request is an instruction to the ASPSP to begin the domestic standing order journey. The PISP must submit the domestic standing order immediately, however, there are some scenarios where the ASPSP may not warehouse the domestic standing order immediately (e.g. busy periods at the ASPSP).

  • The PISP must ensure that the Initiation and Risk sections of the domestic-standing-order match the corresponding Initiation and Risk sections of the domestic-standing-order-consent resource. If the two do not match, the ASPSP must not process the request and must respond with a 400 (Bad Request).

  • Any operations on the domestic-standing-order resource will not result in a Status change for the domestic-standing-order resource.

Status

A domestic-standing-order can only be created if its corresponding domestic-standing-order-consent resource has the status of "Authorised". 

The domestic-standing-order resource that is created successfully must have one of the following Status codes:

Status

Status

InitiationPending

InitiationFailed

InitiationCompleted 

GET /domestic-standing-orders/{DomesticStandingOrderId}

GET /domestic-standing-orders/{DomesticStandingOrderId}

A PISP can retrieve the domestic-standing-order to check its status.

Status

The domestic-standing-order resource must have one of the following Status codes:

Status

Status

InitiationPending

InitiationFailed

InitiationCompleted 

State Model

Payment Order Consent

The state model for the domestic-standing-order-consent resource follows the generic consent state model. However, does not use the "Revoked" status, as the consent for a domestic-standing-order is not a long-lived consent.

 

 

The definitions for the Status:

Status

Status Description

Status

Status Description

1

AwaitingAuthorisation

The consent resource is awaiting PSU authorisation.

2

Rejected

The consent resource has been rejected.

3

Authorised 

The consent resource has been successfully authorised.

4

Consumed

The consented action has been successfully completed. This does not reflect the status of the consented action.

Payment Order

The state model for the domestic-standing-order resource describes the initiation status only. I.e., not the subsequent execution of the domestic-standing-order.

 

 

The definitions for the Status:

Status

Payment Status Description

Status

Payment Status Description

1

InitiationPending

The initiation of the payment order is pending.

2

InitiationFailed

The initiation of the payment order has failed.

3

InitiationCompleted 

The initiation of the payment order is complete.

Multiple Authorisation

If the payment-order requires multiple authorisations - the Status of the multiple authorisations will be updated in the MultiAuthorisation object.

 

The definitions for the Status:

Status

Status Description

Status

Status Description

1

AwaitingFurtherAuthorisation

The payment-order resource is awaiting further authorisation.

2

Rejected

The payment-order resource has been rejected by an authoriser.

3

Authorised 

The payment-order resource has been successfully authorised by all required authorisers.

Data Model

The data dictionary section gives the detail on the payload content for the Domestic Standing Order API flows.

Reused Classes

OBDomesticStandingOrder1

This section describes the OBDomesticStandingOrder1 class - which is reused as the Initiation object in the domestic-standing-order-consent and domestic-standing-order resources.

UML Diagram

Notes

For the OBDomesticStandingOrder1 Initiation object: 

  • All elements in the Initiation payload that are specified by the PISP must not be changed via the ASPSP - as this is part of formal consent from the PSU

  • If the ASPSP is able to establish a problem with payload or any contextual error during the API call, the ASPSP must reject the domestic-standing-order-consent request immediately

  • If the ASPSP establishes a problem with the domestic-standing-order-consent after the API call, the ASPSP can set the Status of the domestic-standing-order-consent resource to Rejected

  • DebtorAccount is optional - as the PISP may not know the account identification details for the PSU.

  • If the DebtorAccount is specified by the PISP and is invalid for the PSU - then the domestic-standing-order-consent will be set to Rejected after PSU authentication.

  • Account Identification field usage:

    • Where "SortCodeAccountNumber" is specified as the SchemeName in the Account identification section (either DebtorAccount or CreditorAccount), the Identification field must be populated with the 6 digit Sort Code and 8 digit Account Number (a 14 digit field).

    • Where the "IBAN" is specified as the SchemeName in the Account identification section (either DebtorAccount or CreditorAccount), the Identification field must be populated with the full IBAN

  • Permission field is restricted to "Create" - however, may be extended to "Update" and "Delete" in a future iteration of the specification.

  • Either the NumberOfPayments or FinalPaymentDateTime must be specified (not both) if the domestic standing order is not open ended.

  • The structure allows a PISP to specify a domestic standing order with a different payment amount and date combinations: for the first payment, the recurring payment, and the final payment. The recurring payment (and date) must only be populated if different from the first payment (and date).

  • If the PISP requests a Frequency that is not supported by the ASPSP the ASPSP must respond with a 400 HTTP status code.

Frequency Examples

Frequency

Example

Details

Frequency

Example

Details

EvryDay

EvryDay

Every day

EvryWorkgDay

EvryWorkgDay

Every working day

IntrvlWkDay

IntrvlWkDay:1:3

Every week, on the 3rd day of the week

IntrvlWkDay

IntrvlWkDay:2:3

Every 2nd week, on the 3rd day of the week

WkInMnthDay

WkInMnthDay:2:3

Every month, on the 2nd week of the month, and on the third day of the week

IntrvlMnthDay

IntrvlMnthDay:1:-1

Every month, on the last day of the month

IntrvlMnthDay

IntrvlMnthDay:6:15

Every 6th month, on the 15th day of the month

QtrDay

QtrDay:ENGLISH

Paid on the 25th March, 24th June, 29th September and 25th December

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

© Open Banking Limited 2019 | https://www.openbanking.org.uk/open-licence | https://www.openbanking.org.uk