Version Control

Release Note

This release note explains what's new in the Payment Initiation API Specifications v1.1.0.

Fixes

• In Accounts Transactions sequence diagram, removed Step 4 Request data response to the PSU.

• Corrected the case for Links.First, Links.Last, Links.Next, Links.Prev, Links.Self and Meta.TotalPages (updated Basics/Pagination, Basics / Return & Error Codes / 400 (Bad Request) v/s 404 (Not Found), and Data Model / High Level Payload Structure / Response Structure).
• Removed special characters in the Frequency field for Data Model / Data Payload - Resources / Standing Orders / Data Dictionary.
• Corrected the Pattern for the ActiveOrHistoricCurrencyCode class from [A-Z]{3,3} to ^[A-Z]{3,3}$ to limit the field to 3 characters.
• Corrected the Pattern for the CountryCode class to be specified as ^[A-Z]{2,2}$ instead of [A-Z]{2,2} to limit the field to 2 characters.
• In Usage Examples, have corrected "AwaitingAuthentication" to "AwaitingAuthorisation"
• Updated Usage Example for /products endpoint to align with Data Dictionary.
• Updated Pagination Response JSON payload to correctly separate one of the JSON properties by inclusion of a comma.
• Corrected a mis-spelling from "UFT-8" to "UTF-8".

Clarifications

• Added details and updated examples on the various date formats used outside of the JSON payload (updated Examples, Basics / Date formats, and Basics / Non-repudiation / Process for signing a payload).
• Clarified that Timezone offsets of -00:00 are not permitted in ISO-8601 (updated Examples, and all default dates in Data Model / Data payload - resources).
• Clarified that all dates in HTTP headers are represented as RFC 7231 Full Dates. For example: Sun 3 Sep 2017 19:43:31 UTC
• Clarified that a status of 403 should not be used to indicate a time-out of the access token, and that a 403 indicates that re-authentication of the PSU will not help.
• Clarified that digital signatures must NOT be implemented for v1.x specification.

Enhancements

• Metadata fields in the /transactions response now include an earliest available transaction date AND a latest available transaction date (updated Examples, Data Model / High Level Payload Structure / Response Structure / Meta, and default values specified in the Data Payload sections).
• Added a new section to cater for reversals (Security & Access Control / Consent Authorization / Permissions / Reversing Entries).
• Added a new section to specify the default character set as UTF-8 (Basics / Character Encoding). 
• All datetime fields returned by the API must have the Timezone specified (updated Examples and added a new section Basics / Date Format).
• Specified min and max page sizes for pagination (updated section on Basics / Pagination).

• Sort Code and Account Number are now stored in the Account identification section together (in the Identification field), and a new SchemeName has been created for SortCodeAccountNumber (updated Examples, Data Model / Data Payload - Resources / Accounts / Data Dictionary, Data Model / Data Payload - Resources / Beneficiaries / Data Dictionary, Data Model / Data Payload - Resources / Standing Orders / Data Dictionary, and Data Model / Data Payload - Enumerations).

• Extended the Standing Order Frequency pattern to include weekends and clarified pattern description (updated Data Model / Data Payload - Resources / Standing Orders / Data Dictionary).
• Changed the BankTransactionCode to be the ISO 20022 code description, with all delimiters removed (updated Data Model / Data Payload - Resources / Transactions).
• Add a Retry-After header for the HTTP 429 Too Many Requests response (updated Basics / Return & Error Codes, Basics / Headers / Response Headers, and Alternate Error Flows showing 429 as an optional implementation).

• Added 405 and 406 as status codes (updated section on Basics / Response Headers).

• Added clarifications to the Pagination section to state that the self link must be included in the response (Updated section Basic / Pagination).

• Added a section describing resource URL path structures.

• Added regex pattern for all Amount based fields under the Data Model / Data Payload. Removed pattern definition TotalDigits: 18 FractionDigits: 5.

• Swagger Specification updated to include the Swagger Specification version number in the base of the URL (i.e. linked to this Specification).

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

Digital signatures will facilitate non-repudiation for Open Banking APIs. 

However, the solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is 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 in the "Mapping to Schemes & Standards" section.

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.

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

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
note over PSU, ASPSP Resource Server
Step 1: Request payment initiation
end note
PSU -> PISP: Send payment initiation request

note over PSU, ASPSP Resource Server
 Setup single payment initiation
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 /payments
ASPSP Resource Server -> PISP: HTTP 201 (Created),  PaymentId
PISP -> PSU: HTTP 302 (Found), Redirect (PaymentId)

note over PSU, ASPSP Resource Server
 Step 3: Authorize consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (PaymentId)
PSU <-> ASPSP Authorisation Server: authenticate
PSU <-> ASPSP Authorisation Server: SCA if required
PSU <-> ASPSP Authorisation Server: Select debtor account
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

  
note over PSU, ASPSP Resource Server
Step 4: Create payment submission
end note
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentSubmissionId

note over PSU, ASPSP Resource Server
Step 5: Get payment submission status
end note

opt 
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId}
ASPSP Resource Server -> PISP: HTTP 200 (OK) payment-submissions resource
end opt

Actors

Character Encoding

The API requests and responses must use a  UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - Section 8.1)

However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "Happy Birthday 🎂🎂!" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP should respond with an HTTP 400 (Bad Request) status code.

Date Formats

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below:

2017-04-05T10:43:07+00:00

All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

Sun, 10 Sep 2017 19:43:31 UTC

JWT claims are expressed as a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

Resource URI Path Structure

The resources defined by these APIs can be addressed through a path structure consisting of the following parts:

• An optional ASPSP specific path prefix
• The constant string "open-banking"
• The version of the APIs expressed as /v[major-version].[minor-version]/
• The resource name

Examples:

/superbank/open-banking/v1.1/payments

/open-banking/v1.0/payments

/apis/open-banking/v1.1/payments

Payment Limits

The standard does not provide a uniform limit for payments that can be supported through this API.

Each ASPSP must determine an appropriate limit that they support based on their individual practices, standards and limitations.

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

When the TPP uses an access token that is no longer valid, the situation could potentially be remedied by asking the PSU to re-authenticate. This should be indicated by a 401 (Unauthorized) status code.

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

The solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / 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.

A solution for non-repudiation that does not rely on TLS, would be achieved by providing a JWS with detached content (as defined in RFC 7515 - Appendix F) in the HTTP header of each API request.

The HTTP body would form an un-encoded payload as defined in RFC 7797.

The JWS would be signed using an algorithm that supports asymmetric keys.

A request would be signed by a TPP's private key  and a response would be signed by the ASPSP's private key.

OB Directory will provide and host the necessary certificates containing the corresponding public keys so that hte signature can be verified.

Specification

The TPP must sign the HTTP body of each API request that has an HTTP body. (e.g. GET requests do not have an HTTP body and are not signed.)

The ASPSP must sign the HTTP body of each API response that it produces which has an HTTP body.

The ASPSP should verify the signature of API requests that it receives before carrying out the request. If the signature fails validation, the ASPSP must respond with a 400 (Bad Request).

The ASPSP must reject any API requests that should be signed but do not contain a signature in the HTTP header with a 400 (Bad Request) error.

The TPP should verify the signature of API responses that it receives.

Process for signing a payload

Step 1: Identify the private key and corresponding signing certificate to be used for signing

The signer must use a private key that has a corresponding digital certificate (that contains the corresponding public key) issued by OB.

The signing certificate must be valid at the time of creating the JWS.

Step 2: Form the JOSE Header

The JOSE header for the signature must contain the following fields

Step 3: Compute the JWS

The signer must compute the signature as a detached JWS as defined in RFC 7515.

payload = base64Encode (JOSEHeader) + "." + base64Encode( json)
detachedJWS = base64Encode( JOSEHeader) + ".." + base64Encode ( encrypt (privateKey, base64Encode(json)))

Step 4: Add the JWS as a HTTP header 

The signer must include an HTTP header called x-jws-signature with its value set to the signature computed in Step 3.

x-jws-signature: V2hhdCBoYXRoIGdvZCB3cm91Z2h0ID8=..QnkgR2VvcmdlLCBzaGUncyBnb3QgaXQhIEJ5IEdlb3JnZSBzaGUncyBnb3QgaXQhIE5vdyBvbmNlIGFnYWluLCB3aGVyZSBkb2VzIGl0IHJhaW4/

Process for verifying a signature

Step 1: Extract the components from the JWS 

The verifier must extract and decode the JOSE header and signature from the JWS provided in the x-jws-signature http header

JWSParts[] = detachedJWS.tokenize("..");
JOSEHeader = base64Decode (JWSParts[0]);
Signature = JWSParts[1];
ExpectedSignedPayload = JWSParts[0] + "." + base64Encode( httpBody)

Step 2: Validate the JOSE header and certificate

The verifier must validate the JOSE header to ensure that it is a valid json object with only the claims specified in Process for Signing a Payload - Step 2.

The verifier must ensure that the specified alg is one of the algorithms specified by OB.

The verifier must ensure that the specified kid is valid and a signing certificate with the specified key id can be retrieved from the OB directory.

The verifier must ensure that the certificate is valid.

The verifier must ensure that the b64 claim is set to false.

The verifier must ensure that the http://openbanking.org.uk/iat claim has a date-time value set in the past.

The veriier must ensure that the http://openbanking.org.uk/iss claim matches the dn of the certificate.

The verifier must ensure that the crit claim does not contain additional critical elements.

Step 3: Verify the signature

The verifier must verify the signature by decrypting it and ensuring that it matches the ExpectedSignedPayload.

DecryptedPayload = base64Decode ( decrypt ( publicKey, Signature));

Sample JOSE Header

{
	"alg": "RS512",
	"kid": "90210ABAD",
	"b64": false,
	"http://openbanking.org.uk/iat": 1501497671,
	"http://openbanking.org.uk/iss": "C=UK, ST=England, L=London, O=Acme Ltd.",
	"crit": [ "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"]
]

Filtering

The Payment APIs do not support filtering.

Pagination

The Payment APIs do not support pagination.

Regulatory Considerations

PSD2 - Article 48

Immediately after receipt of the payment order, the payer’s payment service provider shall provide the payer with or make available to the payer, all of the following data with regard to its own services:
(a) a reference enabling the payer to identify the payment transaction and, where appropriate, information relating to the payee;
(b) the amount of the payment transaction in the currency used in the payment order;
(c) the amount of any charges for the payment transaction payable by the payer and, where applicable, a breakdown of the amounts of such charges;
(d) where applicable, the exchange rate used in the payment transaction by the payer’s payment service provider or a reference thereto, when different from the rate provided in accordance with point (d) of Article 45(1), and the amount of the payment transaction after that currency conversion;

ASPSPs can address this requirement by providing this information to PSUs just after they have completed "Step 3: Authorize payment instruction", but before they are redirected back to the PISP.

RTS - Article 13

Trusted beneficiaries and recurring transactions:

1. Subject to paragraph 2 of this Article and to compliance with the requirements laid down in paragraphs 1, 2 and 3 of Article 2, payment service providers are exempted from the application of strong customer authentication in each of the following situations:
(a) the payer initiates a payment transaction where the payee is included in a list of trusted beneficiaries previously created or confirmed by the payer through its account servicing payment service provider;
(b) the payer initiates a series of payment transactions with the same amount and the same payee.

ASPSPs can address this requirement of the RTS by checking whether the Creditor Account is one of the accounts that is a trusted beneficiary of the PSU. The ASPSP would be exempted from carrying out SCA in such situations.

RTS - Article 14

Payments to self
Subject to compliance with the requirements laid down in paragraphs 1, 2 and 3 of Article 2, payment service providers are exempted from the application of strong customer authentication where the payer initiates a credit transfer where the payer and the payee are the same natural or legal person and both payment accounts are held by the same account servicing payment service provider.

ASPSPs can address this requirement by checking if the Creditor Account belongs to the same PSU. The ASPSP would be exempted from carrying out SCA in such situations.

RTS - Article 15

Low-value transaction
Subject to compliance with the requirements laid down in paragraphs 1, 2 and 3 of Article 2, payment service providers are exempted from the application of strong customer authentication, where the payer initiates a remote electronic payment transaction provided that both the following conditions are met:
(a) the amount of the remote electronic payment transaction does not exceed EUR 30;
(b) the cumulative amount, or the number, of previous remote electronic payment transactions initiated by the payer since the last application of strong customer authentication does not, respectively, exceed EUR 100 or 5 consecutive individual remote electronic payment transactions.

At the point of consent authorisation, the ASPSP will be able to determine if the transaction is a low value transaction.

The ASPSP would additionally need to keep track of previous transactions in order to determine if it can be exempted from carrying out SCA.

Endpoints

This section looks at the list of available API endpoints to complete a Payment flow. For detail on the request and response objects - refer to the Data Model section of the specification.

The ASPSP must implement the API end-points in the table below that are marked as mandatory.

The ASPSP may optionally implement the API end-points that are marked as non-mandatory.

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

Endpoint design considerations:

• Having a separate resource for the payment setup and payment submission means we can extend the flows in the future more easily for bulk and recurring payments. 
• Separation in setup and submission also allows for cleaner separation in updating the status of resources - for ASPSPs that chose to implement the functionally

POST /payments 

POST /payments

The API allows the PISP to ask an ASPSP to create a new payment resource.

• This indicates to the ASPSP that a payment should be initiated. At this stage, 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.
• This API effectively allows the PISP to send a copy of the consent to the ASPSP to authorise for this payment.
• The ASPSP creates the payments resource and responds with a unique PaymentId to refer to the resource.

Payment Status

The state model for the Status field is in the Mapping to Schemes & Standards section. The Status field for the Payment API follows the behaviour and definitions for the ISO 20022 PaymentStatusCode code-set.

The payment resource that is created successfully must have one of the following PaymentStatusCode code-set:

GET /payments/{PaymentId}

GET /payments/{PaymentId}

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

Payment Status

Once the PSU authorises the payment resource - the Status of the payment resource will be updated with AcceptedCustomerProfile.

The available PaymentStatusCode code-set enumerations for the payment resource are:

POST /payment-submissions

POST /payment-submissions/

Once the payment has been authorised by the PSU, the PISP can proceed to submitting the payment for processing:

• This is done by making a POST request to the payment-submissions resource.
• This request is an instruction to the ASPSP to begin the single immediate payment journey. The payment will be submitted immediately, however, there are some scenarios where the payment may not happen immediately (e.g. busy periods at the ASPSP).
• The PISP must ensure that the Initiation and Risk sections of the payment submission match the corresponding Initiation and Risk sections of the original payment 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 payment-submission resource will not result in a Status change for the payment resource.

Payment Submission Status

A payment-submission can only be created if its corresponding payment resource has the status of 'AcceptedCustomerProfile'. 

The payment-submission resource that is created successfully must have one of the following PaymentStatusCode code-set enumerations:

GET /payment-submissions/{PaymentSubmissionId}

GET/payment-submissions/{PaymentSubmissionId}

A PISP can retrieve the payment-submission to check its status.

Payment Submission Status

The payment-submission resource must have one of the following PaymentStatusCode code-set enumerations:

Security & Access Control

API Scopes

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

payments

Grants Types

PISPs must use a client credentials grant to obtain a token to make POST requests to the payments resource.

PISPs must use a authorization code grant to obtain a token to make POST requests to the payment-submissions resource.

PISPs may use a either a client credentials grant or an authorization code 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 single immediate payment request by creating a payments resource through a POST operation. This resource indicates 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 PaymentId. 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 entirity (but not selectively).
• If the consent did not indicate a debtor account, the ASPSP presents the PSU 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.

Payment Status

The Payment resource can have one of the following ISO status codes after authorisation has taken place:

Error Condition

If the PSU does not complete a successful consent authorisation (e.g. if the PSU is not authenticated successfully), the authorization code grant ends with a redirection to the TPP with an error response as described in RFC 6749 Section 4.1.2.1. The PSU is redirected to the TPP with a error parameter indicating the error that occoured.

Consent Revocation

A PSU cannot revoke consent for a single immediate payment - once it has been authorized.

This is required to comply with Article 80 of PSD2.

Changes to Selected Account

For a single immediate payment, the selected debtor account cannot be changed once the consent has been authorized.

Handling Expired Access Tokens

Access Token issued through Client Credentials Grant

When an access token issued through a Client Credentials Grant expires, the TPP must get a new access token by executing a client credential grant again.

Access Token issued through Authorization Code Grant

Due to the immediate nature of single immediate payments, an access token is unlikely to expire before it is used for creating the payment-submission. Consequently, issuing a refresh token along with the access token is not useful in this situation.

However, to simplify their implementation, an ASPSP may issue a refresh token along with an access token at the end of an authorisation code grant.

When an access token obtained through an authorisation code grant expires, the TPP may attempt to get a new access and refresh token as defined in Section 6 of the OAuth 2.0 specification.

If the TPP fails to get an access token using a refresh token, the TPP would have to get the PSU to initiate a fresh authorisation code grant using an existing intent-id.

An ASPSP may choose to simplify their implementation by ensuring that the tokens and consent authorisation have the same period of validity - in such a situation, the tokens will not expire within the lifetime of the consent authorisation and subsequently the ability to re-authenticate will not be required.

Risk Scoring Information

During the design workshops ASPSPs articulated a need to perform risk scoring on the payments initiated via the Payment API.

Information for risk scoring and assessment will come via:

• FAPI HTTP headers. These are defined in Section 6.3 of the FAPI specification and in the Headers section above.
• Additional fields identified by the industry as business logic security concerns - which will be passed in the Risk section of the payload in the JSON object. 

These are the set of additional fields in the risk section of the payload for v1.0 - which will be specified by the PISP:

• PaymentContextCode
• MerchantCategoryCode
• MerchantCustomerIdentification
• DeliveryAddress

The PaymentContextCode describes the payment context and can have these values:

• BillPayment
• EcommerceGoods
• EcommerceServices
• Other
• PersonToPerson

Payments for EcommerceGoods and EcommerceServices will be expected to have a MerchantCategoryCode and MerchantCustomerIdentification populated. Payments for EcommerceGoods will also have the DeliveryAddress populated.

These fields are documented further in the Data Payload section.

Swagger Specification

The Swagger Specification (v1.1.0) for Payment Initiation APIs can be downloaded from the following links:

•  PDF
•  JSON
•  YAML

Data Model

High Level Payload Structure

This section gives an overview of the top level structure for the API payloads for the Payment APIs.

The Data and Risk sections of the payload structure are documented in Data Dictionary section; while the Links and Meta are standardised - which are explained in the Response Structure.

Request Structure

The top level request structure for Payment APIs:

{
  "Data": {
    "Initiation": {
    ...
    }
  },
  "Risk": {
  ...
  }
}

The top level structure for the Payment API POST requests will be:

• Data

  • Initiation

• Risk

The Data section contains the payment initiation object.

A separate Initiation section within the Data section gives us the flexibility to extend and modify the Initiation section in isolation.

A Risk section for the request structure has been separated out - so that this can evolve in isolation from the Initiate section of the payload.

Response Structure

The top level response structure for Payment APIs:

{
  "Data": {
    ...
    "Initiation": {
    ...
    }
  },
  "Risk": {
    ...
  },
  "Links": {
    ...
  },
  "Meta": {
    ...
  }
}

In line with the principle on RESTful API practices - we are replaying the full resource as part of the response.

Two additional top level sections are included in the response for:

• Links

• Meta

Links

The Links section is mandatory and will always contain URIs to related resources, 

The "Self" member is mandatory, the other members  "First", "Prev", "Next", "Last"  are optional.

For example:

  "Links": {
    "Self": "http://example.com/articles?page[number]=3&page[size]=1",
    "First": "http://example.com/articles?page[number]=1&page[size]=1",
    "Prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "Next": "http://example.com/articles?page[number]=4&page[size]=1",
    "Last": "http://example.com/articles?page[number]=13&page[size]=1"
  }

Meta

The Meta section is mandatory, but can be empty.  An optional member is "TotalPages" which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.

For example:

  "Meta": {
    "TotalPages": 13
  }

Data Payload

The data dictionary section gives the detail on the payload content for the Payment API flows.

UML diagram notes:

• All amount fields across the API endpoints use the ISO 20022 ActiveOrHistoricCurrencyAndAmount class. This is an XML attribute (with an embedded Currency field). Due to the limitations of the XML tool - the Currency field does not show in the UML diagram - however, is reflected in the Data Dictionary.

Payment Setup - Request

The OBPaymentSetup1 object will be used for the call to:

• POST /payments

UML Diagram

Notes

• The DebtorAgent and DebtorAccount are optional - as the PISP may not know the account identification details for the PSU.
• If the DebtorAgent and DebtorAccount are specified by the PISP - then the account identification details for the Payment resource cannot be changed - as this is part of formal consent from the PSU. If the DebtorAgent and DebtorAccount are not valid for the PSU - then the payment will be rejected.
• 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); and the Servicer identification section (either DebtorAgent or CreditorAgent) must not be populated
• 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; and the Servicer identification section (either DebtorAgent or CreditorAgent) should be populated with the "BICFI" as the SchemeName
• The element Reference has been renamed from CreditorReferenceInformation - as this is the unique ISO 20022 element used in pain.001, rather than a ISO 20022 message component.
• As a merchant may be initiating a payment via a PISP - two identifiers are included in the payload: 
  • InstructionIdentification is uniquely generated by the PISP - the expectation is that this is unique indefinitely across all time periods. The PISP can ensure this is indefinitely unique by including a date or date time element to the field, or by inserting a unique Id. 
  • EndToEndIdentification is uniquely generated by the merchant.
• Neither the InstructionIdentification nor EndToEndIdentification will be used as the payment resource identifier (PaymentId) - as the PaymentId must be uniquely generated by the ASPSP.
• Design decisions for the Initiation section of the payload - and how this maps to the ISO 20022 messaging standard are articulated in the Mapping to Schemes and Standards section.

Data Dictionary

Payment Setup - Response

The OBPaymentSetupResponse1 object will be used for a response to a call to:

• POST /payments
• GET /payments/{PaymentId}

UML Diagram

Notes

The Payment Setup response contains the full original payload from the Payment Setup POST request - with these additional elements:

• PaymentId.
• Status of the Payment resource.
• Date time the Payment resource was created.

Data Dictionary

Payment Submission - Request

The OBPaymentSubmission1 object will be used for a call to:

• POST /payment-submissions

UML Diagram

Notes

The payment-submission request object contains the: 

• PaymentId
• The full payload from the payment setup request (including the Initiation and Risk sections)

The Initiation and Risk sections of the payment-submission request must match the Initiation and Risk sections of the corresponding payment setup request.

Data Dictionary

Payment Submission - Response

The OBPaymentSubmissionResponse1 object will be used for a response to a call to:

• POST /payment-submissions
• GET /payment-submissions/{PaymentSubmissionId}

UML Diagram

Notes

The Payment Submission POST response contains the: 

• PaymentSubmissionId
• PaymentId
• Status of the payment-submission resource
• Date time the payment-submission resource was created

Data Dictionary

Data Payload - Enumerations

This section gives the definitions for enumerations used in the Payment APIs.

Identifier Fields

This section describes the identifiers used through the Payment API flows - the direction of flow through the system, and how they are used.

The standard definitions for the elements in the API payloads are described in the Data Payload section. However, this table gives further detail on the business meaning, and how they are used.

The tables below identify the actor that initially creates each of the message identifiers and their transmission and visibility to other actors.

These flows are indicative - and will be dependent on what payment schemes or agencies are able to support.

Key:

O indicates the actor that creates the identifier.

=> downstream direction of flow

<= upstream direction of flow

Merchant Flow

Person to Person Flow

Mapping to Schemes & Standards

ISO 20022

The Initiation section of the Payment API payloads is based on the ISO 20022 pain.001 XML standard - and we have used ISO 20022 message elements or components - where possible. However - has been adapted for APIs based as per our design principles. 

Deviations from the pain.001 XML standard are:

• The pain.001 header section and trailer sections have been removed - as these are not required for a RESTful API
• Only fields required for the v1.0 scope of single-debit single-credit GBP payments, immediately executed are included in the payload. This has meant:
  • The separate CreditTransferTransactionInformation section in pain.001 - which is a repeating group for multi-credit payments has been removed and flattened
  • PaymentInformationIdentification not required - we also have a InstructionIdentification
  • PaymentMethod not required - as this is always immediate execution for the ASPSP
  • RequestedExecutionDate not required - as this is always as soon as possible - which may differ between FPS and Bacs payments
  • Debtor / DebtorAgent / DebtorAccount are optional - as the debtor details are not always known to the PISP submitting the payment setup or submit
• The Payment Initiation team has requested a flatter structure for the payload:
  • InstructionIdentification and EndToEndIdentification moved to the top level (instead of embedding within PaymentIdentification) 
  • DebtorAgent and CreditorAgent are simplified to only include the SchemeName and Identification
  • DebtorAccount and CreditorAccount are simplified to only include the SchemeName and Identification

Transaction Status

A principle has been agreed to adhere to the ISO Transaction Status codes. 

The ISO Transaction Status has been split into statuses for the payment setup resource, and the payment-submission resource.

Faster Payments

Execution:

• The processing of payments via the FPS scheme is business as usual processing - i.e., no change
• FPS scheme requirements (in draft, and not part of the Open Banking API specification):
  • The field 61.1 PAYMENT SUB-TYPE will be set by the FPS Institution with a A{**} prefix for any FPS transaction initiated by a PISP. Values within {**} will ordinarily be “00” unless the PISP initiated payment requires usage of other facilities (as indicated by usage of an FPS sub-type code). 
  • There is also a requirement from the FPS scheme to identify the PISP - via the field 122 REGULATORY REPORTING  

This is the mapping from the Payment API - Initiation section to the relevant FPS scheme fields - with the use of the "SortCodeAccountNumber" account identification SchemeName.

All required fields in the FPS ISO8583 message can all be generated from the Initiate section of the API payload, or from the ASPSP.

Highlighted in red are the fields which are smaller in size than the corresponding ISO 20022 field.

In the case that a PISP sets up a payment resource with a larger field size (e.g., EndToEndIdentification, or InstructedAmount) than the eventual scheme field size - it will be up to the ASPSP to decide whether to reject the payment setup, or truncate the field.

Notes:

• If the Initiation/CreditorAccount/SecondaryIdentification field is populated - we expect this to be mapped to field 120 REFERENCE INFORMATION - as this will be used for the Creditor Agent to identify the account (i.e., the roll numbers in the building society context)
• However - if the /CreditorAccount/SecondaryIdentification is not populated - then we expect field 120 REFERENCE INFORMATION to be populated with the Initiation/RemittanceInformation/Reference field
• If both Initiation/CreditorAccount/SecondaryIdentification and Initiation/RemittanceInformation/Reference are populated by the PISP - only the SecondaryIdentification will be mapped for use in the payment rails (i.e., FPS or Bacs). Whether the Reference is used in any other ASPSP systems is for the ASPSP to decide.
  
• The FPS Field 116 - the ORIGINATING CUSTOMER ACCOUNT NAME - should be populated from the ASPSP's system of record
• Where the Initiation/DebtorAccount/SchemeName field is populated with "SortCodeAccountNumber" the Initiation/DebtorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to ORIGINATING CREDIT INSTITUTION) and 8 digit Account Number (mapped to ORIGINATING CUSTOMER ACCOUNT NUMBER)
• Where the Initiation/CreditorAccount/SchemeName field is populated with "SortCodeAccountNumber" the Initiation/CreditorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to BENEFICIARY CREDIT INSTITUTION) and 8 digit Account Number (mapped to BENEFICIARY CUSTOMER ACCOUNT NUMBER)

Bacs

Execution:

• The processing of payments via the Bacs scheme is business as usual processing - i.e., no change
• Expectation is that a Bank Grade user will be able to bulk up payments generated via the Payment API - and create the appropriate file and submission structure (as per usual processing) - none of these details will need to be generated via the Payment API
• The mapping below uses the Bacs Electronic Funds Transfer, File Structures (PN5011) document - and the section on 2.6.1 CREDIT AND DEBIT PAYMENT INSTRUCTIONS (BANK GRADE USERS)

This is the mapping from the Payment API - Initiation section to the relevant Bacs scheme fields - with the use of the "SortCodeAccountNumber" account identification SchemeName.

All required fields in the Bacs STD18 message can all be generated from the Initiate section of the API payload, or from the ASPSP.

Highlighted in red are the fields which are smaller in size than the corresponding ISO 20022 field. 

In the case that a PISP sets up a payment resource with a larger field size (e.g., EndToEndIdentification, or InstructedAmount) than the eventual scheme field size - it will be up to the ASPSP to decide whether to reject the payment setup, or truncate the field. 

Notes:

• If the Initiation/CreditorAccount/SecondaryIdentification field is populated - we expect this to be mapped to field 10 service user's reference - as this will be used for the Creditor Agent to identify the account(i.e., the roll numbers in the building society context)
• However - if the /CreditorAccount/SecondaryIdentification is not populated - then we expect field 10 service user's reference to be populated with the Initiation/RemittanceInformation/Reference field
• If both Initiation/CreditorAccount/SecondaryIdentification and Initiation/RemittanceInformation/Reference are populated by the PISP - only the SecondaryIdentification will be mapped for use in the payment rails (i.e., FPS or Bacs). Whether the Reference is used in any other ASPSP systems is for the ASPSP to decide.
• The Bacs Field 9 - the service user's name - should be populated from the ASPSP's system of record
• Where the Initiation/DebtorAccount/SchemeName field is populated with "SortCodeAccountNumber" the Initiation/DebtorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to originating sorting code) and 8 digit Account Number (mapped to originating account number)
• Where the Initiation/CreditorAccount/SchemeName field is populated with "SortCodeAccountNumber" the Initiation/CreditorAccount/Identification field will be populated with a 14 digit field comprised of a 6 digit Sort Code (mapped to destination sorting code) and 8 digit Account Number (mapped to destination a/c number)

Usage Examples

Merchant

This example set of flows and payload examples are for a payment initiated by a merchant via a PISP.

In this scenario:

• The merchant has not specified the Debtor Account details for the the PSU - the PSU will select their account during the authorisation of consent
• The merchant's account is a building society account - with a roll number specified in the SecondaryIdentification field

Sequence Diagram

participant PSU
participant Merchant
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
note over PSU, ASPSP Resource Server
Step 1: Request payment initiation
end note
PSU -> Merchant: Check-out and pay
Merchant -> PISP: Send request to setup single immediate payment initiation

note over PSU, ASPSP Resource Server
Step 2: Setup single payment initiation
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 /payments
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentId
PISP -> Merchant: HTTP 302 (Found), Redirect (PaymentId)
Merchant -> PSU: HTTP 302 (Found), Redirect (PaymentId)

note over PSU, ASPSP Resource Server
Step 3: Authorize consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (PaymentId)
PSU <-> ASPSP Authorisation Server: authenticate
PSU <-> ASPSP Authorisation Server: SCA if required
PSU <-> ASPSP Authorisation Server: Select debtor account
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
PISP -> PSU: HTTP 302 (Found), Redirect back to merchant
PSU -> Merchant: Follow redirect
Merchant --> PISP: Check payment status

note over PSU, ASPSP Resource Server
Step 4: Create payment submission
end note
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentSubmissionId

note over PSU, ASPSP Resource Server
Step 5: Get payment submission status
end note
opt 
Merchant -> PISP: Check payment status
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId}
ASPSP Resource Server -> PISP: HTTP 200 (OK), payment-submissions resource
PISP -> Merchant: HTTP 200 (OK), Return payment-submission Status
 
end opt

Illustrative Interactions

Notes:

• As per the Security & Access Control section - examples are given where the call to GET may use a either a client credentials grant or an authorization code grant to obtain a token to make GET requests.

Person To Person

This example set of flows and payload examples are for a payment initiated by a person to another person via a PISP.

In this scenario:

• The PSU has pre-specified the account from which funds will be transferred (i.e., the Debtor Account details)
• No building society accounts are involved in this interaction - so only the sort code and account number are specified in the DebtorAccount and CreditorAccount sections

Sequence Diagram

 participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
   
note over PSU, ASPSP Resource Server
Step 1: Request payment initiation
end note
PSU <-> PISP: Initiate a funds transfer
PSU -> PISP: Select debtor and creditor accounts
 
note over PSU, ASPSP Resource Server
Step 2: Setup single payment initiation
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 /payments
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentId
PISP -> PSU: HTTP 302 (Found), Redirect (PaymentId)
 
note over PSU, ASPSP Resource Server
Step 3: Authorize consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (PaymentId)
PSU <-> ASPSP Authorisation Server: authenticate
PSU <-> ASPSP Authorisation Server: SCA if required
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
 
note over PSU, ASPSP Resource Server
Step 4: Create payment submission
end note
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentSubmissionId
 
   
note over PSU, ASPSP Resource Server
Step 5: Get payment submission status
end note
opt
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId}
ASPSP Resource Server -> PISP: HTTP 200 (OK), payment-submissions resource

end opt

Illustrative Interactions

Alternative and Error Flows

Idempotent Payment Setup

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
note over PSU, ASPSP Resource Server
Step 2: Setup single payment initiation
end note
PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
PISP -> ASPSP Authorisation Server: Initiate Client Credentials Grant
ASPSP Authorisation Server -> PISP: token
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payments (x-idempotency-key={pisp-guid-1})
ASPSP Resource Server -> ASPSP Resource Server: Create new resource (PaymentId=1001)
alt unexpected failure
PISP -> ASPSP Resource Server: POST /payments (x-idempotency-key={pisp-guid-1})
note right of ASPSP Resource Server
    The resource server recognizes that 
    this is the same request as earlier.
    A new resource is not created.
    The payment id remains the same (e.g. 1001) as above.
    The status of the resource may be different if it has changed.   
  
    This operation can be retried multiple times if required.
end note
end alt

ASPSP Resource Server -> PISP: HTTP 201(Created), PaymentId=1001
PISP -> PSU: Redirect (PaymentId)

Idempotent Payment Submission

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
 
note over PSU, ASPSP Resource Server
 Step 4: Create payment submission
end note
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions PaymentId = 1001, x-idempotency-key={pisp-guid-2}

alt PISP attempts to POST to /payment-submissions with same PaymentId
PISP -> ASPSP Resource Server: POST /payment-submissions PaymentId = 1001, x-idempotency-key={pisp-guid-2}
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentSubmissionId

note right of ASPSP Resource Server
    The resource server recognizes that this
    is the same request as earlier.
    A new resource is not created.
    The PaymentSubmissionId remains the same as above. 
    The status of the resource may be different if it has changed. 
    
    The operation can be retried multiple times if required.
end note
end alt

Missing or Expired Access Token

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Payment Initiation
• Step 2: Setup Single Payment Initiation
• Step 3: Authorize Consent

The PISP attempts to provide an expired or missing access token to the ASPSP in an attempt to Create a Payment Submission or Get a Payment Submission Status

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
alt PISP attempts to create a payment submission with a missing or invalid access-token
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions
ASPSP Resource Server -> PISP: HTTP 401 (Unauthorized)
end par
  
alt PISP attempts to get a payment submission status with a missing or invalid access-token
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId}
ASPSP Resource Server -> PISP: HTTP 401 (Unauthorized)

Incomplete or Malformed Request Payload

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Payment Initiation
• Step 2: Setup Single Payment Initiation
• Step 3: Authorize Consent

The PISP provides an malformed request Payload to the ASPSP in an attempt to Create a Payment Submission

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
alt PISP attempts to create a payment submission with a malformed payload
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions
ASPSP Resource Server -> PISP: HTTP 400 (Bad Request)
end par

Missing or Invalid Access Token Scope

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Payment Initiation
• Step 2: Setup Single Payment Initiation
• Step 3: Authorize Consent

The PISP provides a (valid) access token containing an invalid scope to the ASPSP in an attempt to Create a Payment Submission or Get a Payment Submission Status

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
alt PISP attempts to create a payment submission with incorrect access-token scope
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: POST /payment-submissions
ASPSP Resource Server -> PISP: HTTP 403 (Forbidden)
end par
  
alt PISP attempts to get a payment submission status with incorrect access-token scope
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId}
ASPSP Resource Server -> PISP: HTTP 403 (Forbidden)

Sudden Burst of API Requests

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Payment Initiation
• Step 2: Setup Single Payment Initiation
• Step 3: Authorize Consent

The PISP provides a (valid) access token but rapidly increases the number of Get Payment Submission Status requests to the Resource Server.

The ASPSP can optionally choose to return a 429 Response

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  

alt PISP attempts to get a payment submission
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
    loop Burst of multiple GET Requests
        PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId}
        opt
            ASPSP Resource Server -> PISP: HTTP 429 (Too Many Requests)
        end
    end 
end

Failed Authorisation Consent 

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Payment Initiation
• Step 2: Setup Single Payment Initiation

The Step 3: Authorize Consent Flow fails to succeed due to the PSU providing invalid credentials to the ASPSP, resulting in no Authorization Code being generated.

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
   
note over PSU, ASPSP Resource Server
Step 1: Request payment initiation
end note
PSU -> PISP: Send payment initiation request
 
note over PSU, ASPSP Resource Server
 Setup single payment initiation
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 /payments
ASPSP Resource Server -> PISP: HTTP 201 (Created),  PaymentId
PISP -> PSU: HTTP 302 (Found), Redirect (PaymentId)
 
note over PSU, ASPSP Resource Server
 Step 3: Failed authorize consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (PaymentId)
PSU -> ASPSP Authorisation Server: Invalid credentials
ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (error)
PSU -> PISP: Follow redirect (error)
PISP -> PSU: Error response