/
Payment Initiation API Specification - v3.0

Payment Initiation API Specification - v3.0

Sept 10, 2018

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

3.0-draft1

Apr 18, 2018 

OB R/W API Team

First draft of v3

Changes to align with the structure of Accounts & Transactions API

  • Removed Overview / Design Principles - RESTful APIs, Standards,  ISO 20022, Extensibility, Idempotency  and Status Codes

  • Removed Overview / Design Principles / Non-repudiation

  • Removed Overview / Scope 

  • Removed Overview / Out of Scope 

  • Removed Basics / Actors, Character Encoding, Date Formats, Resource URI Path Structure, Headers, Return & Error Codes, Pre-conditions, Idempotency, Non-repudiation, Filtering, Pagination, Regulatory Considerations

  • Endpoints section updated to cross-reference child pages with end-point details

  • Documentation for individual end-points moved into child pages

  • Removed section Data Model except for Identifier Fields, Enumerations and Mapping to Schemes & Standards

  • Removed section Usage Examples

3.0-draft2

May 8, 2018 

OB R/W API Team

  • Modified Basics / Overview to add details about standing orders

  • Generalise references to Single Immediate Payments to Payment Orders or add Standing Order references where appropriate.

3.0-draft3

May 17, 2018 

OB R/W API Team

Draft 3 changes:

  • OBRisk1 class moved to this page (from the Payment resource page)

  • Updated references to payment setup to payment-order consent; and references to payment submission to payment-order resource

  • Design Principles / Status Codes:

    • Removed reference in Status Codes to "The Security Working Group have stated that granular error codes may expose threat vectors - so these are limited to the HTTP Status Codes for v1.0." as this is under review

  • Generalised Basics / Overview section to payment-order consent and payment-order resource. Clarified consent step and differences in GET requests.

  • Removed Consent Authorisation / Payment Status section - as this has been moved into the payment-order type sub pages.

  • Updated Mapping to Schemes & Standards / Transaction Status

  • Removed DebtorAgent and CreditorAgent from FP and Bacs mappings.

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

  • In Endpoint section - removed reference to "must respond with a 404 (Not Found) for requests to that URL." and moved to Read Write API page.

3.0-draft4

May 25, 2018 

OB R/W API Team

Errata:

  • Generalised the references of PaymentId and PaymentSubmissionId to ConsentId and Payment Order Id

Draft 4 Changes:

  • Updated Enumerations table - Remove deprecated statuses for OBTransactionIndividualStatus1Code

  • Updated Payment Limits section to Payment Restrictions - clarified behaviour if an ASPSP is unable to handle a payment-order request

3.0-draft5

Jun 7, 2018 

OB R/W API Team

Draft 5 Changes:

  • New subpages for new payment-order types:

    • International Standing Orders

    • File Payments

  • Usage Examples moved back into payment-order type pages

  • Included status values in overview sequence diagram

  • Added CutOffDateTime in Payment Restrictions section

  • Removed OBExternalAccountIdentification2Code enumeration reference

  • Removed Mapping to Schemes and Standards section - and moved to a sub-page for Domestic Payment Message Formats

  • Usage Examples and Alternate flows are moved back to the individual specification pages. New alternate flow for CutOffDateTime behaviour.

  • Errata:

    • Spelling errors

    • Reference to consent for payment-order updated to payment-order consent (for consistency)

3.0-draft6/rc1

Jun 27, 2018 

OB R/W API Team

Draft6 Changes:

  • Removed "request" in statements relating to rejection - so that the ASPSP may set the Status of a resource as "Rejected" in the case of a rejection. 

  • Updated references to PersonToPerson to PartyToParty - as it generalises to business to business payments.

  • Added Consent Authorisation / Multiple Authorisation section

  • Referenced Read/Write Data API Specification in overview.

  • Added Release Management in Basics section

  • Errata:

    • Spelling

    • Typo on MSD.

    • Moved table under Data Model / Enumerations to Daa Model / Enumerations / Static Enumerations

    • Added section for Data Model / Enumerations /Namespaced Enumerations

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.

  • Added definitions of reused classes - OBCharge1, OBAuthorisation1 and OBMultiAuthorisation1, and

    • Removed from all Payment Order pages.

  • Added Post PSU Authentication guideline in Payment Initiation>Consent Authorisation>Multiple Authorisation Section

  • Added Multi-Auth Payment Order Consent flow

  • Added Enumeration definitions for completeness

  • Added webhook notifications as an option to notify a TPP that a multi auth flow is complete

Errata

  • In the Release Management Section, GET payment-order consent updated:

3.0-RC2

Jul 19, 2018 

OB R/W API Team

RC2 Changes:

  • Updated file types to UK.OBIE.pain.001.001.08 and UK.OBIE.PaymentInitiation.3.0.

  • Referred to Event Notification API Specification (renamed from Webhook Notification Specification).

  • Removed 'generalised for all payment types' comment on the Multi-Auth Payment Order Consent as specific to Domestic Payments.

  • Removed section on 'Handling Expired Access Tokens'

  • Added section on Consent Re-authorisation

  • Updated LocalInstrument Enumeration section to

    • Include wording of a "payment service"

    • Include international payment services 

  • CutOffDateTime Behaviour updated in accordance with draft Decision 162

  • Removed AuthorisationType "Multiple"

  • Changes to cater for CIBA

    • Modified Basics / Overview / Steps

    • Added  alternative Sequence Diagram for Decoupled Flow

    • Updated Grant Types

  • Clarification - the OBMultiAuthorisation1/NumberRequired field is the total number required at the start of the multi authorisation journey

  • Added Swagger specification.

3.0-RC3

Aug 3, 2018 

OB R/W API Team

RC3 Changes:

  • Added BalanceTransfer and MoneyTransfer to Namespaced Enumerations for LocalInstrument:

    • UK.OBIE.BalanceTransfer

    • UK.OBIE.MoneyTransfer

  • Clarified that an ASPSP may optionally return a CutOffDateTime.

  • Renamed Consent Re-authorisation to Consent Re-authentication

    • Added UK.OBIE.Link as a LocalInstrument enumeration. 

  • Clarified the definitions for the FileTypes in the core UK.OBIE.* namespace

    • Added Swagger-based API specification files encoded in JSON and YAML.

3.0

Sep 7, 2018 

OB R/W API Team

This is the baseline version. No change from RC3.

Swagger URLs updated to point to latest stable version.

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a general payment-order. 

The API endpoints described here allow a PISP to: 

  • Register an intent to stage a payment-order consent

  • Subsequently submit the payment-order for processing

  • Optionally retrieve the status of a payment-order consent or payment-order resource

This specification should be read in conjunction with Read/Write Data API Specification which provides a description of the elements that are common across all the Read/Write Data APIs.

Document Overview

This document consists of the following parts:

Overview: Provides an overview of the API and the key decisions and principles that contributed to the specification.

Basics: The section begins with an introduction to how the API is to used to initiate a payment order, using the example of a single immediate payment. It goes on to identify the resources and operations that are permitted on those resources and various special cases.

Security & Access Control: Specifies the means for PISPs and PSUs to authenticate themselves and provide consent.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Data Model: Describes the data model for the API payloads.

Usage Examples: Examples for normal flows, and alternate flows.

Design Principles

Scheme Agnostic

The API will be designed so that it is agnostic to the underlying payment scheme that is responsible for carrying out the payment.

In doing so - this means we will not design field lengths and payloads to only match the Faster Payments message, and will instead rely on the field lengths and definitions in ISO 20022. Due diligence has been carried out to ensure that the API has the necessary fields to function with Bacs payments - as per agreed scope.

We will provide further mapping guidance to ensure that differences are understood between the Open Banking Payment API standard, and other message formats in the Domestic Payment Message Formats sub-page.

Status Codes

The API uses two status codes that serve two different purposes:

  • The HTTP Status Code reflects the outcome of the API call (the HTTP operation on the resource).

  • The Status field for the payment-order consent reflects the status of the PSU consent authorisation.

  • The Status field for the payment-order resource reflects the status of the payment-order initiation or execution.

Basics

Overview

The figure below provides a general outline of a payment flow for all payment-order types using the Payment APIs. The payment-order types covered in this specification include:

  • Domestic payments

  • Domestic scheduled payments

  • Domestic standing orders

  • International payments

  • International scheduled payments

The payment-order consent and payment-order resource in the following flow generalises for the different payment-order types. e.g. for a domestic payment, the payment-order consent resource is domestic-payment-consents; and the payment-order resource is domestic-payments. 

Steps

Step 1: Agree Payment-Order Initiation

  • This flow begins with a PSU consenting to a payment being made. The consent is between the PSU and the PISP.

  • The debtor account details can optionally be specified at this stage.

Step 2: Setup Payment-Order Consent

  • The PISP connects to the ASPSP that services the PSU's payment account and creates a new payment-order consent resource. This informs the ASPSP that one of its PSUs intends to make a payment-order. The ASPSP responds with an identifier for the payment-order consent resource (the ConsentId - which is the intent identifier).

  • This step is carried out by making a POST request to the payment-order consent resource.

Step 3: Authorise Consent

  • The PISP requests the PSU to authorise the consent. The ASPSP may carry this out by using a redirection flow or a decoupled flow.

    • In a redirection flow, the PISP redirects the PSU to the ASPSP.

      • The redirect includes the ConsentId generated in the previous step.

      • This allows the ASPSP to correlate the payment order consent that was setup.

      • The ASPSP authenticates the PSU.

      • The ASPSP updates the state of the payment order consent resource internally to indicate that the consent has been authorised.

      • Once the consent has been authorised, the PSU is redirected back to the PISP.

    • In a decoupled flow, the ASPSP requests the PSU to authorise consent on an authentication device that is separate from the consumption device on which the PSU is interacting with the PISP.

      • The decoupled flow is initiated by the PISP calling a back-channel authorisation request.

      • The request contains a 'hint' that identifies the PSU paired with the consent to be authorised.

      • The ASPSP authenticates the PSU and updates the state of the payment order consent resource internally to indicate that the consent has been authorised.

      • Once the consent has been authorised, the ASPSP can make a callback to the PISP to provide an access token.

  • The PSU selects the debtor account at this stage - if it has not been previously specified in Step 1.

Step 4: Create Payment-Order

  • Once the PSU is redirected to the PISP, the PISP creates a payment-order resource to indicate that the payment created in the steps above should be submitted for processing.

  • This is carried out by making a POST request to the appropriate payment-order resource.

  • ASPSP returns the identifier for the payment-order resource to the PISP.

Step 5: Get Payment-Order/Consent Status

  • If the ASPSP provides a status API, the PISP can check the status of the payment-order consent (with the ConsentId) or payment-order resource (with the payment-order resource identifier).

  • This is carried out by making a GET request to the payment-order consent or payment-order resource.

Sequence Diagram

 

participant PSU participant PISP participant ASPSP Authorisation Server participant ASPSP Resource Server note over PSU, ASPSP Resource Server Step 1: Agree Payment-Order Initiation end note PSU -> PISP: Agree payment-order initiation request note over PSU, ASPSP Resource Server Setup Payment-Order Consent end note PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server -> PISP: access-token PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: POST /payment-order-consents state over ASPSP Resource Server: Consent Status: AwaitingAuthorisation ASPSP Resource Server -> PISP: HTTP 201 (Created), ConsentId note over PSU, ASPSP Resource Server Step 3: Authorize Consent end note alt Redirection (Using authorization code grant) PISP -> PSU: HTTP 302 (Found), Redirect (ConsentId) PSU -> ASPSP Authorisation Server: Follow redirect (ConsentId) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: Select debtor account if required state over ASPSP Resource Server: Consent Status: Authorised ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (authorization-code) PSU -> PISP: Follow redirect (authorization-code) PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> PISP: access-token else Decoupled (Using CIBA) PISP -> ASPSP Authorisation Server: POST /bc-authorize (login_hint_token) ASPSP Authorisation Server -> PISP: OK PSU -> ASPSP Authorisation Server: Authorise (Consent Id) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: select accounts state over ASPSP Resource Server: Consent Status: Authorised alt Using callback ASPSP Authorisation Server -> PISP: Callback (authorization-code) PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> PISP: access-token else Using polling PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Poll at /token using auth-req-id ASPSP Authorisation Server -> PISP: access-token end alt end alt note over PSU, ASPSP Resource Server Step 4: Create Payment-Order end note PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: POST /payment-orders state over ASPSP Resource Server: Consent Status: Consumed alt Immediate Payment state over ASPSP Resource Server: Payment Status: Pending state over ASPSP Resource Server: Payment Status: AcceptedSettlementInProcess state over ASPSP Resource Server: Payment Status: AcceptedSettlementComplete else Standing Order or Future Dated Payment state over ASPSP Resource Server: Payment Status: InitiationPending state over ASPSP Resource Server: Payment Status: InitiationCompleted end alt ASPSP Resource Server -> PISP: HTTP 201 (Created), Payment-Order Id note over PSU, ASPSP Resource Server Step 5: Get Payment-Order/Consent Status end note opt payment-order-consent PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: GET /payment-order-consents/{ConsentId} ASPSP Resource Server -> PISP: HTTP 200 (OK) payment-order-consent resource end opt opt payment-order PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: GET /payment-orders/{Payment-Order Id} ASPSP Resource Server -> PISP: HTTP 200 (OK) payment-order resource end opt option footer=bar

Payment Restrictions

The standard does not provide a uniform set of restrictions for payment-order types that can be supported through this API.

For example, but not limited to:

  • The maximum InstructedAmount allowable

  • The domestic-standing-order Frequency patterns supported

  • The maximum future date on a scheduled-payment

Each ASPSP must determine appropriate restrictions that they support based on their individual practices, standards and limitations. These restrictions should be documented on ASPSP developer portals.

An ASPSP must reject the payment-order consent if the ASPSP is unable to handle the request.

CutOffDateTime Behaviour

An ASPSP may return the specific CutOffDateTime when responding to a payment-order consent request.

An ASPSP must document behaviour for payment receipt before and after the CutOffDateTime for a payment-order has elapsed.

Two strategies for handling behaviour are:

  • Reject the payment-order (and steps associated with the creation of payment-order) if received after the applicable CutOffDateTime

  • Accept the payment-order (and steps associated with the creation of payment-order) if received after the applicable CutOffDateTime

Reject the Payment-Order

In this scenario, the behaviour of payment-order execution is explicit to the PISP and PSU.

  • An ASPSP must reject the payment-order consent if the CutOffDateTime for specific payment-order type has elapsed.

  • An ASPSP must reject an authorization request when the underlying intent object is associated with a CutoffDateTime that has elapsed. The ASPSP must not issue an access token in such a situation. The ASPSP must set the status of the payment-order consent resource to “Rejected”.

  • An ASPSP must reject the payment-order resource if the CutOffDateTime for specific payment-order type, has been established and has elapsed.

  • A PISP must ensure the PSU consent authorisation is completed and payment-order resource is created before the CutOffDateTime elapses. 

For a payment-order consent or payment-order resource that has been rejected due to the elapsed CutoffDateTime, the PISP may decide to create corresponding schedule payment endpoint to create a new payment-order consent. E.g. if a PISP attempts to make a BACS payment after 16:00, it would be rejected. The PISP may use the /domestic-scheduled-payment-consents endpoint to create a consent for the same payment for the next working day.

Accept the Payment-Order

In this scenario, the behaviour of payment-order execution is not explicit to the PISP and PSU, and the payment-order will be executed on the next available working day.

  • An ASPSP must accept the payment-order consent if the CutOffDateTime for specific payment-order type has elapsed.

  • An ASPSP must accept an authorization request when the underlying intent object is associated with a CutoffDateTime that has elapsed.

  • An ASPSP must accept the payment-order resource if the CutOffDateTime for specific payment-order type, has been established and has elapsed.

  • An ASPSP may update the payment-order consent or payment-order resource with the CutOffDateTime, ExpectedExecutionDateTime and ExpectedSettlementDateTime - to communicate expected execution behaviour  if the CutOffDateTime has elapsed.

Release Management

This section overviews the release management and versioning strategy for Payment Initiation API. It applies to all Payment Order Consent and Payment Order resources, specified in the Endpoints section.

Payment-Order Consent

POST

  • A PISP must not create a payment-order consent ConsentId on a newer version and use it to create a payment-order resource in a previous version 

    • E.g., ConsentId created in v3, must not be used to create v1 PaymentSubmissionId

  • A PISP must not create a payment-order consent ConsentId on a previous version and use it to create a payment-order resource in a newer version

    • E.g., PaymentId created in v1, must not be used to create v3 DomesticPaymentId

GET

  • A PISP must not access a payment-order ConsentId created in a newer version, via a previous version endpoint

    • E.g., ConsentId created in v3 accessed via v1 PaymentId

  • An ASPSP may choose to make ConsentIds accessible across versions

    • E.g., for a PaymentId created in v1, an ASPSP may or may not make it available via v3 - as this is a short-lived consent

Payment-Order Resource

POST

  • A PISP must use a payment-order consent ConsentId within the same version to create the payment-order resource (in that version)

    • E.g., A v3 payment-order consent can only be used to create a payment-order resource in v3.

  • An ASPSP must not allow a PISP to use a ConsentId from a previous version to create Payment Order in a newer version, and vice versa

GET

  • A PISP must refer to the ASPSP's online Developer Portal for guidelines on accessibility of a payment-order resource in a newer version

  • A PISP must not access the payment-order resource types introduced in a newer version, on an older version endpoint

    • E.g., an international-payment created in v3, that is accessed via the v1 payment-submissions endpoint

  • A PISP must not access the payment-order resource created in a newer version on an older version endpoint

    • E.g., for a domestic-payment resource created in v3, access via the v1 payment-submissions endpoint is not permitted

  • An ASPSP must document the behaviour on the accessibility of a payment-order resource in a newer version on ASPSP's online Developer Portal

  • An ASPSP must allow access to the payment-order resource created in a previous version on a newer version endpoint (depending on an ASPSP's legal requirement for data retention):

    • E.g., a payment-submission created in v1, must be accessible as a v3 domestic-payment, with sensible defaults for additional fields introduced in v3 (e.g., if an ASPSP must make payment resources available for 7 years).

    • In the case where a payment-order type is same, but the structure is changed in a newer version - sensible defaults may be used, with ASPSP's Developer Portal clearly specifying the behaviour.

      • E.g., a new field StatusUpdateDateTime was introduced in v3 - an ASPSPs must populate with this with the last status update time - as the StatusUpdateDateTime is a mandatory field

Endpoints

This section looks at the list of available API endpoints to complete a Payment flow and optionality (definitions of mandatory, conditional or optional are defined in the Design Principles section in Read/Write Data API Specification). For detail on the request and response objects - refer to the Data Model section of the specification.

The Mandatory/Conditional/Optional status of a resource's POST endpoint matches the GET operation. If a POST endpoint is implemented, the GET endpoint must also be implemented.

Endpoint design considerations:

  • Having a separate resource for the payment-order consent and payment-order resource means we can extend the flows in the future. 

  • Separation in payment-order consent and payment-order resource also allows for cleaner separation in updating the status of resources - for ASPSPs that chose to implement the functionally.

Security & Access Control

API Scopes

The access tokens required for accessing the Payment APIs must have at least the following scope:

Scopes
payments

Grants Types

PISPs must use a client credentials grant to obtain a token to make POST requests to the payment-order consent endpoints. In the specification, this grant type is referred to as "Client Credentials".

PISPs must use grant using a redirect or decoupled flow to obtain a token to make POST requests to the payment-order resource endpoints. In the specification, this grant type is referred to as "Authorization Code".

PISPs must use a client credentials grant to obtain a token to make GET requests.

Consent Authorisation

OAuth 2.0 scopes are coarse-grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine-grained scopes (e.g. a scope to enforce payments of a specified amount on a specified date). 

A consent authorisation is used to define the fine-grained scope that is granted by the PSU to the PISP.

The PISP must begin a payment-order request by creating a payment-order consent resource through a POST operation. These resources indicate the consent that the PISP claims it has been given by the PSU. At this stage, the consent is not yet authorised as the ASPSP has not yet verified this claim with the PSU.

The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

As part of the authorization code grant:

  • The ASPSP authenticates the PSU.

  • The ASPSP plays back the consent (registered by the PISP) back to the PSU - to get consent authorisation. The PSU may accept or reject the consent in its entirety (but not selectively).

  • If the consent did not indicate a debtor account, the ASPSP presents the PSU with a list of accounts from which the PSU may select one.

Once these steps are complete, the consent is considered to have been authorised by the PSU.

Multiple Authorisation

In a multiple authorisation context, the same consent authorisation steps are followed for the first PSU to authorise or stage the payment-order consent.

In the payment-order consent:

  • A PISP may request an AuthorisationType for the payment-order (i.e., Single or Any). If a value is not provided, an ASPSP will interpret the AuthorisationType as 'Any'.