...

• Register an intent to stage a payment-order consents.consent

• Optionally confirm available funds for a payment-order for Domestic payments and International international immediate payments .only

• Subsequently submit the payment-order for processing.

• Optionally retrieve Retrieve the status of a payment-order consentsconsent or payment-order resource.

...

1.1 Document Overview

This document consists of the following parts:

Overview: Provides an overview of the profile.

Basics: Identifies the flows, restrictions, etc.

Security & Access Control: Specifies the means for PISPs and usersUser/customers Customers to authenticate themselves and provide consents.consent

Data Model: Documents mappings and enumerations that apply to all the end-points.

Alternative Flows: Documents rules for alternative flows.

1.2 Resources

Each of the Payment Initiation API resources are documented in the the Resources and Data Models / PISP area PISP area of the specification. Each resource is documented with:

• Endpoints

  • The API endpoints available for the resource.

• Data Model

  • Resource definition.

  • UML diagram.

  • Data dictionary - which defines fields, re-usable classes, mandatory (1..1) or conditional (0..1) as defined in the Design Principles section, and enumerations.

• Usage Examples

1.3  Design Principles

1.3.1 Status Codes

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

• The HTTP Status Code reflects the outcome of the API call (the HTTP operation on the resource).

• The Status field for the payment-order consents consent reflects the status of the userUser/customer consents Customer consent authorisation.

• The Status field for the payment-order resource reflects the status of the payment-order initiation or execution.

2.  Basics

2.1  Overview

The figure below provides a general outline of a payment flow for all payment-order types using the Payment APIs. The payment-order types covered in this profile include:

• Domestic paymentsSingle

• Domestic Payment.

• Single Future Dated Domestic Payment.

• Single International payment.

• Bulk/Batch Payment.future dated payments

• Domestic standing orders

• International payments

The payment-order consents consent and payment-order resource in the following flow generalises for the different payment-order types. E.g. for a domestic payment, the payment-order consents consent resource is domestic-payment-consents; and the payment-order resource is domestic-payments.

...

Step 1: Agree Payment-Order Initiation

• This flow begins with a userUser/customer Customer consenting to a payment being made. The consents consent is between the userUser/customer Customer and the PISP.

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

Step 2: Setup Payment-Order ConsentsConsent

• The PISP connects to the ASPSP that services the user’sUser/customer’s Customer's payment account and creates a new payment-order consentsconsent resource. This informs the ASPSP that one of its usersUser/customers Customers intends to make a payment-order. The ASPSP responds with an identifier for the payment-order consents consent resource (the ConsentId, which is the intent identifier).

• This step is carried out by making a POST request to the payment-order consentsconsent resource.

Step 3: Authorise ConsentsConsent

• The PISP requests the userUser/customer Customer to authorise the consentsconsent. The ASPSP may carry this out by using a redirection flow or a decoupled flow.

  • In a redirection flow, the PISP redirects the userUser/customer Customer to the ASPSP .

    • The redirect includes the ConsentId generated in the previous step.

    • This allows the ASPSP to correlate the payment order consents consent that was setup.

    • The ASPSP authenticates the userUser/customer.Customer

    • The userUser/customer Customer selects the debtor account at this stage (if it has not been previously specified in Step 1).

    • The ASPSP updates the state of the payment order consents consent resource internally to indicate that the consents consent has been authorised.

    • Once the consents consent has been authorised, the userUser/customer Customer is redirected back to the PISP.

  • In a decoupled flow, the ASPSP requests the userUser/customer Customer to authorise consents consent on an authentication device that is separate from the consumption device on which the userUser/customer Customer is interacting with the PISP.

    • The decoupled flow is initiated by the PISP calling a back-channel authorisation request.

    • The request contains a 'hint' that identifies the userUser/customer Customer paired with the consents consent to be authorised.

    • The ASPSP authenticates the userUser/customer.Customer

    • The userUser/customer Customer selects the debtor account at this stage (if it has not been previously specified in Step 1).

    • The ASPSP updates the state of the payment order consents consent resource internally to indicate that the consents consent has been authorised.

    • Once the consents consent has been authorised, the ASPSP can make a callback to the PISP to provide an access token.

Step  Step 4: Confirm Funds (Domestic and International Single Immediate international immediate Payments Only)

• Once the userUser/customer Customer is authenticated and has authorised the payment-order-consentsconsent, the PISP can check whether funds are available to make the payment.

• This is carried out by making a GET request, calling the funds-confirmation operator on the payment-order-consentsconsent resource.

Step 5: Create Payment-Order

• The PISP creates a payment-order 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 appropriate payment-order resource.

• The ASPSP returns the identifier for the payment-order resource to the PISP.

Step 6: Get ConsentsConsent/Payment-Order/Payment-Details Status

• The PISP can check the status of the payment-order consents consent (with the ConsentId) or payment-order resource (with the payment-order resource identifier) or payment-details (with the payment-order resource identifier).

• This is carried out by making a GET request to the payment-order consentsconsent or payment-order or payment-details resource.  

2.1.2 Sequence Diagram

...

* CIBA- Client Initiated Backchannel Authentication

2.2  Payment Restrictions

...

• The maximum InstructedAmount allowable.

• The domestic-standing-order Frequency patterns supported.

• The maximum future date on a future dated payment.

Each ASPSP must determine appropriate restrictions that they support based on their individual practices, standards and limitations. These restrictions should be documented on ASPSP developer portals.

An ASPSP must reject the payment-order consentsconsent if the ASPSP is unable to handle the request.

...

An ASPSP may return the specific CutOffDateTime when responding to a payment-order consents consent request.

An ASPSP must document the behaviour for a payment receipt before and after the CutOffDateTime for a payment-order has elapsed.

...

• Reject the payment-order (and steps associated with the creation of payment-order) if received after the applicable CutOffDateTime.

• Accept the payment-order (and steps associated with the creation of payment-order) if received after the applicable CutOffDateTime.

2.2.1.1  Reject the Payment-Order

In this scenario, the behaviour of payment-order execution is explicit to the PISP and userUser/customerCustomer.

• An ASPSP must reject the payment-order consentsconsent if the CutOffDateTime for a specific payment-order type has elapsed.

• An ASPSP must reject an authorisation request when the underlying intent object is associated with a CutoffDateTime that has elapsed. The ASPSP must not issue an access token in such a situation. The ASPSP must set the status of the payment-order consents consent resource to “Rejected”.

• An ASPSP must reject the payment-order resource if the CutOffDateTime for a specific payment-order type, has been established and has elapsed.

• A PISP must ensure that the userUser/customer consents Customer consent authorisation is completed and the payment-order resource is created before the CutOffDateTime elapses.

For a payment-order consentsconsent or a payment-order resource that has been rejected due to the elapsed CutoffDateTime, the PISP may decide to create a corresponding future dated payment endpoint to create a new payment-order consentsconsent. The PISP may use the /domestic-future-dated-payment-consents endpoint to create a consents consent for the same payment for the next working day.

...

In this scenario, the behaviour of the payment-order execution is not explicit to the PISP and userUser/customerCustomer, and the payment-order will be executed on the next available working day.

• An ASPSP must accept the payment-order consentsconsent if the CutOffDateTime for a specific payment-order type has elapsed.

• An ASPSP must accept an authorisation request when the underlying intent object is associated with a CutoffDateTime that has elapsed.

• An ASPSP must accept the payment-order resource if the CutOffDateTime for a specific payment-order type, has been established and has elapsed.

• An ASPSP may update the payment-order consents consent or payment-order resource with the CutOffDateTime, ExpectedExecutionDateTime and ExpectedSettlementDateTime, to communicate expected execution behaviour if the CutOffDateTime has elapsed 

...

This section overviews the release management and versioning strategy for the Payment Initiation API. It applies to all Payment Order Consents Consent and Payment Order resources, specified in the Endpoints section.

...

• A PISP must not create a payment-order consents consent ConsentId on a newer version and use it to create a payment-order resource in a previous version.

  • E.g., A ConsentId created in v3, must not be used to create a v1 PaymentSubmissionId.

• A PISP must not create a payment-order consents consent ConsentId on a previous version and use it to create a payment-order resource in a newer version.

  • E.g., A PaymentId created in v1, must not be used to create a v3 DomesticPaymentId.

2.3.1.2  GET

• A PISP must not access a payment-order ConsentId created in a newer version, via a previous version endpoint.

  • E.g., A ConsentId created in v3 accessed via a v1 PaymentId.

• An  An ASPSP may choose to make ConsentIds accessible across versions.

  • E.g., for a PaymentId created in v1, an ASPSP may or may not make it available via v3, as this is a short-lived consents.consent

2.3.2 Payment-Order Consents (Confirm Funds)

...

• A PISP must not confirm funds using a payment-order-consents consent ConsentId created in a different version.

  • E.g. A a ConsentId created in v3, must not be used to confirm funds on a v1 endpoint.

2.3.3 Payment-Order Resource

...

• A PISP must use a payment-order consents consent ConsentId within the same version to create the payment-order resource (in that version).

  • E.g., A a v3 payment-order consentsconsent can only be used to create a payment-order resource in v3.

• An ASPSP must not allow a PISP to use a ConsentId from a previous version to create a Payment Order in a newer version, and vice versa.

2.3.3.2  GET

• A PISP must refer to the ASPSP's online Developer Portal for guidelines on accessibility of a payment-order resource in a newer version.

• A PISP must not access the payment-order resource types introduced in a newer version, on an older version endpoint:

  • E.g., an internationaldomestic-payment created in v3, which is accessed via the v1 payment-submissions endpoint.

• A PISP must not access the payment-order resource created in a newer version on an older version endpoint:

  • E.g., for a domestic-payment resource created in v3, access via the v1 payment-submissions endpoint is not permitted.

• An ASPSP must document the behaviour on the accessibility of a payment-order resource in a newer version on the ASPSP's online Developer Portal.

• An ASPSP must allow access to the payment-order resource created in a previous version on a newer version endpoint (depending on an ASPSP's legal requirement for data retention):

  • E.g., a payment-submission created in v1, must be accessible as a v3 domestic-payment, with sensible defaults for additional fields introduced in v3 (e.g., if an ASPSP must make payment resources available for 7 years).

• In the case where a payment-order type is the same, but the structure has changed in a newer version, sensible defaults may be used, with the ASPSP's Developer Portal clearly specifying the behaviour.

  • E.g., a new field StatusUpdateDateTime was introduced in v3, an ASPSP ASPSPs must populate this with the last status update time (as the StatusUpdateDateTime is a mandatory field).

3.  Security & Access Control

...

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

paymentsPayments: Generic payment scope

3.2 Grants Types

PISPs must use a client credentials grant to obtain a token to make POST requests to the payment-order consentsconsent endpoints. In the specification, this grant type is referred to as "Client Credentials".

PISPs must use an authorisation code grant using a redirect or decoupled flow to obtain a token to make POST requests to the payment-order resource endpoints. This token may also be used to confirm funds on a payment-order consentsconsent resource. In the specification, this grant type is referred to as "Authorisation Code".

...

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 consents consent authorisation is used to define the fine-grained scope that is granted by the userUser/customer Customer to the PISP.

The PISP must begin a payment-order request by creating a payment-order consentsconsent resource through a POST operation. These resources indicate the consentsconsent that the PISP claims it has been given by the userUser/customerCustomer. At this stage, the consents consent is not yet authorised as the ASPSP has not yet verified this claim with the userUser/customerCustomer.

The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorisation code grant.

As part of the authorisation code grant:

• The ASPSP authenticates the user/customer.the User/Customer

• If the consent did not indicate a debtor account the ASPSP presents the User/Customer with a list of accounts from which the User/Customer may select one

• The ASPSP plays back the consents consent (registered by the PISP) back to the userUser/customer Customer to get consents consent authorisation. The userUser/customer Customer may accept or reject the consents consent in its entirety (but not selectively).If the consents did not indicate a debtor account the ASPSP presents the user/customer with a list of accounts from which the user/customer may select one. 

Once these steps are complete, the consents consent is considered to have been authorised by the userUser/customerCustomer.

3.3.1 Error Condition

If the userUser/customer Customer does not complete a successful consents consent authorisation (e.g., if the userUser/customer Customer has not authenticated successfully), the authorisation code grant ends with a redirection to the PISP with an error response. The userUser/customer Customer is redirected to the PISP with an error parameter indicating the error that occurred.

3.3.2 Consents Revocation

A userUser/customer Customer cannot revoke a payment-order consents consent once it has been authorised.

3.3.3 Changes to Selected Account

For a payment-order consentsconsent, the selected debtor account cannot be changed once the consents consent has been authorised.

3.3.4 Consents Re-Authentication

Payment consents are short-lived and cannot be re-authenticated by the userUser/customerCustomer.

3.4 Risk Scoring Information 

...

Information for risk scoring and assessment will come via:

• FAPI HTTP headers.

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

• PartyToParty.

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

...

This section describes the OBRisk class which is reused in the payment-order consents consent and payment-order resources.

...

4.1.2 OBCharge

This section describes the OBCharge class - which is reused in the response payloads in the payment-order consents consent and payment-order resources.

...

4.1.3 OBAuthorisation

This section describes the OBAuthorisation class which is used in the payment-order consents consent request and payment-order consents consent response payloads.

4.1.3.1  UML Diagram

...

4.1.4 OBDomesticRefundAccount

This section describes the OBDomesticRefundAccount class which is used in the response payloads of Domestic Payment and , Domestic Future Dated Payment and Domestic Standing Order.

4.1.4.1  UML Diagram

...

4.1.4.2  Data Dictionary

4.1.5        OBInternationalRefundAccount

This section describes the OBInternationalRefundAccount OBWritePaymentDetails class which is used in the response payloads of International Paymentpayment-detail sub resources.

4.1.5.1   UML Diagram

...

4.1.5.2   Data Dictionary

...