Payment Initiation API Specification – v1.0.0

Payment Initiation API Specification – v1.0.0

Overview Back To Top

Disclaimer

The following specifications are API standards , subject to change and provide no access to API end points or any data whatsoever.

Open Banking grants to third party users a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, these API Specifications solely for the purposes of developing and implementing relevant Applications and APIs. Provided that attribution be made to Open Banking Ltd as the source of the material but that such attribution does not indicate an endorsement by Open Banking.

Open Banking accepts no responsibility or liability as a result of third party use of, or access to, the specifications. It takes no responsibility or liability regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in these specifications or the extent to which any license under such rights might or might not be available; Open Banking makes no warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the third party.

Any contributor of comments or feedback to the above specifications does so in the knowledge that the specifications are open data and no rights or interest shall arise as a result of such contributions

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:

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

Subject to change

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 section will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

The APIs will provide non-repudiation through digital signatures.

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

Payment API – Scheme Agnostic

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

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

We will provide further mapping guidance to ensure that differences are understood between the Open Banking Payment API standard, and FPS and Bacs schemes.

Status Codes

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

  • The HTTP Status Code reflects the outcome of the API call (the HTTP operation on the resource). The Security Working Group have stated that granular error codes may expose threat vectors – so these are limited to the HTTP Status Codes for v1.0.
  • The Status field in the Payment API payloads reflect the status of the payments and payment-submissions resources. This Status will be limited to the ISO 20022 PaymentStatusCode code-list enumeration for v1.0.

Scope

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

Out of Scope

This v1.0 specification does not cater for:

  • Payments that involve currency exchange.
  • Payments that involve currencies other than GBP (no validation of EUR payment schemes has been completed for v1.0).
  • Payments that are not single, immediate, domestic payments made in GBP – i.e., payments that are:
    • In bulk – single debit, multiple credit
    • Future dated or deferred
    • Recurring.
  • Multi-authentication flows have been designed – but the full implications of the multi-authentication flows have not been worked through – so these are not included in this version.
  • Non-functional requirements and specification of caching and throttling.

Basics Back To Top

Overview

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

Payment API

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
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
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: payment-submissions resource
PISP -> PSU: HTTP 200 (OK)
   
end opt

Actors

Actor Abbreviation Type Specializes Description
Third Party Providers / Trusted Third Parties TPP Legal Entity PSP 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 Service User PSU Person N/A A natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10))
Payment Service Provider PSP Legal Entity N/A A legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11)
Payment Initiation Service Provider PISP Legal Entity TPP 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 Servicing Payment Service Provider ASPSP Legal Entity PSP 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.

Account Information Service Provider AISP Legal Entity TPP A TPP that provides Account Information Services.

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

Headers

Request Headers

Header Value Notes POST Requests GET Requests
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.

TBC TBC
x-idempotency-key
Custom HTTP Header; Unique request identifier to support idempotency.

Mandatory for POST requests.

Mandatory Do not use
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.

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

Mandatory Mandatory
x-fapi-customer-last-logged-time
The time when the PSU last logged in with the TPP. Optional Optional
x-fapi-customer-ip-address
The PSU’s IP address if the PSU is currently logged in with the TPP. Optional Optional
Content-Type
Standard HTTP Header; Represents the format of the payload being provided in the request.

This must be set to application/json.

Mandatory Do not use
 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. Mandatory Mandatory
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.

Optional Optional

Response Headers

Header Value Notes Mandatory ?
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.

TBC
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

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 POST Returned by GET
Query completed successfully 200 OK No Yes
Normal execution. The request has succeeded. 201 Created The operation results in the creation of a new resource. Yes No
Delete operation completed successfully 204 No Content No No
Request has malformed, missing or non-compliant JSON body or URL parameters 400 Bad Request The requested operation will not be carried out. Yes No
Authorization header missing or invalid token 401 Unauthorized The operation was refused access. Yes Yes
Token invalid, has incorrect scope or a security policy was violated 403 Forbidden The operation was refused access. Yes Yes
The operation was refused as too many requests have been made within a certain timeframe. 429 Too Many Requests Throttling is a NFR. Yes Yes
Something went wrong on the API gateway or micro-service 500 Internal Server Error The operation failed. Yes Yes

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:

Situation Request Response
TPP attempts to retrieve an account with a PaymentId that does not exist GET /payments/1001 400 (Bad Request)
TPP attempts to retrieve a resource that is not defined GET /bulk 404 (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/1002 404 (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 is no longer valid
  • The TPP uses an access token that does not have the approporiate scope to access the requested resource.
  • The TPP attempted to access a resource with an Id that it does not have access to. E.g., an attempt to access GET /payments/1001 where a payment resource with id 1001 belongs to another TPP.

429 (Too Many Requests)

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

This situation could arise when:

  • A TPP decides to implement “Real Time Payment Status” functionality for its users and implements this badly by polling a GET endpoint or an Idempotent POST endpoint once-per-second constantly to provide pseudo “real-time” Status updates to the user.
  • A TPP decides to use the Single Immediate Payment endpoint as if it were a BATCH payment facility and sends 1,000 payment requests in a very short space of time.

Pre-Conditions

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

Pre-conditions for TPPs

    1. The TPP must have completed onboarding on the Open Banking Directory.
    2. The TPP must have registered one or more software statements with the Open

Banking Directory. The software statement must have “payments” as one of the required scopes.

  • The TPP must have valid network and signing certificates issued by Open Banking.
  • 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

    Subject to change

    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 section will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

    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 the 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 string containing a timestamp in ISO 8601 format.

    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 verifier 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": "2017-06-12T20:05:50+00:00",
        "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 Back To Top

    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
    Resource HTTP Operation End-point Mandatory? Scope Idempotent Request Object Response Object
    payments POST POST /payments Mandatory payments Yes OBPaymentSetup1 OBPaymentSetupResponse1
    payments GET GET /payments/{PaymentId} Optional payments NA NA OBPaymentSetupResponse1
    payment-submissions POST POST /payment-submissions Mandatory payments Yes OBPaymentSubmission1 OBPaymentSubmissionResponse1
    payment-submissions GET GET /payment-submissions/{PaymentSubmissionId} Optional payments NA NA OBPaymentSubmissionResponse1

    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:

    Status Payment Status Description
    1 Pending Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
    2 Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.
    3 AcceptedTechnicalValidation Authentication 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:

    Status Payment Status Description
    1 Pending Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
    2 Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.
    3 AcceptedTechnicalValidation Authentication and syntactical and semantic validation are successful.
    4 AcceptedCustomerProfile Preceding 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:

    Status Payment Status Description
    1 Pending Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
    2 Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.
    3 AcceptedSettlementInProcess 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:

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

    Security & Access Control Back To Top

    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.

    Payment Status Code Payment Status Description
    1 AcceptedCustomerProfile Preceding check of technical validation was successful. Customer profile check was also successful.
    2 Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.

    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 Back To Top

    The swagger specification for Payment Initiation APIs can be downloaded from the following links:

    Data Model Back To Top

    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"
    }

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

    For example:

    Example Meta

    "Meta": {
      "total-pages": 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.
    • 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
    Name Occurrence Xpath EnhancedDefinition Class Codes Pattern
    OBPaymentSetup1 OBPaymentSetup1 OBPaymentSetup1
    Data 1..1 OBPaymentSetup1/Data OBPaymentDataSetup1
    Initiation 1..1 OBPaymentSetup1/Data/Initiation The 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
    InstructionIdentification 1..1 OBPaymentSetup1/Data/Initiation/InstructionIdentification Unique 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
    EndToEndIdentification 1..1 OBPaymentSetup1/Data/Initiation/EndToEndIdentification Unique 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
    InstructedAmount 1..1 OBPaymentSetup1/Data/Initiation/InstructedAmount Amount 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
    Currency 1..1 OBPaymentSetup1/Data/Initiation/InstructedAmount/Currency A 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}
    DebtorAgent 0..1 OBPaymentSetup1/Data/Initiation/DebtorAgent Financial institution servicing an account for the debtor. OBBranchAndFinancialInstitutionIdentification2
    SchemeName 1..1 OBPaymentSetup1/Data/Initiation/DebtorAgent/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalFinancialInstitutionIdentification2Code BICFI
    UKSortCode
    Identification 1..1 OBPaymentSetup1/Data/Initiation/DebtorAgent/Identification Unique and unambiguous identification of a person. Max35Text
    DebtorAccount 0..1 OBPaymentSetup1/Data/Initiation/DebtorAccount Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. OBCashAccountDebtor1
    SchemeName 1..1 OBPaymentSetup1/Data/Initiation/DebtorAccount/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalAccountIdentification2Code BBAN
    IBAN
    Identification 1..1 OBPaymentSetup1/Data/Initiation/DebtorAccount/Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max34Text
    Name 0..1 OBPaymentSetup1/Data/Initiation/DebtorAccount/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.

    Max70Text
    SecondaryIdentification 0..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
    CreditorAgent 1..1 OBPaymentSetup1/Data/Initiation/CreditorAgent Financial institution servicing an account for the creditor. OBBranchAndFinancialInstitutionIdentification2
    SchemeName 1..1 OBPaymentSetup1/Data/Initiation/CreditorAgent/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalFinancialInstitutionIdentification2Code BICFI
    UKSortCode
    Identification 1..1 OBPaymentSetup1/Data/Initiation/CreditorAgent/Identification Unique and unambiguous identification of a person. Max35Text
    CreditorAccount 1..1 OBPaymentSetup1/Data/Initiation/CreditorAccount Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. OBCashAccountCreditor1
    SchemeName 1..1 OBPaymentSetup1/Data/Initiation/CreditorAccount/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalAccountIdentification2Code BBAN
    IBAN
    Identification 1..1 OBPaymentSetup1/Data/Initiation/CreditorAccount/Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max34Text
    Name 1..1 OBPaymentSetup1/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
    SecondaryIdentification 0..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
    RemittanceInformation 0..1 OBPaymentSetup1/Data/Initiation/RemittanceInformation Information 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
    Unstructured 0..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
    Reference 0..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
    Risk 1..1 OBPaymentSetup1/Risk/PaymentContextCode Specifies the payment context OBExternalPaymentContext1Code BillPayment
    EcommerceGoods
    EcommerceServices
    Other
    PersonToPerson
    MerchantCategoryCode 0..1 OBPaymentSetup1/Risk/MerchantCategoryCode Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction. Min3Max4Text
    MerchantCustomerIdentification 0..1 OBPaymentSetup1/Risk/MerchantCustomerIdentification The unique customer identifier of the PSU with the merchant. Max70Text
    DeliveryAddress 0..1 OBPaymentSetup1/Risk/DeliveryAddress Information that locates and identifies a specific address, as defined by postal services or in free format text. PostalAddress18
    AddressLine 0..2 OBPaymentSetup1/Risk/DeliveryAddress/AddressLine Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. Max70Text
    StreetName 0..1 OBPaymentSetup1/Risk/DeliveryAddress/StreetName Name of a street or thoroughfare. Max70Text
    BuildingNumber 0..1 OBPaymentSetup1/Risk/DeliveryAddress/BuildingNumber Number that identifies the position of a building on a street. Max16Text
    PostCode 0..1 OBPaymentSetup1/Risk/DeliveryAddress/PostCode Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. Max16Text
    TownName 1..1 OBPaymentSetup1/Risk/DeliveryAddress/TownName Name of a built-up area, with defined boundaries, and a local government. Max35Text
    CountrySubDivision 0..2 OBPaymentSetup1/Risk/DeliveryAddress/CountrySubDivision Identifies a subdivision of a country, for instance state, region, county. Max35Text
    Country 1..1 OBPaymentSetup1/Risk/DeliveryAddress/Country Nation 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
    Name Occurrence XPath EnhancedDefinition Class Codes Pattern
    OBPaymentSetupResponse1 OBPaymentSetupResponse1 OBPaymentSetupResponse1
    Data 1..1 OBPaymentSetupResponse1/Data OBPaymentDataSetupResponse1
    PaymentId 1..1 OBPaymentSetupResponse1/Data/PaymentId OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource. Max128Text
    Status 0..1 OBPaymentSetupResponse1/Data/Status Specifies the status of the payment resource. OBTransactionIndividualStatus1Code AcceptedCustomerProfile
    AcceptedTechnicalValidation
    Pending
    Rejected
    CreationDateTime 1..1 OBPaymentSetupResponse1/Data/CreationDateTime Date and time at which the resource was created. ISODateTime
    Initiation 1..1 OBPaymentSetupResponse1/Data/Initiation The 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
    InstructionIdentification 1..1 OBPaymentSetupResponse1/Data/Initiation/InstructionIdentification Unique 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
    EndToEndIdentification 1..1 OBPaymentSetupResponse1/Data/Initiation/EndToEndIdentification Unique 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
    InstructedAmount 1..1 OBPaymentSetupResponse1/Data/Initiation/InstructedAmount Amount 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 TotalDigits: 18
    FractionDigits: 5
    Currency 1..1 OBPaymentSetupResponse1/Data/Initiation/InstructedAmount/Currency A 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}
    DebtorAgent 0..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAgent Financial institution servicing an account for the debtor. OBBranchAndFinancialInstitutionIdentification2
    SchemeName 1..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAgent/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalFinancialInstitutionIdentification2Code BICFI
    UKSortCode
    Identification 1..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAgent/Identification Unique and unambiguous identification of a person. Max35Text
    DebtorAccount 0..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAccount Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. OBCashAccountDebtor1
    SchemeName 1..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalAccountIdentification2Code BBAN
    IBAN
    Identification 1..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max34Text
    Name 0..1 OBPaymentSetupResponse1/Data/Initiation/DebtorAccount/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.

    Max70Text
    SecondaryIdentification 0..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
    CreditorAgent 1..1 OBPaymentSetupResponse1/Data/Initiation/CreditorAgent Financial institution servicing an account for the creditor. OBBranchAndFinancialInstitutionIdentification2
    SchemeName 1..1 OBPaymentSetupResponse1/Data/Initiation/CreditorAgent/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalFinancialInstitutionIdentification2Code BICFI
    UKSortCode
    Identification 1..1 OBPaymentSetupResponse1/Data/Initiation/CreditorAgent/Identification Unique and unambiguous identification of a person. Max35Text
    CreditorAccount 1..1 OBPaymentSetupResponse1/Data/Initiation/CreditorAccount Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. OBCashAccountCreditor1
    SchemeName 1..1 OBPaymentSetupResponse1/Data/Initiation/CreditorAccount/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalAccountIdentification2Code BBAN
    IBAN
    Identification 1..1 OBPaymentSetupResponse1/Data/Initiation/CreditorAccount/Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max34Text
    Name 1..1 OBPaymentSetupResponse1/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
    SecondaryIdentification 0..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
    RemittanceInformation 0..1 OBPaymentSetupResponse1/Data/Initiation/RemittanceInformation Information 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
    Unstructured 0..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
    Reference 0..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
    Risk 1..1 OBPaymentSetupResponse1/Risk The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments. OBRisk1
    PaymentContextCode 0..1 OBPaymentSetupResponse1/Risk/PaymentContextCode Specifies the payment context OBExternalPaymentContext1Code BillPayment
    EcommerceGoods
    EcommerceServices
    Other
    PersonToPerson
    MerchantCategoryCode 0..1 OBPaymentSetupResponse1/Risk/MerchantCategoryCode Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction. Min3Max4Text
    MerchantCustomerIdentification 0..1 OBPaymentSetupResponse1/Risk/MerchantCustomerIdentification The unique customer identifier of the PSU with the merchant. Max70Text
    DeliveryAddress 0..1 OBPaymentSetupResponse1/Risk/DeliveryAddress Information that locates and identifies a specific address, as defined by postal services or in free format text. PostalAddress18
    AddressLine 0..2 OBPaymentSetupResponse1/Risk/DeliveryAddress/AddressLine Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. Max70Text
    StreetName 0..1 OBPaymentSetupResponse1/Risk/DeliveryAddress/StreetName Name of a street or thoroughfare. Max70Text
    BuildingNumber 0..1 OBPaymentSetupResponse1/Risk/DeliveryAddress/BuildingNumber Number that identifies the position of a building on a street. Max16Text
    PostCode 0..1 OBPaymentSetupResponse1/Risk/DeliveryAddress/PostCode Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. Max16Text
    TownName 1..1 OBPaymentSetupResponse1/Risk/DeliveryAddress/TownName Name of a built-up area, with defined boundaries, and a local government. Max35Text
    CountrySubDivision 0..2 OBPaymentSetupResponse1/Risk/DeliveryAddress/CountrySubDivision Identifies a subdivision of a country, for instance state, region, county. Max35Text
    Country 1..1 OBPaymentSetupResponse1/Risk/DeliveryAddress/Country Nation 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
    Name Occurrence XPath EnhanceddDefinition Class Codes Pattern
    AddressLine 0..2 OBPaymentSubmission1/Risk/DeliveryAddress/AddressLine Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. Max70Text
    BuildingNumber 0..1 OBPaymentSubmission1/Risk/DeliveryAddress/BuildingNumber Number that identifies the position of a building on a street. Max16Text
    Country 1..1 OBPaymentSubmission1/Risk/DeliveryAddress/Country Nation with its own government, occupying a particular territory. CountryCode [A-Z]{2,2}
    CountrySubDivision 0..2 OBPaymentSubmission1/Risk/DeliveryAddress/CountrySubDivision Identifies a subdivision of a country, for instance state, region, county. Max35Text
    CreditorAccount 1..1 OBPaymentSubmission1/Data/Initiation/CreditorAccount Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. OBCashAccountCreditor1
    CreditorAgent 1..1 OBPaymentSubmission1/Data/Initiation/CreditorAgent Financial institution servicing an account for the creditor. OBBranchAndFinancialInstitutionIdentification2
    Currency 1..1 OBPaymentSubmission1/Data/Initiation/InstructedAmount/Currency A 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}
    Data 1..1 OBPaymentSubmission1/Data OBPaymentDataSubmission1
    DebtorAccount 0..1 OBPaymentSubmission1/Data/Initiation/DebtorAccount Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. OBCashAccountDebtor1
    DebtorAgent 0..1 OBPaymentSubmission1/Data/Initiation/DebtorAgent Financial institution servicing an account for the debtor. OBBranchAndFinancialInstitutionIdentification2
    DeliveryAddress 0..1 OBPaymentSubmission1/Risk/DeliveryAddress Information that locates and identifies a specific address, as defined by postal services or in free format text. PostalAddress18
    EndToEndIdentification 1..1 OBPaymentSubmission1/Data/Initiation/EndToEndIdentification Unique 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
    Identification 1..1 OBPaymentSubmission1/Data/Initiation/DebtorAgent/Identification Unique and unambiguous identification of a person. Max35Text
    Identification 1..1 OBPaymentSubmission1/Data/Initiation/DebtorAccount/Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max34Text
    Identification 1..1 OBPaymentSubmission1/Data/Initiation/CreditorAgent/Identification Unique and unambiguous identification of a person. Max35Text
    Identification 1..1 OBPaymentSubmission1/Data/Initiation/CreditorAccount/Identification Identification assigned by an institution to identify an account. This identification is known by the account owner. Max34Text
    Initiation 1..1 OBPaymentSubmission1/Data/Initiation The 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
    InstructedAmount 1..1 OBPaymentSubmission1/Data/Initiation/InstructedAmount Amount 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 TotalDigits: 18
    FractionDigits: 5
    InstructionIdentification 1..1 OBPaymentSubmission1/Data/Initiation/InstructionIdentification Unique 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
    MerchantCategoryCode 0..1 OBPaymentSubmission1/Risk/MerchantCategoryCode Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction. Min3Max4Text
    MerchantCustomerIdentification 0..1 OBPaymentSubmission1/Risk/MerchantCustomerIdentification The unique customer identifier of the PSU with the merchant. Max70Text
    Name 0..1 OBPaymentSubmission1/Data/Initiation/DebtorAccount/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.

    Max70Text
    Name 1..1 OBPaymentSubmission1/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
    OBPaymentSubmission1 OBPaymentSubmission1 OBPaymentSubmission1
    PaymentContextCode 0..1 OBPaymentSubmission1/Risk/PaymentContextCode Specifies the payment context OBExternalPaymentContext1Code BillPayment
    EcommerceGoods
    EcommerceServices
    Other
    PersonToPerson
    PaymentId 1..1 OBPaymentSubmission1/Data/PaymentId OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource. Max128Text
    PostCode 0..1 OBPaymentSubmission1/Risk/DeliveryAddress/PostCode Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. Max16Text
    Reference 0..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
    RemittanceInformation 0..1 OBPaymentSubmission1/Data/Initiation/RemittanceInformation Information 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
    Risk 1..1 OBPaymentSubmission1/Risk The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments. OBRisk1
    SchemeName 1..1 OBPaymentSubmission1/Data/Initiation/DebtorAgent/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalFinancialInstitutionIdentification2Code BICFI
    UKSortCode
    SchemeName 1..1 OBPaymentSubmission1/Data/Initiation/DebtorAccount/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalAccountIdentification2Code BBAN
    IBAN
    SchemeName 1..1 OBPaymentSubmission1/Data/Initiation/CreditorAgent/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalFinancialInstitutionIdentification2Code BICFI
    UKSortCode
    SchemeName 1..1 OBPaymentSubmission1/Data/Initiation/CreditorAccount/SchemeName Name of the identification scheme, in a coded form as published in an external list. OBExternalAccountIdentification2Code BBAN
    IBAN
    SecondaryIdentification 0..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
    SecondaryIdentification 0..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
    StreetName 0..1 OBPaymentSubmission1/Risk/DeliveryAddress/StreetName Name of a street or thoroughfare. Max70Text
    TownName

    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
    Name Occurrence XPath EnhanceddDefinition Class Codes Pattern
    CreationDateTime 1..1 OBPaymentSubmissionResponse1/Data/CreationDateTime Date and time at which the resource was created. ISODateTime
    Data 1..1 OBPaymentSubmissionResponse1/Data OBPaymentDataSubmissionResponse1
    OBPaymentSubmissionResponse1 OBPaymentSubmissionResponse1 OBPaymentSubmissionResponse1
    PaymentId 1..1 OBPaymentSubmissionResponse1/Data/PaymentId OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource. Max128Text
    PaymentSubmissionId 1..1 OBPaymentSubmissionResponse1/Data/PaymentSubmissionId OB: Unique identification as assigned by the ASPSP to uniquely identify the payment submission resource. Max40Text
    Status 0..1 OBPaymentSubmissionResponse1/Data/Status Specifies the status of the payment submission resource. OBTransactionIndividualStatus1Code AcceptedSettlementCompleted
    AcceptedSettlementInProcess
    Pending
    Rejected

    Data Payload – Enumerations

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

    Code Class Name Definition
    OBExternalAccountIdentification2Code BBAN Basic Bank Account Number (BBAN) – identifier used nationally by financial institutions, ie, in individual countries, generally as part of a National Account Numbering Scheme(s), to uniquely identify the account of a customer.
    OBExternalAccountIdentification2Code IBAN An 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)”.
    OBExternalFinancialInstitutionIdentification2Code BICFI Valid 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.
    OBExternalFinancialInstitutionIdentification2Code UKSortCode United Kingdom (UK) Sort Code – identifies British financial institutions on the British national clearing systems. The sort code is assigned by Payments UK.
    OBExternalPaymentContext1Code BillPayment The context of the payment initiation is a bill payment.
    OBExternalPaymentContext1Code EcommerceGoods The context of the payment initiation is a for goods via an ecommerce channel.
    OBExternalPaymentContext1Code EcommerceServices The context of the payment initiation is a for services via an ecommerce channel.
    OBExternalPaymentContext1Code PersonToPerson The context of the payment initiation is a person to person payment.
    OBExternalPaymentContext1Code Other The context of the payment initiation is of an other type.
    OBTransactionIndividualStatus1Code AcceptedCustomerProfile Preceding check of technical validation was successful. Customer profile check was also successful.
    OBTransactionIndividualStatus1Code AcceptedSettlementCompleted 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.

    OBTransactionIndividualStatus1Code AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
    OBTransactionIndividualStatus1Code AcceptedTechnicalValidation Authentication and syntactical and semantic validation are successful.
    OBTransactionIndividualStatus1Code Pending Payment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
    OBTransactionIndividualStatus1Code Rejected Payment 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.

    Generated Identifier Business Description
    Merchant/PISP

    Sent in API Payload

    EndToEndIdentification The 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

    RemittanceInformation The RemittanceInformation is the reference information that creditor (or beneficiary) will need to reconcile (e.g. Invoice 123).
    ASPSP / API System PaymentId Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.
    ASPSP / API System PaymentSubmissionId Unique identification as assigned by the ASPSP to uniquely identify the payment-submission resource.
    ASPSP / Payment Scheme Scheme Payment ID This 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 => => =>
    RemittanceInformation O => => => =>
    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
    • Scheme requirements (in draft):
      • 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.

    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.

    Name XPath Occurrence Class ISO8583
    BIT
    FPS Field Name Mandatory Size
    Initiation Initiation 1..1 OBInitiation1
    InstructionIdentification Initiation/InstructionIdentification 1..1 Max35Text
    EndToEndIdentification Initiation/EndToEndIdentification 1..1 Max35Text 62 END TO END REFERENCE O 31
    InstructedAmount Initiation/InstructedAmount 1..1 TotalDigits: 18, FractionDigits: 5 6 AMOUNT M 14
    Currency Initiation/InstructedAmount/Currency 1..1 ActiveOrHistoricCurrencyCode
    DebtorAgent Initiation/DebtorAgent 0..1
    SchemeName Initiation/DebtorAgent/SchemeName 1..1
    Identification Initiation/DebtorAgent/Identification 1..1 Max35Text 42 ORIGINATING CREDIT INSTITUTION M 11
    DebtorAccount Initiation/DebtorAccount 0..1
    SchemeName Initiation/DebtorAccount/SchemeName 1..1
    Identification Initiation/DebtorAccount/Identification 1..1 Max34Text 43 ORIGINATING CUSTOMER ACCOUNT NUMBER M 34
    Name Initiation/DebtorAccount/Name 0..1
    SecondaryIdentification Initiation/DebtorAccount/SecondaryIdentification 0..1
    CreditorAgent Initiation/CreditorAgent 1..1
    SchemeName Initiation/CreditorAgent/SchemeName 1..1
    Identification Initiation/CreditorAgent/Identification 1..1 Max35Text 95 BENEFICIARY CREDIT INSTITUTION M 11
    CreditorAccount Initiation/CreditorAccount 1..1
    SchemeName Initiation/CreditorAccount/SchemeName 1..1
    Identification Initiation/CreditorAccount/Identification 1..1 Max34Text 35 BENEFICIARY CUSTOMER ACCOUNT NUMBER M 34
    Name Initiation/CreditorAccount/Name 1..1 Max70Text 118 BENEFICIARY CUSTOMER ACCOUNT NAME O 40
    SecondaryIdentification Initiation/CreditorAccount/SecondaryIdentification 0..1 Max34Text 120 REFERENCE INFORMATION O 18
    RemittanceInformation Initiation/RemittanceInformation 0..1
    Unstructured Initiation/RemittanceInformation/Unstructured 0..1 Max140Text 121 REMITTANCE INFORMATION O 140
    Reference Initiation/RemittanceInformation/Reference 0..1 Max35Text 120 REFERENCE INFORMATION O 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

    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.

    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.

    Name XPath Occurrence Class STD18 Field Bacs Field Name Mandatory ? Size
    Initiation Initiation 1..1 OBInitiation1
    InstructionIdentification Initiation/InstructionIdentification 1..1
    EndToEndIdentification Initiation/EndToEndIdentification 1..1
    InstructedAmount Initiation/InstructedAmount 1..1 TotalDigits: 18, FractionDigits: 5 8 amount in pence M 11
    Currency Initiation/InstructedAmount/Currency 1..1
    DebtorAgent Initiation/DebtorAgent 0..1
    SchemeName Initiation/DebtorAgent/SchemeName 1..1
    Identification Initiation/DebtorAgent/Identification 1..1 Max35Text 5 originating sorting code M 6
    DebtorAccount Initiation/DebtorAccount 0..1
    SchemeName Initiation/DebtorAccount/SchemeName 1..1
    Identification Initiation/DebtorAccount/Identification 1..1 Max34Text 6 originating account number M 8
    Name Initiation/DebtorAccount/Name 0..1
    SecondaryIdentification Initiation/DebtorAccount/SecondaryIdentification 0..1
    CreditorAgent Initiation/CreditorAgent 1..1
    SchemeName Initiation/CreditorAgent/SchemeName 1..1
    Identification Initiation/CreditorAgent/Identification 1..1 Max35Text 1 destination sorting code M 6
    CreditorAccount Initiation/CreditorAccount 1..1
    SchemeName Initiation/CreditorAccount/SchemeName 1..1
    Identification Initiation/CreditorAccount/Identification 1..1 Max34Text 2 destination a/c number M 8
    Name Initiation/CreditorAccount/Name 1..1 Max70Text 11 destination account name M 18
    SecondaryIdentification Initiation/CreditorAccount/SecondaryIdentification 0..1 Max34Text 10 service user’s reference M 18
    RemittanceInformation Initiation/RemittanceInformation 0..1
    Unstructured Initiation/RemittanceInformation/Unstructured 0..1
    Reference Initiation/RemittanceInformation/Reference 0..1 Max35Text 10 service user’s reference M 18
    • 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

    An ASPSP may choose to simplify their implementation by ensuring that the access token and account-request have the same expiration date – in such a situation, the access token will not expire within the lifetime of the account-request, and subsequently the ability to re-authenticate an account-request is not required.

    Usage Examples Back To Top

    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

    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: 2017-06-13T11:36:09
    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"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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: 2017-06-13T11:36:09
    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"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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: 2017-06-13T11:36:09
    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"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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: 2017-06-13T11:36:09
    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 (Created), payment-submissions resource
    PISP -> PSU: HTTP 200 (OK)
       
    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: 2017-06-13T11:36:09
    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"
          },
          "DebtorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC112800"
          },
          "DebtorAccount": {
            "SchemeName": "BBAN",
            "Identification": "01234567",
            "Name": "Andrea Smith"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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"
          },
          "DebtorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC112800"
          },
          "DebtorAccount": {
            "SchemeName": "BBAN",
            "Identification": "01234567",
            "Name": "Andrea Smith"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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: 2017-06-13T11:36:09
    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"
          },
          "DebtorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC112800"
          },
          "DebtorAccount": {
            "SchemeName": "BBAN",
            "Identification": "01234567",
            "Name": "Andrea Smith"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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: 2017-06-13T11:36:09
    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"
          },
          "DebtorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC112800"
          },
          "DebtorAccount": {
            "SchemeName": "BBAN",
            "Identification": "01234567",
            "Name": "Andrea Smith"
          },
          "CreditorAgent": {
            "SchemeName": "UKSortCode",
            "Identification": "SC080800"
          },
          "CreditorAccount": {
            "SchemeName": "BBAN",
            "Identification": "21325698",
            "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: 2017-06-13T11:36:09
    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

    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

    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

    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.

    Sudden Burst of API Requests

    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}
            ASPSP Resource Server -> PISP: HTTP 429 (Too Many Requests)
        end
    end

    Failed Authorization Consent

    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