Version Control

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a single immediate domestic payment.

The API endpoints described here allow a PISP to: 

• Register an intent to setup a payment instruction 

• Subsequently submit the payment instruction for processing

• Optionally retrieve the status of a payment setup or submission.

Document Overview

This document consists of the following parts:

Overview: Provides an overview of the scope 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 single, immediate, domestic 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

RESTful APIs

The API adheres to RESTful API concepts where possible and sensible to do so.

However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.

References:

• The highest level Data Description Language used is the JSON Schema : http://json-schema.org/

• Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/

• The Interface Description Language used is the Swagger Specification version 2.0 (also known as Open API) : http://swagger.io/ and 

   

Standards

The OBIE principles for developing the new API standards:

• OBIE will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.

• The initial scope of these Standards is limited to current OBIE scope - i.e., meeting CMA remedies. However, the intention is that the scope of the Standards will extend to either include or align to initiatives to cover a wider scope (i.e., PSD2).

• The Standards currently being reviewed include ISO20022, and FAPI.

• OBIE will favour developer/user experience over and above adoption of existing Standards, in order to create a more future proof Standard.

• OBIE will work with other relevant bodies to align with, contribute to and/or adopt other Standards work, especially relating to creation of Standards around APIs and JSON payloads.

ISO 20022

The CMA Order requires the CMA9 Banks to be aligned with the Regulatory and Technical Standards (RTS) under PSD2.

A previous draft of the EBA RTS required that the interface "shall use ISO 20022 elements, components or approved message definitions". In keeping with that requirement, the API payloads are designed using the ISO 20022 message elements and components where available.

The principles we have applied to re-use of ISO message elements and components are:

• Where relevant - the API payloads have been flattened so that they are more developer friendly. This has been a request from the developer community, and the stakeholders involved in the design workshop.

• Only elements that are required for the functioning of the API endpoint will be included in the API payload. API endpoints are defined for specific use-cases (not to be generically extensible for all use-cases). Hence - only elements that are required for a single immediate payment initiation are included in the Payment API payload for v1.0 (as this is the agreed scope for our v1.0 specification).

• We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.). An example is having latitude and longitude in decimal format - as this is how developers will work with latitude and longitude; or using simple types (e.g., a single date-time field) instead of a complex type (e.g., a choice field with a nesting of date and time).

Extensibility

Version 1.0 of the Payment API only caters for the setup and submission of a single, immediate, domestic payment.

However, it is intended that the API flows will be extended to cater for more complex use-cases in subsequent releases - and we have kept this in mind during the design. It is expected that the API payloads will evolve to cater for other payment types (e.g., future dated, recurring, bulk etc.)

Idempotency

POST operations on both the /payments and /payment-submissions endpoint are designed to be idempotent. 

Details on idempotency can be founds in the section on Basics / Idempotency.

Non-Repudiation

The APIs will provide non-repudiation through digital signatures.

The specifications required to achieve this are described in Basics / Non-repudiation.

Payment API - 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 FPS and Bacs schemes.

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

• The Status field in the Payment API payloads reflect the status of the payments and payment-submissions resources. This Status will be limited to the ISO 20022 PaymentStatusCode code-list enumeration for v1.0.

Scope

The APIs in this document allow a PISP to initiate a single, immediate, domestic payments made in GBP.

Out of Scope

This v1.0 specification does not cater for:

• Payments that involve currency exchange.

• Payments that involve currencies other than GBP (no validation of EUR payment schemes has been completed for v1.0).

• Payments that are not single, immediate, domestic payments made in GBP - i.e., payments that are:

  • In bulk - single debit, multiple credit

  • Future dated or deferred

  • Recurring.

• Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are not included in this version.

• Non-functional requirements and specification of caching and throttling.

Basics

Overview

The figure below provides a general outline of a payment flow using the Payment APIs.

Open

Steps

Step 1: Request Payment Intitation

• This flow begins with a PSU consenting to a payment being made. The request is sent through a PISP.

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

Step 2: Setup Single Payment Initiation

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

• This step is carried out by making a POST request to the payments resource.

Step 3: Authorise Consent

• The PISP redirects the PSU to the ASPSP. The redirect includes the PaymentId generated in the previous step. This allows the ASPSP to correlate the payment that was setup. The ASPSP authenticates the PSU. This could be an SCA if the ASPSP determines that none of the SCA exemptions apply. The ASPSP updates the state of the payments resource internally to indicate that the payment has been authorized.

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

• The PSU is redirected back to the PISP.

Step 4: Create Payment Submission

• Once the PSU is redirected to the PISP, the PISP creates a payment-submissions 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 payment-submissions resource.

• ASPSP returns the PaymentSubmissionId to the PISP.

Step 5: Get Payment Submission Status

• If the ASPSP provides a status API, the PISP can check the status of the payment (with the PaymentId) or payment-submission (with the PaymentSubmissionId).

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

Sequence Diagram

Open

Payment Initiation - High Level Flow

Actors

Headers

Request Headers

(Reference: Section 6.3 - Financial API — Part 1: Read Only API Security Profile (Implementer’s Draft).)

Response Headers

Return & Error Codes

The following are the HTTP response codes for the different HTTP methods - across all Payment API endpoints.

An ASPSP MAY return other standard HTTP status codes (e.g. from gateways and other edge devices) as described in RFC 7231 - Section 6.

400 (Bad Request) v/s 404 (Not Found)

When a TPP tries to request a resource URL with an resource Id that does not exist, the ASPSP must respond with a 400 (Bad Request) rather than a 404 (Not Found).

E.g., if a TPP tries to GET /payments/22289 where 22289 is not a valid PaymentId, the ASPSP must respond with a 400.

If the TPP tries to access a URL for a resource that is not defined by these specifications (e.g. GET /card-accounts), the ASPSP may choose to respond with a 404 (Not Found).

If an ASPSP has not implemented an optional API, it must respond with a 404 (Not Found) for requests to that URL.

The table below illustrates some examples of expected behaviour:

403 (Forbidden)

When a TPP tries to access a resource that it does not have permission to access, the ASPSP must return a 403 (Forbidden).

The situation could arise when:

• The TPP uses an access token that is no longer valid

• The TPP uses an access token that does not have the approporiate scope to access the requested resource.

• The TPP attempted to access a resource with an Id that it does not have access to. E.g., an attempt to access GET /payments/1001 where a payment resource with id 1001 belongs to another TPP.

429 (Too Many Requests)

When a TPP tries to access a resource too frequently the ASPSP may return a 429 (Too Many Requests).  This is a Non Functional Requirement and is down to individual ASPSPs to decide throttling limits. 

This situation could arise when:

• A TPP decides to implement "Real Time Payment Status" functionality for its users and implements this badly by polling a GET endpoint or an Idempotent POST endpoint once-per-second constantly to provide pseudo "real-time" Status updates to the user.

• A TPP decides to use the Single Immediate Payment endpoint as if it were a BATCH payment facility and sends 1,000 payment requests in a very short space of time. 

Pre-Conditions

The following pre-conditions must be satisfied in order to use these APIs:

Pre-conditions for TPPs

1. The TPP must have completed onboarding on the Open Banking Directory.

2. The TPP must have registered one or more software statements with the Open Banking Directory. The software statement must have "payments" as one of the required scopes.

3. The TPP must have valid network and signing certificates issued by Open Banking.

4. The TPP must have completed registration with each of the ASPSPs that it wants to transact with and have been issued with a client-id.

Pre-conditions for ASPSPs

1. The ASPSP must have completed onboarding on the Open Banking Directory.

2. The ASPSP must have valid network and signing certificates issued by Open Banking.

Idempotency

The APIs for creating payment and payment-submission resources are idempotent. The intent of this capability is to allow PISP to retry API requests that failed with a timeout or an unexpected error. 

The Idempotency key provided in the header must be at most 40 characters in size. If a larger idempotency key length is provided, the ASPSP must reject the request with a status code is 400 (Bad Request).

The PISP must not change the request body while using the same Idempotency Key. If the PISP changes the request body, the ASPSP must not modify the end resource. The ASPSP may treat this as a fraudulent action.

An ASPSP must treat a request as idempotent if it had received the first request with the same Idempotency Key from the same PISP in the preceding 24 hours. 

The ASPSP must not create a new resource for a POST request if it is determined to be an idempotent request.

The ASPSP must respond to the request with the current status of the resource (or a status which is at least as current as what's available on existing online channels) and a HTTP status code of 201 (Created).

The PISP must not use the idempotent behaviour to poll the status of the payment resource or payment-submission resource.

An ASPSP may use the message signature (if implemented) along with the Idempotency Key to ensure that the request body has not changed.

Non-repudiation

Overview

The APIs require TLS 1.2 Mutual Authentication and this can be used as a means of non-repudiation. However, it would be difficult to maintain digital records and evidence of non-repudiation if the API only relied on TLS 1.2.