Payment Initiation API Specification - v1.1.0

Version Control

VersionDateAuthorComments
1.0.023 Jun 2017Open Banking Read/Write API Team

This is the Baseline version. No Changes from v1.0-rc4.

1.1.031 Aug 2017Open Banking Read/Write API Team

Includes 9 fixes, 5 clarifications and 14 enhancements. Please see the release note for details. Changes from v1.1-rc2: More explicit wording around Non-Repudiation not to be implemented for v1.x

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

Important

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

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

Payment Initiation - High Level Flow
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

ActorAbbreviationTypeSpecializesDescription
Payment Service UserPSUPersonN/AA natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10))
Payment Service ProviderPSPLegal EntityN/AA legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11)
Account Servicing Payment Service ProviderASPSPLegal EntityPSP

An ASPSP is a PSP that provides and maintains a payment account for a payment services user (PSD 2 Article 4(15).

The CMA 9 are all ASPSPs.

Third Party Providers / Trusted Third PartiesTPPLegal EntityPSP

A party other than an ASPSP that provides payment related services.

The term is not actually defined in PSD2, but is generally deemed to include all payment service providers that are 3rd parties (the ASPSP and the PSU to whom the account belongs being the first two parties)

Payment Initiation Service ProviderPISPLegal EntityTPP

A TPP that provides Payment Initiation Services.

PSD2 does not offer a formal definition. Article 4(18) quite circularly defines a PISP as a PSP that provides Payment Initiation Services.

Account Information Service Provider

AISPLegal EntityTPP

A TPP that provides Account Information Services.

Again, PSD2 defines AISPs in Article 4(19) circularly as a PSP that provides account information services

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

Header ValueNotesPOST RequestsGET Requests
x-fapi-financial-id

The unique id of the ASPSP to which the request is issued.

The unique id will be issued by OB.

If the value does not match the expected value (based on the Client ID or network certificate of the caller, the ASPSP must reject the request with a 403 (Not Authorized) status code.

MandatoryMandatory
x-fapi-customer-last-logged-time

The time when the PSU last logged in with the TPP.

OptionalOptional
x-fapi-customer-ip-address

The PSU's IP address if the PSU is currently logged in with the TPP.

OptionalOptional
x-fapi-interaction-id

An RFC4122 UID used as a correlation id.

If provided, the ASPSP must "play back" this value in the x-fapi-interaction-id response header.

OptionalOptional
Authorization

Standard HTTP Header; Allows Credentials to be provided to the Authorisation / Resource Server depending on the type of resource being requested. For OAuth 2.0 / OIDC, this comprises of either the Basic / Bearer Authentication Schemes.

MandatoryMandatory
Content-Type

Standard HTTP Header; Represents the format of the payload being provided in the request.

This must be set to application/json.

MandatoryDo not use
Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.

If set, it must have the value: application/json.

If set to any other value, ASPSP must respond with a 406 Not Acceptable.

Optional.

OptionalOptional
x-idempotency-key

Custom HTTP Header; Unique request identifier to support idempotency.

Mandatory for POST requests.

MandatoryDo not use
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

Mandatory for requests that contain a payload.

A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means of non-repudiation.

This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

Not for v1.xNot for v1.x

(Reference: Section 6.3 - Financial API ‚ÄĒ Part 1: Read Only API Security Profile (Implementer‚Äôs Draft).)

Response Headers

Header ValueNotesMandatory ?
Content-Type

Standard HTTP Header; Represents the format of the payload returned in the response.

The ASPSP must return Content-type: application/json as a content header.

Mandatory.

Mandatory
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

Mandatory for requests that contain a payload.

A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means ofnon-repudiation.

This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

Not for v1.x
x-fapi-interaction-id

An RFC4122 UID used as a correlation id.

This must be the same value provided in the x-fapi-interaction-id request header.

Conditionally Mandatory
Retry-After

Header indicating the time (in seconds) that the TPP should wait before retrying an operation.

The ASPSP should include this header along with responses with the HTTP status code of 429 (Too many requests).

Optional

Return & Error Codes

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

Situation

HTTP Status

Notes

Returned by POSTReturned by GET
Query completed successfully200 OK
NoYes
Normal execution. The request has succeeded.201 CreatedThe operation results in the creation of a new resource.YesNo
Delete operation completed successfully204 No Content
NoNo

Request has malformed, missing or non-compliant JSON body or URL parameters

400 Bad RequestThe requested operation will not be carried out.YesNo

Authorization header missing or invalid token

401 Unauthorized

The operation was refused access.

Re-authenticating the PSU may result in an appropriate token that can be used.

YesYes

Token has incorrect scope or a security policy was violated.

403 Forbidden

The operation was refused access.

Re-authenticating the PSU is unlikely to remediate the situation.

YesYes
The TPP tried to access the resource with a method that is not supported.405 Method Not Allowed
YesYes
The request contained an accept header that requested a content-type other than application/json and a character set other than UTF-8406 Not Acceptable
YesYes
The operation was refused as too many requests have been made within a certain timeframe.429 Too Many Requests

Throttling is a NFR.

The ASPSP should include a Retry-After header in the response indicating how long the TPP must wait before retrying the operation.

YesYes
Something went wrong on the API gateway or micro-service500 Internal Server ErrorThe operation failed.YesYes

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:

SituationRequestResponse
TPP attempts to retrieve an account with a PaymentId that does not existGET /payments/1001400 (Bad Request)
TPP attempts to retrieve a resource that is not definedGET /bulk404 (Not Found)

TPP attempts to retrieve a resource that is in the specification, but not implemented by the ASPSP.

E.g., an ASPSP has chosen not to implement the status API endpoint for payment-submissions

GET /payment-submissions/1002404 (Not Found)

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

Important

API requests and responses must NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

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

Claim

Description

alg

The algorithm that will be used for signing the JWS.

The list of valid algorithms is here https://tools.ietf.org/html/rfc7518#section-3.1.

The algorithms that will be supported by OB will be specified in the future.

kid

This must match the certificate id of the certificate selected in step 1.

b64

This must have the boolean value false.

This indicates that the message payload is not base64 url encoded.

(See RFC 7797 - The "b64" header Parameter)

http://openbanking.org.uk/iat

This must be a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. 

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names)

http://openbanking.org.uk/iss

This must be a string containing the id of the TPP. This must match the dn of the signing certificate.

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names)

crit

This must be a string array consisting of the values "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"

This indicates that the JWS signature validator must understand and process the three additional claims.

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

Non-normative guidance

This section provides non-normative guidance on how the specifications can be used to comply with certain requirements of PSD2 and the RTS. This is not an exhaustive list. Detailed analysis will be provided separately - with full traceability matrix of requirements.

Although this specification refers to the use of SCA, the use of SCA is not mandated until the RTS comes into effect.

The RTS is not finalised at the point of publishing this version of the specification - this may lead to some changes as new drafts of the RTS are released.

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
ResourceHTTP OperationEnd-pointMandatory ?ScopeIdempotentRequest ObjectResponse Object
paymentsPOSTPOST /paymentsMandatorypaymentsYesOBPaymentSetup1OBPaymentSetupResponse1
paymentsGETGET /payments/{PaymentId}OptionalpaymentsNANAOBPaymentSetupResponse1
payment-submissionsPOSTPOST /payment-submissionsMandatorypaymentsYesOBPaymentSubmission1OBPaymentSubmissionResponse1
payment-submissionsGETGET /payment-submissions/{PaymentSubmissionId}OptionalpaymentsNANAOBPaymentSubmissionResponse1

POST /payments 

Single Payment Setup Endpoint
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:


StatusPayment Status Description
1PendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.
3AcceptedTechnicalValidationAuthentication and syntactical and semantic validation are successful.

GET /payments/{PaymentId}

Single Payment Status Endpoint
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:


StatusPayment Status Description
1PendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.
3AcceptedTechnicalValidationAuthentication and syntactical and semantic validation are successful.
4AcceptedCustomerProfilePreceding check of technical validation was successful. Customer profile check was also successful.

POST /payment-submissions

Single Payment Submission Endpoint
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:


StatusPayment Status Description
1PendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.
3AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

GET /payment-submissions/{PaymentSubmissionId}

Single Payment Submission Status Endpoint
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:


StatusPayment Status Description
1PendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.
3AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
4AcceptedSettlementCompletedSettlement on the debtor's account has been completed. 

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

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:


Payment Status CodePayment Status Description
1AcceptedCustomerProfilePreceding check of technical validation was successful. Customer profile check was also successful.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.

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:

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:

Payment API Request
{
  "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:

Payment API Response
{
  "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

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:

Example Links
  "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:

Example Meta
  "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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSetup1
OBPaymentSetup1
OBPaymentSetup1

Data1..1OBPaymentSetup1/Data
OBPaymentDataSetup1

Initiation1..1OBPaymentSetup1/Data/InitiationThe Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

InstructionIdentification1..1OBPaymentSetup1/Data/Initiation/InstructionIdentificationUnique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.

Usage: the  instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
Max35Text

EndToEndIdentification1..1OBPaymentSetup1/Data/Initiation/EndToEndIdentificationUnique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.
OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field.
Max35Text

InstructedAmount1..1OBPaymentSetup1/Data/Initiation/InstructedAmountAmount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.
ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1OBPaymentSetup1/Data/Initiation/InstructedAmount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
DebtorAgent0..1OBPaymentSetup1/Data/Initiation/DebtorAgentFinancial institution servicing an account for the debtor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBPaymentSetup1/Data/Initiation/DebtorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBPaymentSetup1/Data/Initiation/DebtorAgent/IdentificationUnique and unambiguous identification of a person.Max35Text

DebtorAccount0..1OBPaymentSetup1/Data/Initiation/DebtorAccountUnambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.OBCashAccountDebtor1

SchemeName1..1OBPaymentSetup1/Data/Initiation/DebtorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2Code

IBAN

SortCodeAccountNumber


Identification1..1OBPaymentSetup1/Data/Initiation/DebtorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name0..1OBPaymentSetup1/Data/Initiation/DebtorAccount/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text

SecondaryIdentification0..1

OBPaymentSetup1/Data/Initiation/DebtorAccount

/SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

CreditorAgent0..1OBPaymentSetup1/Data/Initiation/CreditorAgentFinancial institution servicing an account for the creditor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBPaymentSetup1/Data/Initiation/CreditorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBPaymentSetup1/Data/Initiation/CreditorAgent/IdentificationUnique and unambiguous identification of a person.Max35Text

CreditorAccount1..1OBPaymentSetup1/Data/Initiation/CreditorAccountUnambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.OBCashAccountCreditor1

SchemeName1..1OBPaymentSetup1/Data/Initiation/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2Code

IBAN

SortCodeAccountNumber


Identification1..1OBPaymentSetup1/Data/Initiation/CreditorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name1..1OBPaymentSetup1/Data/Initiation/CreditorAccount/Name

Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.

ASPSPs may carry out name validation for Confirmation of Payee, but it is not mandatory.

Max70Text

SecondaryIdentification0..1

OBPaymentSetup1/Data/Initiation/CreditorAccount/

SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

RemittanceInformation0..1OBPaymentSetup1/Data/Initiation/RemittanceInformationInformation supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.OBRemittanceInformation1

Unstructured0..1

OBPaymentSetup1/Data/Initiation/

RemittanceInformation/Unstructured

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.Max140Text

Reference0..1

OBPaymentSetup1/Data/Initiation/

RemittanceInformation/Reference

Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money.

If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.
OB: The Faster Payments Scheme can only accept 18 characters for the ReferenceInformation field - which is where this ISO field will be mapped.
Max35Text

Risk1..1OBPaymentSetup1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments.OBRisk1

PaymentContextCode0..1OBPaymentSetup1/Risk/PaymentContextCodeSpecifies the payment contextOBExternalPaymentContext1CodeBillPayment
EcommerceGoods
EcommerceServices
Other
PersonToPerson

MerchantCategoryCode0..1OBPaymentSetup1/Risk/MerchantCategoryCodeCategory code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.Min3Max4Text

MerchantCustomerIdentification0..1OBPaymentSetup1/Risk/MerchantCustomerIdentificationThe unique customer identifier of the PSU with the merchant.Max70Text

DeliveryAddress0..1OBPaymentSetup1/Risk/DeliveryAddressInformation that locates and identifies a specific address, as defined by postal services or in free format text.PostalAddress18

AddressLine0..2OBPaymentSetup1/Risk/DeliveryAddress/AddressLineInformation that locates and identifies a specific address, as defined by postal services, that is presented in free format text.Max70Text

StreetName0..1OBPaymentSetup1/Risk/DeliveryAddress/StreetNameName of a street or thoroughfare.Max70Text

BuildingNumber0..1OBPaymentSetup1/Risk/DeliveryAddress/BuildingNumberNumber that identifies the position of a building on a street.Max16Text

PostCode0..1OBPaymentSetup1/Risk/DeliveryAddress/PostCodeIdentifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.Max16Text

TownName1..1OBPaymentSetup1/Risk/DeliveryAddress/TownNameName of a built-up area, with defined boundaries, and a local government.Max35Text

CountrySubDivision0..2OBPaymentSetup1/Risk/DeliveryAddress/CountrySubDivisionIdentifies a subdivision of a country, for instance state, region, county.Max35Text

Country1..1OBPaymentSetup1/Risk/DeliveryAddress/CountryNation with its own government, occupying a particular territory.CountryCode
^[A-Z]{2,2}$

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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSetupResponse1
OBPaymentSetupResponse1
OBPaymentSetupResponse1

Data1..1OBPaymentSetupResponse1/Data
OBPaymentDataSetupResponse1

PaymentId1..1OBPaymentSetupResponse1/Data/PaymentIdOB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.Max128Text

Status0..1OBPaymentSetupResponse1/Data/StatusSpecifies the status of the payment resource.OBTransactionIndividualStatus1CodeAcceptedCustomerProfile
AcceptedTechnicalValidation
Pending
Rejected

CreationDateTime1..1OBPaymentSetupResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime

Initiation1..1OBPaymentSetupResponse1/Data/InitiationThe Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

InstructionIdentification1..1OBPaymentSetupResponse1/Data/Initiation/InstructionIdentificationUnique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.

Usage: the  instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
Max35Text

EndToEndIdentification1..1OBPaymentSetupResponse1/Data/Initiation/EndToEndIdentificationUnique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.
OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field.
Max35Text

InstructedAmount1..1OBPaymentSetupResponse1/Data/Initiation/InstructedAmountAmount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.
ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1OBPaymentSetupResponse1/Data/Initiation/InstructedAmount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
DebtorAgent0..1OBPaymentSetupResponse1/Data/Initiation/DebtorAgentFinancial institution servicing an account for the debtor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBPaymentSetupResponse1/Data/Initiation/DebtorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBPaymentSetupResponse1/Data/Initiation/DebtorAgent/IdentificationUnique and unambiguous identification of a person.Max35Text

DebtorAccount0..1OBPaymentSetupResponse1/Data/Initiation/DebtorAccountUnambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.OBCashAccountDebtor1

SchemeName1..1OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2Code

IBAN

SortCodeAccountNumber


Identification1..1OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name0..1OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text

SecondaryIdentification0..1

OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/

SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

CreditorAgent0..1OBPaymentSetupResponse1/Data/Initiation/CreditorAgentFinancial institution servicing an account for the creditor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBPaymentSetupResponse1/Data/Initiation/CreditorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBPaymentSetupResponse1/Data/Initiation/CreditorAgent/IdentificationUnique and unambiguous identification of a person.Max35Text

CreditorAccount1..1OBPaymentSetupResponse1/Data/Initiation/CreditorAccountUnambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.OBCashAccountCreditor1

SchemeName1..1OBPaymentSetupResponse1/Data/Initiation/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2Code

IBAN

SortCodeAccountNumber


Identification1..1OBPaymentSetupResponse1/Data/Initiation/CreditorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name1..1OBPaymentSetupResponse1/Data/Initiation/CreditorAccount/Name

Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.

ASPSPs may carry out name validation for Confirmation of Payee, but it is not mandatory.

Max70Text

SecondaryIdentification0..1

OBPaymentSetupResponse1/Data/Initiation/CreditorAccount/

SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

RemittanceInformation0..1OBPaymentSetupResponse1/Data/Initiation/RemittanceInformationInformation supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.OBRemittanceInformation1

Unstructured0..1

OBPaymentSetupResponse1/Data/Initiation/

RemittanceInformation/Unstructured

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.Max140Text

Reference0..1

OBPaymentSetupResponse1/Data/Initiation/

RemittanceInformation/Reference

Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money.

If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.
OB: The Faster Payments Scheme can only accept 18 characters for the ReferenceInformation field - which is where this ISO field will be mapped.
Max35Text

Risk1..1OBPaymentSetupResponse1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments.OBRisk1

PaymentContextCode0..1OBPaymentSetupResponse1/Risk/PaymentContextCodeSpecifies the payment contextOBExternalPaymentContext1CodeBillPayment
EcommerceGoods
EcommerceServices
Other
PersonToPerson

MerchantCategoryCode0..1OBPaymentSetupResponse1/Risk/MerchantCategoryCodeCategory code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.Min3Max4Text

MerchantCustomerIdentification0..1OBPaymentSetupResponse1/Risk/MerchantCustomerIdentificationThe unique customer identifier of the PSU with the merchant.Max70Text

DeliveryAddress0..1OBPaymentSetupResponse1/Risk/DeliveryAddressInformation that locates and identifies a specific address, as defined by postal services or in free format text.PostalAddress18

AddressLine0..2OBPaymentSetupResponse1/Risk/DeliveryAddress/AddressLineInformation that locates and identifies a specific address, as defined by postal services, that is presented in free format text.Max70Text

StreetName0..1OBPaymentSetupResponse1/Risk/DeliveryAddress/StreetNameName of a street or thoroughfare.Max70Text

BuildingNumber0..1OBPaymentSetupResponse1/Risk/DeliveryAddress/BuildingNumberNumber that identifies the position of a building on a street.Max16Text

PostCode0..1OBPaymentSetupResponse1/Risk/DeliveryAddress/PostCodeIdentifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.Max16Text

TownName1..1OBPaymentSetupResponse1/Risk/DeliveryAddress/TownNameName of a built-up area, with defined boundaries, and a local government.Max35Text

CountrySubDivision0..2OBPaymentSetupResponse1/Risk/DeliveryAddress/CountrySubDivisionIdentifies a subdivision of a country, for instance state, region, county.Max35Text

Country1..1OBPaymentSetupResponse1/Risk/DeliveryAddress/CountryNation with its own government, occupying a particular territory.CountryCode
^[A-Z]{2,2}$

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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSubmission1
OBPaymentSubmission1
OBPaymentSubmission1

Data1..1OBPaymentSubmission1/Data
OBPaymentDataSubmission1

PaymentId1..1OBPaymentSubmission1/Data/PaymentIdOB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.Max128Text

Initiation1..1OBPaymentSubmission1/Data/InitiationThe Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

InstructionIdentification1..1OBPaymentSubmission1/Data/Initiation/InstructionIdentificationUnique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.

Usage: the  instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
Max35Text

EndToEndIdentification1..1OBPaymentSubmission1/Data/Initiation/EndToEndIdentificationUnique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.
OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field.
Max35Text

InstructedAmount1..1OBPaymentSubmission1/Data/Initiation/InstructedAmountAmount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.
ActiveOrHistoricCurrencyAndAmount
^\d{1,13}\.\d{1,5}$
Currency1..1OBPaymentSubmission1/Data/Initiation/InstructedAmount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
DebtorAgent0..1OBPaymentSubmission1/Data/Initiation/DebtorAgentFinancial institution servicing an account for the debtor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBPaymentSubmission1/Data/Initiation/DebtorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBPaymentSubmission1/Data/Initiation/DebtorAgent/IdentificationUnique and unambiguous identification of a person.Max35Text

DebtorAccount0..1OBPaymentSubmission1/Data/Initiation/DebtorAccountUnambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.OBCashAccountDebtor1

SchemeName1..1OBPaymentSubmission1/Data/Initiation/DebtorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2Code

IBAN

SortCodeAccountNumber


Identification1..1OBPaymentSubmission1/Data/Initiation/DebtorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name0..1OBPaymentSubmission1/Data/Initiation/DebtorAccount/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text

SecondaryIdentification0..1

OBPaymentSubmission1/Data/Initiation/DebtorAccount/

SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

CreditorAgent0..1OBPaymentSubmission1/Data/Initiation/CreditorAgentFinancial institution servicing an account for the creditor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBPaymentSubmission1/Data/Initiation/CreditorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBPaymentSubmission1/Data/Initiation/CreditorAgent/IdentificationUnique and unambiguous identification of a person.Max35Text

CreditorAccount1..1OBPaymentSubmission1/Data/Initiation/CreditorAccountUnambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.OBCashAccountCreditor1

SchemeName1..1OBPaymentSubmission1/Data/Initiation/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2Code

IBAN

SortCodeAccountNumber


Identification1..1OBPaymentSubmission1/Data/Initiation/CreditorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner.Max34Text

Name1..1OBPaymentSubmission1/Data/Initiation/CreditorAccount/Name

Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
ASPSPs may carry out name validation for Confirmation of Payee, but it is not mandatory.

Max70Text

SecondaryIdentification0..1

OBPaymentSubmission1/Data/Initiation/CreditorAccount/

SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution.
This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).
Max34Text

RemittanceInformation0..1OBPaymentSubmission1/Data/Initiation/RemittanceInformationInformation supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.OBRemittanceInformation1

Unstructured0..1

OBPaymentSubmission1/Data/Initiation/

RemittanceInformation/Unstructured

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.Max140Text

Reference0..1

OBPaymentSubmission1/Data/Initiation/

RemittanceInformation/Reference

Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money.

If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.
OB: The Faster Payments Scheme can only accept 18 characters for the ReferenceInformation field - which is where this ISO field will be mapped.
Max35Text

Risk1..1OBPaymentSubmission1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments.OBRisk1

PaymentContextCode0..1OBPaymentSubmission1/Risk/PaymentContextCodeSpecifies the payment contextOBExternalPaymentContext1CodeBillPayment
EcommerceGoods
EcommerceServices
Other
PersonToPerson

MerchantCategoryCode0..1OBPaymentSubmission1/Risk/MerchantCategoryCodeCategory code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.Min3Max4Text

MerchantCustomerIdentification0..1OBPaymentSubmission1/Risk/MerchantCustomerIdentificationThe unique customer identifier of the PSU with the merchant.Max70Text

DeliveryAddress0..1OBPaymentSubmission1/Risk/DeliveryAddressInformation that locates and identifies a specific address, as defined by postal services or in free format text.PostalAddress18

AddressLine0..2OBPaymentSubmission1/Risk/DeliveryAddress/AddressLineInformation that locates and identifies a specific address, as defined by postal services, that is presented in free format text.Max70Text

StreetName0..1OBPaymentSubmission1/Risk/DeliveryAddress/StreetNameName of a street or thoroughfare.Max70Text

BuildingNumber0..1OBPaymentSubmission1/Risk/DeliveryAddress/BuildingNumberNumber that identifies the position of a building on a street.Max16Text

PostCode0..1OBPaymentSubmission1/Risk/DeliveryAddress/PostCodeIdentifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.Max16Text

TownName1..1OBPaymentSubmission1/Risk/DeliveryAddress/TownNameName of a built-up area, with defined boundaries, and a local government.Max35Text

CountrySubDivision0..2OBPaymentSubmission1/Risk/DeliveryAddress/CountrySubDivisionIdentifies a subdivision of a country, for instance state, region, county.Max35Text

Country1..1OBPaymentSubmission1/Risk/DeliveryAddress/CountryNation with its own government, occupying a particular territory.CountryCode
^[A-Z]{2,2}$

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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSubmissionResponse1
OBPaymentSubmissionResponse1
OBPaymentSubmissionResponse1

Data1..1OBPaymentSubmissionResponse1/Data
OBPaymentDataSubmissionResponse1

PaymentSubmissionId1..1OBPaymentSubmissionResponse1/Data/PaymentSubmissionIdOB: Unique identification as assigned by the ASPSP to uniquely identify the payment submission resource.Max40Text

PaymentId1..1OBPaymentSubmissionResponse1/Data/PaymentIdOB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.Max128Text

Status0..1OBPaymentSubmissionResponse1/Data/StatusSpecifies the status of the payment submission resource.OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted
AcceptedSettlementInProcess
Pending
Rejected

CreationDateTime1..1OBPaymentSubmissionResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime

Data Payload - Enumerations

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

Code ClassName Definition 
OBExternalAccountIdentification2CodeIBANAn identifier used internationally by financial institutions to uniquely identify the account of a customer at a financial institution, as described in the latest edition of the international standard ISO 13616. "Banking and related financial services - International Bank Account Number (IBAN)".
OBExternalAccountIdentification2CodeSortCodeAccountNumber

Sort Code and Account Number - identifier scheme used in the UK by financial institutions to identify the account of a customer. The identifier is the concatenation of the 6 digit UK sort code and 8 digit account number.

The regular expression for this identifier is: ^[0-9]{6}[0-9]{8}$

OBExternalFinancialInstitutionIdentification2CodeBICFIValid BICs for financial institutions are registered by the ISO 9362 Registration Authority in the BIC directory, and consist of eight (8) or eleven (11) contiguous characters.
OBExternalPaymentContext1CodeBillPaymentThe context of the payment initiation is a bill payment.
OBExternalPaymentContext1CodeEcommerceGoodsThe context of the payment initiation is a for goods via an ecommerce channel.
OBExternalPaymentContext1CodeEcommerceServicesThe context of the payment initiation is a for services via an ecommerce channel.
OBExternalPaymentContext1CodePersonToPersonThe context of the payment initiation is a person to person payment.
OBExternalPaymentContext1CodeOtherThe context of the payment initiation is of an other type.
OBTransactionIndividualStatus1CodeAcceptedCustomerProfilePreceding check of technical validation was successful. Customer profile check was also successful.
OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted

Settlement on the debtor's account has been completed.

Usage : this can be used by the first agent to report to the debtor that the transaction has been completed. Warning : this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

PISPs must not use this status as confirmation that settlement is complete on the creditor's account.

OBTransactionIndividualStatus1CodeAcceptedSettlementInProcessAll preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
OBTransactionIndividualStatus1CodeAcceptedTechnicalValidationAuthentication and syntactical and semantic validation are successful.
OBTransactionIndividualStatus1CodePendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
OBTransactionIndividualStatus1CodeRejectedPayment initiation or individual transaction included in the payment initiation has been rejected.

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.

GeneratedIdentifierBusiness Description

Merchant/PISP

Sent in API Payload

EndToEndIdentificationThe EndToEndIdentification reference is a reference that can be populated by the debtor (or merchant in the ecommerce space). This reference is important to the debtor (could be an internal reference Id against the transaction), it Is NOT the reference information that will be primarily populated on the statement of the creditor (beneficiary).

Merchant/PISP

Sent in API Payload

InstructionIdentification

PISP generates the InstructionIdentification which is a unique transaction Id and passes it to the ASPSP (this is mandatory), but this doesn’t have to go any further in the payment flow. The flow of this identifier needs to align with payment scheme rules.

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.

Merchant/PISP

Sent in API Payload

RemittanceInformationThe RemittanceInformation is the reference information that creditor (or beneficiary) will need to reconcile (e.g. Invoice 123).

ASPSP / API System

PaymentIdUnique identification as assigned by the ASPSP to uniquely identify the payment setup resource.
ASPSP / API SystemPaymentSubmissionIdUnique identification as assigned by the ASPSP to uniquely identify the payment-submission resource.

ASPSP / Payment Scheme

Scheme Payment IDThis is generated by the ASPSP to uniquely identify a payment through a processing scheme. In the case of FPS - this is the FPID.

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

Identifier

PSU

Merchant

PISP

ASPSP

Originating Bank

Payment Scheme

Beneficiary

EndToEndIdentification
O=>=>=>=>
RemittanceInformation
O=>=>=>=>
InstructionIdentification

O

=>


PaymentId

<=

O



PaymentSubmissionId

<=O

Scheme Payment ID

(e.g., FPID)




O

=>

=>

Person to Person Flow

Identifier

PSU

Merchant

PISP

ASPSP

Originating Bank

Payment Scheme

Beneficiary

EndToEndIdentification

O=>=>=>
RemittanceInformationO
=>=>=>=>
InstructionIdentification

O

=>


PaymentId

<=

O



PaymentSubmissionId

<=O

Scheme Payment ID

(e.g., FPID)




O

=>

=>

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.

NameXPathOccurrenceClassISO8583 BITFPS Field NameMandatorySize
InitiationInitiation1..1OBInitiation1



InstructionIdentificationInitiation/InstructionIdentification1..1Max35Text



EndToEndIdentificationInitiation/EndToEndIdentification1..1Max35Text62END TO END REFERENCE 31
InstructedAmountInitiation/InstructedAmount1..1TotalDigits: 18, FractionDigits: 56AMOUNT 14
CurrencyInitiation/InstructedAmount/Currency1..1ActiveOrHistoricCurrencyCode



DebtorAgentInitiation/DebtorAgent0..1




SchemeNameInitiation/DebtorAgent/SchemeName1..1




IdentificationInitiation/DebtorAgent/Identification1..1


 
DebtorAccountInitiation/DebtorAccount0..1




SchemeNameInitiation/DebtorAccount/SchemeName1..1




IdentificationInitiation/DebtorAccount/Identification1..1Max34Text

42

43

ORIGINATING CREDIT INSTITUTION

ORIGINATING CUSTOMER ACCOUNT NUMBER 

11

34

NameInitiation/DebtorAccount/Name0..1




SecondaryIdentificationInitiation/DebtorAccount/SecondaryIdentification0..1




CreditorAgentInitiation/CreditorAgent1..1




SchemeNameInitiation/CreditorAgent/SchemeName1..1




IdentificationInitiation/CreditorAgent/Identification1..1Max35Text
 

CreditorAccountInitiation/CreditorAccount1..1




SchemeNameInitiation/CreditorAccount/SchemeName1..1




IdentificationInitiation/CreditorAccount/Identification1..1Max34Text

95

35

BENEFICIARY CREDIT INSTITUTION

BENEFICIARY CUSTOMER ACCOUNT NUMBER 

11

34

NameInitiation/CreditorAccount/Name1..1Max70Text118BENEFICIARY CUSTOMER ACCOUNT NAME 40
SecondaryIdentificationInitiation/CreditorAccount/SecondaryIdentification0..1Max34Text120REFERENCE INFORMATION 18
RemittanceInformationInitiation/RemittanceInformation0..1




UnstructuredInitiation/RemittanceInformation/Unstructured0..1Max140Text121REMITTANCE INFORMATION 140
ReferenceInitiation/RemittanceInformation/Reference0..1Max35Text120REFERENCE INFORMATION 18

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. 

NameXPathOccurrenceClassSTD18 FieldBacs Field NameMandatory ?Size
InitiationInitiation1..1OBInitiation1



InstructionIdentificationInitiation/InstructionIdentification1..1




EndToEndIdentificationInitiation/EndToEndIdentification1..1




InstructedAmountInitiation/InstructedAmount1..1TotalDigits: 18, FractionDigits: 58amount in penceM11
CurrencyInitiation/InstructedAmount/Currency1..1




DebtorAgentInitiation/DebtorAgent0..1




SchemeNameInitiation/DebtorAgent/SchemeName1..1




IdentificationInitiation/DebtorAgent/Identification1..1Max35Text




DebtorAccountInitiation/DebtorAccount0..1




SchemeNameInitiation/DebtorAccount/SchemeName1..1




IdentificationInitiation/DebtorAccount/Identification1..1Max34Text

5

6

originating sorting code

originating account number

M

M

6

8

NameInitiation/DebtorAccount/Name0..1




SecondaryIdentificationInitiation/DebtorAccount/SecondaryIdentification0..1




CreditorAgentInitiation/CreditorAgent1..1




SchemeNameInitiation/CreditorAgent/SchemeName1..1




IdentificationInitiation/CreditorAgent/Identification1..1Max35Text



CreditorAccountInitiation/CreditorAccount1..1




SchemeNameInitiation/CreditorAccount/SchemeName1..1




IdentificationInitiation/CreditorAccount/Identification1..1Max34Text

1

2

destination sorting code

destination a/c number

M

M

6

8

NameInitiation/CreditorAccount/Name1..1Max70Text11destination account nameM18
SecondaryIdentificationInitiation/CreditorAccount/SecondaryIdentification0..1Max34Text10service user’s referenceM18
RemittanceInformationInitiation/RemittanceInformation0..1




UnstructuredInitiation/RemittanceInformation/Unstructured0..1




ReferenceInitiation/RemittanceInformation/Reference0..1Max35Text10service user’s referenceM18

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

Usage Examples - Merchant
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.

POST /payments request

Payment Setup Request Payload
POST /payments HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
  "Data": {
    "Initiation": {
      "InstructionIdentification": "ACME412",
      "EndToEndIdentification": "FRESCO.21302.GFX.20",
      "InstructedAmount": {
        "Amount": "165.88",
        "Currency": "GBP"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "ACME Inc",
        "SecondaryIdentification": "0002"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-101",
        "Unstructured": "Internal ops code 5120101"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "EcommerceGoods",
    "MerchantCategoryCode": "5967",
    "MerchantCustomerIdentification": "053598653254",
    "DeliveryAddress": {
      "AddressLine": [
        "Flat 7",
        "Acacia Lodge"
      ],
      "StreetName": "Acacia Avenue",
      "BuildingNumber": "27",
      "PostCode": "GU31 2ZZ",
      "TownName": "Sparsholt",
      "CountySubDivision": [
        "Wessex"
      ],
      "Country": "UK"
    }
  }
}




POST /payments response

Payment Setup Response Payload
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentId": "58923",
    "Status": "AcceptedTechnicalValidation",
    "CreationDateTime": "2017-06-05T15:15:13+00:00",
    "Initiation": {
      "InstructionIdentification": "ACME412",
      "EndToEndIdentification": "FRESCO.21302.GFX.20",
      "InstructedAmount": {
        "Amount": "165.88",
        "Currency": "GBP"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "ACME Inc",
        "SecondaryIdentification": "0002"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-101",
        "Unstructured": "Internal ops code 5120101"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "EcommerceGoods",
    "MerchantCategoryCode": "5967",
    "MerchantCustomerIdentification": "053598653254",
    "DeliveryAddress": {
      "AddressLine": [
        "Flat 7",
        "Acacia Lodge"
      ],
      "StreetName": "Acacia Avenue",
      "BuildingNumber": "27",
      "PostCode": "GU31 2ZZ",
      "TownName": "Sparsholt",
      "CountySubDivision": [
        "Wessex"
      ],
      "Country": "UK"
    }
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payments/58923"
  },
  "Meta": {}
}


POST /payment-submissions Request

Payment Submission Request Payload
POST /payment-submissions HTTP/1.1
Authorization: Bearer Jhingapulaav
x-idempotency-key: FRESNO.1317.GFX.22
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
  "Data": {
    "PaymentId": "58923",
    "Initiation": {
      "InstructionIdentification": "ACME412",
      "EndToEndIdentification": "FRESCO.21302.GFX.20",
      "InstructedAmount": {
        "Amount": "165.88",
        "Currency": "GBP"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "ACME Inc",
        "SecondaryIdentification": "0002"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-101",
        "Unstructured": "Internal ops code 5120101"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "EcommerceGoods",
    "MerchantCategoryCode": "5967",
    "MerchantCustomerIdentification": "053598653254",
    "DeliveryAddress": {
      "AddressLine": [
        "Flat 7",
        "Acacia Lodge"
      ],
      "StreetName": "Acacia Avenue",
      "BuildingNumber": "27",
      "PostCode": "GU31 2ZZ",
      "TownName": "Sparsholt",
      "CountySubDivision": [
        "Wessex"
      ],
      "Country": "UK"
    }
  }
}


POST /payment-submissions Response

Payment Submission Response Payload
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentSubmissionId": "58923-001",
    "PaymentId": "58923",
    "Status": "AcceptedSettlementInProcess",
    "CreationDateTime": "2017-06-05T15:15:22+00:00"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payment-submissions/58923-001"
  },
  "Meta": {}
}

GET /payments Request

Get /payments REQUEST
GET /payments/58923 HTTP/1.1
Authorization: Bearer Jhingapulaav
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payments Response

GET payments RESPONSE
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentId": "58923",
    "Status": "AcceptedTechnicalValidation",
    "CreationDateTime": "2017-06-05T15:15:13+00:00",
    "Initiation": {
      "InstructionIdentification": "ACME412",
      "EndToEndIdentification": "FRESCO.21302.GFX.20",
      "InstructedAmount": {
        "Amount": "165.88",
        "Currency": "GBP"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "ACME Inc",
        "SecondaryIdentification": "0002"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-101",
        "Unstructured": "Internal ops code 5120101"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "EcommerceGoods",
    "MerchantCategoryCode": "5967",
    "MerchantCustomerIdentification": "053598653254",
    "DeliveryAddress": {
      "AddressLine": [
        "Flat 7",
        "Acacia Lodge"
      ],
      "StreetName": "Acacia Avenue",
      "BuildingNumber": "27",
      "PostCode": "GU31 2ZZ",
      "TownName": "Sparsholt",
      "CountySubDivision": [
        "Wessex"
      ],
      "Country": "UK"
    }
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payments/58923"
  },
  "Meta": {}
}


GET /payment-submissions Request

GET payment-submissions REQUEST
GET /payment-submissions/58923-001 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payment-submissions Response

GET payment-submissions RESPONSE
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentSubmissionId": "58923-001",
    "PaymentId": "58923",
    "Status": "AcceptedSettlementInProcess",
    "CreationDateTime": "2017-06-05T15:15:22+00:00"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payment-submissions/58923-001"
  },
  "Meta": {}
}


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

Usage Examples - Person to Person
 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

POST /payments request

POST payments REQUEST
POST /payments HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
  "Data": {
    "Initiation": {
      "InstructionIdentification": "ANSM023",
      "EndToEndIdentification": "FRESCO.21302.GFX.37",
      "InstructedAmount": {
        "Amount": "20.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "Andrea Smith"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Bob Clements"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-037",
        "Unstructured": "Internal ops code 5120103"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PersonToPerson"
  }
}


POST /payment response

POST payments RESPONSE
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentId": "7290",
    "Status": "AcceptedTechnicalValidation",
    "CreationDateTime": "2017-06-05T15:15:13+00:00",
    "Initiation": {
      "InstructionIdentification": "ANSM023",
      "EndToEndIdentification": "FRESCO.21302.GFX.37",
      "InstructedAmount": {
        "Amount": "20.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "Andrea Smith"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Bob Clements"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-037",
        "Unstructured": "Internal ops code 5120103"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PersonToPerson"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payments/7290"
  },
  "Meta": {}
}


POST /payment-submissions request

POST payment-submissions REQUEST
POST /payment-submissions HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESNO.1317.GFX.22
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
  "Data": {
    "PaymentId": "7290",
    "Initiation": {
      "InstructionIdentification": "ANSM023",
      "EndToEndIdentification": "FRESCO.21302.GFX.37",
      "InstructedAmount": {
        "Amount": "20.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "Andrea Smith"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Bob Clements"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-037",
        "Unstructured": "Internal ops code 5120103"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PersonToPerson"
  }
}



POST /payment-submissions response

POST payment-submissions RESPONSE
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentSubmissionId": "7290-003",
    "PaymentId": "7290",
    "Status": "AcceptedSettlementInProcess",
    "CreationDateTime": "2017-06-05T15:15:22+00:00"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payment-submissions/7290-003"
  },
  "Meta": {}
}


GET /payments request

GET payments REQUEST
GET /payments/7290 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payments response

GET payments RESPONSE
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentId": "7290",
    "Status": "AcceptedTechnicalValidation",
    "CreationDateTime": "2017-06-05T15:15:13+00:00",
    "Initiation": {
      "InstructionIdentification": "ANSM023",
      "EndToEndIdentification": "FRESCO.21302.GFX.37",
      "InstructedAmount": {
        "Amount": "20.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "Andrea Smith"
      },
      "CreditorAccount": {
        "SchemeName": "SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Bob Clements"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-037",
        "Unstructured": "Internal ops code 5120103"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PersonToPerson"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payments/7290"
  },
  "Meta": {}
}


GET /payment-submissions request

GET payment-submissions REQUEST
GET /payment-submissions/7290-003 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payment-submissions response

GET payment-submissions RESPONSE
HTTP/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentSubmissionId": "7290-003",
    "PaymentId": "7290",
    "Status": "AcceptedSettlementInProcess",
    "CreationDateTime": "2017-06-05T15:15:22+00:00"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payment-submissions/7290-003"
  },
  "Meta": {}
}




Alternative and Error Flows

Idempotent Payment Setup

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

Payment Submission Conflict - Sequence Diagram
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

Missing or Expired Access Token
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

Malformed Request Payload
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

Missing or Invalid Access Token Scope
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

Sudden Burst of API Requests
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.

Failed Authorization Consent
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