Payment Initiation API Specification - v1.0.0
Version Control
Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 23 Jun 2017 | Open Banking Read/Write API Team | This is the Baseline version. No Changes from v1.0 RC4. |
Overview
This Payment Initiation API Specification describes the flows and payloads for initiating a single immediate domestic payment.
The API endpoints described here allow a PISP to:
- Register an intent to setup a payment instruction
- Subsequently submit the payment instruction for processing
- Optionally retrieve the status of a payment setup or submission.
Document Overview
This document consists of the following parts:
Overview: Provides an overview of the scope of the API and the key decisions and principles that contributed to the specification.
Basics: The section begins with an introduction to how the API is to used to initiate a single, immediate, domestic payment. It goes on to identify the resources and operations that are permitted on those resources and various special cases.
Security & Access Control: Specifies the means for PISPs and PSUs to authenticate themselves and provide consent.
Swagger Specifications: Provides links to the swagger specifications for the APIs.
Data Model: Describes the data model for the API payloads.
Usage Examples: Examples for normal flows, and alternate flows.
Design Principles
RESTful APIs
The API adheres to RESTful API concepts where possible and sensible to do so.
However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.
References:
- The highest level Data Description Language used is the JSON Schema : http://json-schema.org/
- Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/
- The Interface Description Language used is the Swagger Specification version 2.0 (also known as Open API) : http://swagger.io/ and
Standards
The OBIE principles for developing the new API standards:
- OBIE will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.
- The initial scope of these Standards is limited to current OBIE scope - i.e., meeting CMA remedies. However, the intention is that the scope of the Standards will extend to either include or align to initiatives to cover a wider scope (i.e., PSD2).
- The Standards currently being reviewed include ISO20022, and FAPI.
- OBIE will favour developer/user experience over and above adoption of existing Standards, in order to create a more future proof Standard.
- OBIE will work with other relevant bodies to align with, contribute to and/or adopt other Standards work, especially relating to creation of Standards around APIs and JSON payloads.
ISO 20022
The CMA Order requires the CMA9 Banks to be aligned with the Regulatory and Technical Standards (RTS) under PSD2.
A previous draft of the EBA RTS required that the interface "shall use ISO 20022 elements, components or approved message definitions". In keeping with that requirement, the API payloads are designed using the ISO 20022 message elements and components where available.
The principles we have applied to re-use of ISO message elements and components are:
- Where relevant - the API payloads have been flattened so that they are more developer friendly. This has been a request from the developer community, and the stakeholders involved in the design workshop.
- Only elements that are required for the functioning of the API endpoint will be included in the API payload. API endpoints are defined for specific use-cases (not to be generically extensible for all use-cases). Hence - only elements that are required for a single immediate payment initiation are included in the Payment API payload for v1.0 (as this is the agreed scope for our v1.0 specification).
- We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.). An example is having latitude and longitude in decimal format - as this is how developers will work with latitude and longitude; or using simple types (e.g., a single date-time field) instead of a complex type (e.g., a choice field with a nesting of date and time).
Extensibility
Version 1.0 of the Payment API only caters for the setup and submission of a single, immediate, domestic payment.
However, it is intended that the API flows will be extended to cater for more complex use-cases in subsequent releases - and we have kept this in mind during the design. It is expected that the API payloads will evolve to cater for other payment types (e.g., future dated, recurring, bulk etc.)
Idempotency
POST operations on both the /payments and /payment-submissions endpoint are designed to be idempotent.
Details on idempotency can be founds in the section on Basics / Idempotency.
Non-Repudiation
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
Overview
The figure below provides a general outline of a payment flow using the Payment APIs.
Steps
Step 1: Request Payment Intitation
- This flow begins with a PSU consenting to a payment being made. The request is sent through a PISP.
- The debtor account details can optionally be specified at this stage.
Step 2: Setup Single Payment Initiation
- The PISP connects to the ASPSP that services the PSU's payment account and creates a new payments resource. This informs the ASPSP that one of its PSUs intends to make a payment. The ASPSP responds with an identifier for the resource (the PaymentId - which is the intent identifier).
- This step is carried out by making a POST request to the payments resource.
Step 3: Authorise Consent
- The PISP redirects the PSU to the ASPSP. The redirect includes the PaymentId generated in the previous step. This allows the ASPSP to correlate the payment that was setup. The ASPSP authenticates the PSU. This could be an SCA if the ASPSP determines that none of the SCA exemptions apply. The ASPSP updates the state of the payments resource internally to indicate that the payment has been authorized.
- The PSU selects the debtor account at this stage - if it has not been previously specified in Step 1.
- The PSU is redirected back to the PISP.
Step 4: Create Payment Submission
- Once the PSU is redirected to the PISP, the PISP creates a payment-submissions resource to indicate that the payment created in the steps above should be submitted for processing.
- This is carried out by making a POST request to the payment-submissions resource.
- ASPSP returns the PaymentSubmissionId to the PISP.
Step 5: Get Payment Submission Status
- If the ASPSP provides a status API, the PISP can check the status of the payment (with the PaymentId) or payment-submission (with the PaymentSubmissionId).
- This is carried out by making a GET request to the payments or payment-subsmissions resource.
Sequence Diagram
Actors
Actor | Abbreviation | Type | Specializes | Description |
---|---|---|---|---|
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) |
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. |
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 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 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-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 |
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 |
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 |
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 |
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 |
x-idempotency-key | Custom HTTP Header; Unique request identifier to support idempotency. Mandatory for POST requests. | Mandatory | Do not use |
x-jws-signature | Header containing a detached JWS signature of the body of the payload. Mandatory for requests that contain a payload. A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means of non-repudiation. This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures. | TBC | TBC |
(Reference: Section 6.3 - Financial API — Part 1: Read Only API Security Profile (Implementer’s Draft).)
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
- The TPP must have completed onboarding on the Open Banking Directory.
- 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
- The ASPSP must have completed onboarding on the Open Banking Directory.
- 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 hte signature can be verified.
Specification
The TPP must sign the HTTP body of each API request that has an HTTP body. (e.g. GET requests do not have an HTTP body and are not signed.)
The ASPSP must sign the HTTP body of each API response that it produces which has an HTTP body.
The ASPSP should verify the signature of API requests that it receives before carrying out the request. If the signature fails validation, the ASPSP must respond with a 400 (Bad Request).
The ASPSP must reject any API requests that should be signed but do not contain a signature in the HTTP header with a 400 (Bad Request) error.
The TPP should verify the signature of API responses that it receives.
Process for signing a payload
Step 1: Identify the private key and corresponding signing certificate to be used for signing
The signer must use a private key that has a corresponding digital certificate (that contains the corresponding public key) issued by OB.
The signing certificate must be valid at the time of creating the JWS.
Step 2: Form the JOSE Header
The JOSE header for the signature must contain the following fields
Claim | Description |
---|---|
alg | The algorithm that will be used for signing the JWS. The list of valid algorithms is here https://tools.ietf.org/html/rfc7518#section-3.1. The algorithms that will be supported by OB will be specified in the future. |
kid | This must match the certificate id of the certificate selected in step 1. |
b64 | This must have the boolean value false. This indicates that the message payload is not base64 url encoded. |
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 veriier must ensure that the http://openbanking.org.uk/iss claim matches the dn of the certificate.
The verifier must ensure that the crit claim does not contain additional critical elements.
Step 3: Verify the signature
The verifier must verify the signature by decrypting it and ensuring that it matches the ExpectedSignedPayload.
DecryptedPayload = base64Decode ( decrypt ( publicKey, Signature));
Sample JOSE Header
{ "alg": "RS512", "kid": "90210ABAD", "b64": false, "http://openbanking.org.uk/iat": "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
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
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}
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
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}
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 | AcceptedSettlementInProcess | All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution. |
4 | AcceptedSettlementCompleted | Settlement on the debtor's account has been completed. |
Security & Access Control
API Scopes
The access tokens required for accessing the Payment APIs must have at least the following scope:
payments
Grants Types
PISPs must use a client credentials grant to obtain a token to make POST requests to the payments resource.
PISPs must use a authorization code grant to obtain a token to make POST requests to the payment-submissions resource.
PISPs may use a either a client credentials grant or an authorization code grant to obtain a token to make GET requests.
Consent Authorisation
OAuth 2.0 scopes are coarse grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine grained scopes (e.g. a scope to enforce payments of a specified amount on a specified date).
A consent authorisation is used to define the fine-grained scope that is granted by the PSU to the PISP.
The PISP must begin a single immediate payment request by creating a payments resource through a POST operation. This resource indicates the consent that the PISP claims it has been given by the PSU. At this stage, the consent is not yet authorised as the ASPSP has not yet verified this claim with the PSU.
The ASPSP responds with a PaymentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).
As part of the authorization code grant:
- The ASPSP authenticates the PSU.
- The ASPSP plays back the consent (registered by the PISP) back to the PSU - to get consent authorisation. The PSU may accept or reject the consent in its entirity (but not selectively).
- If the consent did not indicate a debtor account, the ASPSP presents the PSU a list of accounts from which the PSU may select one.
Once these steps are complete, the consent is considered to have been authorised by the PSU.
Payment Status
The Payment resource can have one of the following ISO status codes after authorisation has taken place:
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. |
Error Condition
If the PSU does not complete a successful consent authorisation (e.g. if the PSU is not authenticated successfully), the authorization code grant ends with a redirection to the TPP with an error response as described in RFC 6749 Section 4.1.2.1. The PSU is redirected to the TPP with a error parameter indicating the error that occoured.
Consent Revocation
A PSU cannot revoke consent for a single immediate payment - once it has been authorized.
This is required to comply with Article 80 of PSD2.
Changes to Selected Account
For a single immediate payment, the selected debtor account cannot be changed once the consent has been authorized.
Handling Expired Access Tokens
Access Token issued through Client Credentials Grant
When an access token issued through a Client Credentials Grant expires, the TPP must get a new access token by executing a client credential grant again.
Access Token issued through Authorization Code Grant
Due to the immediate nature of single immediate payments, an access token is unlikely to expire before it is used for creating the payment-submission. Consequently, issuing a refresh token along with the access token is not useful in this situation.
However, to simplify their implementation, an ASPSP may issue a refresh token along with an access token at the end of an authorisation code grant.
When an access token obtained through an authorisation code grant expires, the TPP may attempt to get a new access and refresh token as defined in Section 6 of the OAuth 2.0 specification.
If the TPP fails to get an access token using a refresh token, the TPP would have to get the PSU to initiate a fresh authorisation code grant using an existing intent-id.
An ASPSP may choose to simplify their implementation by ensuring that the tokens and consent authorisation have the same period of validity - in such a situation, the tokens will not expire within the lifetime of the consent authorisation and subsequently the ability to re-authenticate will not be required.
Risk Scoring Information
During the design workshops ASPSPs articulated a need to perform risk scoring on the payments initiated via the Payment API.
Information for risk scoring and assessment will come via:
- FAPI HTTP headers. These are defined in Section 6.3 of the FAPI specification and in the Headers section above.
- Additional fields identified by the industry as business logic security concerns - which will be passed in the Risk section of the payload in the JSON object.
These are the set of additional fields in the risk section of the payload for v1.0 - which will be specified by the PISP:
- PaymentContextCode
- MerchantCategoryCode
- MerchantCustomerIdentification
- DeliveryAddress
The PaymentContextCode describes the payment context and can have these values:
- BillPayment
- EcommerceGoods
- EcommerceServices
- Other
- PersonToPerson
Payments for EcommerceGoods and EcommerceServices will be expected to have a MerchantCategoryCode and MerchantCustomerIdentification populated. Payments for EcommerceGoods will also have the DeliveryAddress populated.
These fields are documented further in the Data Payload section.
Swagger Specification
The swagger specification for Payment Initiation APIs can be downloaded from the following links:
- JSON
- YAML
Data Model
High Level Payload Structure
This section gives an overview of the top level structure for the API payloads for the Payment APIs.
The Data and Risk sections of the payload structure are documented in Data Dictionary section; while the Links and Meta are standardised - which are explained in the Response Structure.
Request Structure
The top level request structure for Payment APIs:
{ "Data": { "Initiation": { ... } }, "Risk": { ... } }
The top level structure for the Payment API POST requests will be:
Data
- Initiation
Risk
The Data section contains the payment initiation object.
A separate Initiation section within the Data section gives us the flexibility to extend and modify the Initiation section in isolation.
A Risk section for the request structure has been separated out - so that this can evolve in isolation from the Initiate section of the payload.
Response Structure
The top level response structure for Payment APIs:
{ "Data": { ... "Initiation": { ... } }, "Risk": { ... }, "Links": { ... }, "Meta": { ... } }
In line with the principle on RESTful API practices - we are replaying the full resource as part of the response.
Two additional top level sections are included in the response for:
Links
Meta
The Links section is mandatory and will always contain URIs to related resources,
The "self" member is mandatory, the other members "first", "prev", "next", "last" are optional.
For example:
"Links": { "self": "http://example.com/articles?page[number]=3&page[size]=1", "first": "http://example.com/articles?page[number]=1&page[size]=1", "prev": "http://example.com/articles?page[number]=2&page[size]=1", "next": "http://example.com/articles?page[number]=4&page[size]=1", "last": "http://example.com/articles?page[number]=13&page[size]=1" }
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:
"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 | TotalDigits: 18 FractionDigits: 5 | |
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. 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 | 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 | 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. 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 | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBPaymentSubmission1 | OBPaymentSubmission1 | OBPaymentSubmission1 | ||||
Data | 1..1 | OBPaymentSubmission1/Data | OBPaymentDataSubmission1 | |||
PaymentId | 1..1 | OBPaymentSubmission1/Data/PaymentId | OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource. | Max128Text | ||
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 | ||
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 | ||
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 | ||
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 | |
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} | |
DebtorAgent | 0..1 | OBPaymentSubmission1/Data/Initiation/DebtorAgent | Financial institution servicing an account for the debtor. | OBBranchAndFinancialInstitutionIdentification2 | ||
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 | |
Identification | 1..1 | OBPaymentSubmission1/Data/Initiation/DebtorAgent/Identification | Unique and unambiguous identification of a person. | Max35Text | ||
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 | ||
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 | |
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 | ||
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 | ||
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 | ||
CreditorAgent | 1..1 | OBPaymentSubmission1/Data/Initiation/CreditorAgent | Financial institution servicing an account for the creditor. | OBBranchAndFinancialInstitutionIdentification2 | ||
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 | |
Identification | 1..1 | OBPaymentSubmission1/Data/Initiation/CreditorAgent/Identification | Unique and unambiguous identification of a person. | 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 | ||
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 | |
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 | ||
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. | Max70Text | ||
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 | ||
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 | ||
Unstructured | 0..1 | OBPaymentSubmission1/Data/Initiation/ RemittanceInformation/Unstructured | Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form. | Max140Text | ||
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 | ||
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 | ||
PaymentContextCode | 0..1 | OBPaymentSubmission1/Risk/PaymentContextCode | Specifies the payment context | OBExternalPaymentContext1Code | BillPayment EcommerceGoods EcommerceServices Other PersonToPerson | |
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 | ||
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 | ||
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 | ||
StreetName | 0..1 | OBPaymentSubmission1/Risk/DeliveryAddress/StreetName | Name of a street or thoroughfare. | Max70Text | ||
BuildingNumber | 0..1 | OBPaymentSubmission1/Risk/DeliveryAddress/BuildingNumber | Number that identifies the position of a building on a street. | Max16Text | ||
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 | ||
TownName | 1..1 | OBPaymentSubmission1/Risk/DeliveryAddress/TownName | Name of a built-up area, with defined boundaries, and a local government. | Max35Text | ||
CountrySubDivision | 0..2 | OBPaymentSubmission1/Risk/DeliveryAddress/CountrySubDivision | Identifies a subdivision of a country, for instance state, region, county. | Max35Text | ||
Country | 1..1 | OBPaymentSubmission1/Risk/DeliveryAddress/Country | Nation with its own government, occupying a particular territory. | CountryCode | [A-Z]{2,2} |
Payment Submission - Response
The OBPaymentSubmissionResponse1 object will be used for a response to a call to:
- POST /payment-submissions
- GET /payment-submissions/{PaymentSubmissionId}
UML Diagram
Notes
The Payment Submission POST response contains the:
- PaymentSubmissionId
- PaymentId
- Status of the payment-submission resource
- Date time the payment-submission resource was created
Data Dictionary
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBPaymentSubmissionResponse1 | OBPaymentSubmissionResponse1 | OBPaymentSubmissionResponse1 | ||||
Data | 1..1 | OBPaymentSubmissionResponse1/Data | OBPaymentDataSubmissionResponse1 | |||
PaymentSubmissionId | 1..1 | OBPaymentSubmissionResponse1/Data/PaymentSubmissionId | OB: Unique identification as assigned by the ASPSP to uniquely identify the payment submission resource. | Max40Text | ||
PaymentId | 1..1 | OBPaymentSubmissionResponse1/Data/PaymentId | OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource. | Max128Text | ||
Status | 0..1 | OBPaymentSubmissionResponse1/Data/Status | Specifies the status of the payment submission resource. | OBTransactionIndividualStatus1Code | AcceptedSettlementCompleted AcceptedSettlementInProcess Pending Rejected | |
CreationDateTime | 1..1 | OBPaymentSubmissionResponse1/Data/CreationDateTime | Date and time at which the resource was created. | ISODateTime |
Data Payload - Enumerations
This section gives the definitions for enumerations used in the Payment APIs.
Code 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. 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 |