1. API Flows

1.1 Step 1: Agree Service Initiation Consent

The flow MUST begin with a User who provides consent to a TPP to stage a Bank Service Initiation operation, for a LFI that they already have a relationship with.

1.2 Step 2: Authorize Service Initiation Consent

The TPP MUST now request the User to authorize the consent. Please refer to the Authentication and Authorization page , to review the supported Authorization Flows.

The TPP MUST construct a Rich Authorization Request (RFC 9396: OAuth 2.0 Rich Authorization Requests) with the authorization_details populated with the User’s Service Initiation consent

The TPP MUST include in a Service Initiation consent all mandatory data that the User intends to provide to the TPP for initiating a Service Initiation operation.

The TPP MUST include a UUID v4 as the ConsentId as a unique identifier for the Service Initiation consent.

The TPP MAY, within in the Service Initiation Consent (where applicable):

• Set the IsSingleAuthorization field to determine if only Single Authorizer flow supported.

• Set the AuthorizationExpirationDateTime field to limit the overall time in which a Consent MUST be authorized.

1.2.1 Service Initiation Consent Types

The OFP MUST link both PaymentId and ConsentId:

• In the Service Initiation resource (PaymentId) set Links.Related to the authorized ConsentId used to create the Service Initiation.

• In the Service Initiation consent resource (ConsentId) set Links.Related to the PaymentId resource created for the Consent.

1.2.1 Security and Access Control

Authorization Code Grant

The TPP MUST use an authorization code grant to obtain a token to access all other API resources.

1.3 Step 3: Create Service Initiation

The TPP MUST have a valid access token (with scope) from the OFP authorization server.

The TPP MUST use the valid access token to create a Service Initiation resource with the OFP resource server.

The LFI MUST return a 201 Status Code together to acknowledge the creation of the new Service Initiation resource when provided with a valid request from the OFP.

The OFP MUST return a 201 Status Code together to acknowledge the creation of the new Service Initiation resource when provided with a valid access token request from the TPP.

1.4 Step 4: Access the Service Initiation Status

1.5.1 Request Data

The TPP MUST have a valid access token (with scope) from the OFP authorization server.

The TPP MUST set the Content-Type as application/jwt when creating a Service Initiation resource with the OFP, together with the resource identifier from Step 3.

The OFP MUST respond with the TPP request with a signed JWT with a Service Initiation resource. This ensures non-repudiation for Service Initiation.

2. Service Initiation Sequence Diagrams

All sequence diagrams relating to Bank Service Initiation are now available in the API Hub Documentation.

3. Service Initiation Examples

The following are non-normative examples of API access and usage of the Service Initiation API.

3.1 The TPP Redirects the User to Authorize the Service Initiation Consent

3.1.1 Request: TPP Uses RAR (Rich Authorization Request) via a PAR (Pushed Authorization Request) Endpoint with the OFP to Obtain a Request URI

Create a RAR Request JWT with these values:

• kid is a valid signing key ID for the TPP on the Open Finance Directory

• iss is client id (UUID v4)

• state is a UUID v4 value

• response_type MUST be code

• redirect_uri is the TPP’s redirect URI

The authorization_details contain the User’s service initiation consent details, and a UUID v4 which is a unique identifier for the Service Initiation consent.

The PersonalIdentifiableInformation field is a JWE that is encrypted by the LFI’s public key, so that only the LFI can decrypt it. It allows the TPP to transmit personal identifiable information (such as the CreditorAccount and personal information in the Risk object) to the LFI, without the OFP having to store this information in the consent object. The structure of the decrypted JWE is document in the AEPaymentPII schema in the OpenAPI document.

Create the RAR Request using the signed JWT, and authenticated using private_key_jwt.

The request parameter JWT includes the ConsentId, a UUID v4 that was originally generated by the TPP.

3.1.2 Response: The OFP Provides the Request URI for the TPP

3.4 The TPP Redirects the User to Their LFI with the Request URI to Authorize the Consent

3.5 The User Logs into Their LFI, Reviews and Authorizes the Consent

The LFI confirms the Service Initiation consent in the OFP.

3.6 The LFI Returns an Authorization Code to the TPP

3.7 The TPP Exchanges the Authorization Code for an Service Initiation API Access Token with the OFP

3.8 The OFP Returns an Access Token, Refresh Token to the TPP

The TPP can now initiate a Service Initiation resource using the access token.

3.9 The TPP Initiates a Service Initiation Request with the OFP

3.9.1 Request: payments Resource

3.9.2 Response: payments Resource

3.10 The TPP Retrieves the Service Initiation Status from the OFP Using the Resource Identifier

Get the Service Initiation Status from the OFP as a JWT response

3.10.1 Request: /payments/{PaymentId} Resource

3.10.2 Response: /payments/{PaymentId} Resource

4. Further Service Initiation Examples

4.1 The TPP Queries the Service Initiation Resource Using an Expired Access Token

4.1.1 Request: payments/{PaymentId} Resource

4.1.2 Response: payments/{PaymentId} Resource

4.2 Webhooks

4.2.1 The TPP Creates a Service Initiation Consent Request on Behalf of the User with a Webhook Subscription

4.2.1.1 Request: Service Initiation Consent and Webhook Subscription

4.2.2 The TPP updates a Webhook Subscription preference with the OFP

4.2.2.1 Request: Activate Webhook events

4.2.2.2 Response: Webhook events activated

4.2.3 The TPP unsubscribes their Webhook Subscription with the OFP

4.2.3.1 Request: De-Activate Webhook events

4.2.3.2 Response: Webhook events de-activated

4.2.4 The TPP receives Service Initiation Consent data from the OFP via its Webhook

4.2.4.1 The OFP generates a Self Signed JWT Authorization Token for Client Authentication with the TPP

This JWT Authorization Token MUST be set in the Authorization Header.

4.2.4.2 Request: OFP publishes signed/encrypted Service Initiation Data to the registered Webhook Url provided by the TPP

The example below shows a signed and encrypted payload with the JWT Authorization Token set in the Authorization Header

Here, <<jwe>> is a signed and encrypted payload. The inner JWS has the structure below.

4.2.4.3 Response: TPP validates the Self Signed JWT Authorization Token from OFP, stores Payment consent data and acknowledges a success response to the OFP

4.3 Multiple Authorizations

4.3.1 Request: Service Initiation consent resource requesting Multi-Authorization

The TPP creates a Service Initiation consent with IsSingleAuthorization as false denoting its support for a Multi-Authorization consent.

4.4 The TPP Queries the existence of a Service Initiation Resource Using the X-Idempotency-Key

This is a negative scenario whereby the OFP fails to return any payments response and the TPP has no way of identifying the resource PaymentId

The PaymentId is returned within the HTTP Location Header URL under the /payments resource.

4.4.1 Request to /payments Resource

4.4.2 Response to /payments Resource

4.5 The TPP Initiates a Bulk File Payment

4.5.1 Request: TPP Uses RAR (Rich Authorization Request) to Request Initial Base Consent

The authorization_details contain the User’s service initiation consent details, and a UUID v4 which is a unique identifier for the Service Initiation consent.

Create the RAR Request using the signed JWT, and authenticated using private_key_jwt.

The request parameter JWT includes the ConsentId, a UUID v4 that was originally generated by the TPP.

4.5.2 Response: The OFP Provides the Request URI for the TPP

4.5.3 The TPP Uploads File Payment

4.5.4 The TPP Redirects the User to Their LFI with the Request URI to Authorize the Consent

4.5.5 The User Logs into Their LFI, Reviews and Authorizes the Consent

The LFI confirms the Service Initiation consent in the OFP.

4.5.6 The LFI Returns an Authorization Code to the TPP

4.5.7 The TPP Exchanges the Authorization Code for an Service Initiation API Access Token with the OFP

4.5.8 The OFP Returns an Access Token, Refresh Token to the TPP

The TPP can now initiate a Service Initiation resource using the access token.

4.5.9 The TPP Initiates a Service Initiation Request with the OFP

4.5.9.1 Request: file-payments Resource

4.5.8.2 Response: file-payments Resource

4.6 The TPP Requests Refund Account Details

4.6.1 Request: payment-consents/{ConsentId}/refund Resource

4.6.2 Response: payment-consents/{ConsentId}/refund Resource

4.7 The TPP Uses the BaseConsentId to Link Consents

A TPP may update the parameters of an existing consent, by (1) revoking the existing consent, and (2) creating a new consent for the User with the new agreed consent parameters. The BaseConsentId allows TPPs to chain and link consents together, so that there is a history of linked consents.

This flow gives an example of how a TPP will link consents together.

4.7.1 TPP Creates a new Consent as the Base Consent

The authorization_details contain the User’s service initiation consent details, and a UUID v4 which is a unique identifier for the Service Initiation consent.

Create the RAR Request using the signed JWT, and authenticated using private_key_jwt.

The request parameter JWT includes the ConsentId, a UUID v4 that was originally generated by the TPP.

4.7.2 Standard Authorization Flow

The standard authorization flow proceeds with the User authorizing the consent. The TPP now has a valid consent in an Authorized state.

4.7.3 Alternative Flow - the TPP may Revoke the Existing Consent

In the scenario that the TPP wants to update the consent parameters in the original consent - the TPP would take steps to:

• Revoke the original consent

• Create a new consent that the User would authorise this new consent (as per 4.7.1)

• If the TPP would like to link the original consent with the new consent - the TPP would populate the BaseConsentId with the BaseConsentId of the original consent

4.7.3.1 TPP Revokes Original Consent

4.5.3.2 TPP Creates a new Consent with the same BaseConsentId

5. Open API Specification

See the Bank Service Initiation OpenAPI page.

6. Service Initiation Notes

6.1 Staging a Service Initiation Consent

To manage the creation and execution of a Single Instant payment;

The TPP:

• MUST provide a ConsentId in the Consent object within the authorization_details of a Rich Authorization Request.

• MUST include the response from the Confirmation operation at the Confirmation of Payee API in the property ConfirmationOfPayeeResponse when Confirmation of Payee has been performed by the TPP for the CreditorAccount details. This property must be included in the value of the JWE created to populate the property PersonalIdentifiableInformation.

• MAY use PATCH to manage any Webhook configurations for the entire duration of a payment consent.

• MAY use a GET to the /payments/{PaymentId} resource to poll for Payment Statuses.

The OFP:

• MUST reject the Service Initiation consent if a globally unique UUID v4 ConsentId does not exist in the RAR object.

• MUST validate the Consent parameters and create a Consent resource (ConsentId) that is AwaitingAuthorization when a valid RAR object is staged at the PAR endpoint.

• MUST immediately stage the payment with the LFI once a valid Service Initiation resource is created by the TPP.

• MUST send payment status events to the TPP if an active Webhook Subscription is registered within the Consent object.

The LFI:

• MUST immediately stage the payment with the Payment Rails once a valid payment is staged by the OFP.

• MUST emit payment status events to the OFP.

6.2 Service Initiation Consent Parameters

6.2.1 Single Payment Consent Parameters

6.2.1.1 Single Instant Payment

A Single Instant Payment MUST meet the following criteria:

• Type MUST be set to SingleInstantPayment

• The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST be set to the current date.

6.2.1.2 Single Future Dated Payment

A Single Future Dated Payment MUST meet the following criteria:

• Type MUST be set to SingleFutureDatedPayment

• The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.

• RequestedExecutionDate MUST NOT be set to the current day. It MUST be set to a future date/time beyond the current day when the payment is to be scheduled for execution.

6.2.2 Multi-Payment Consent Parameters

These consent parameters are defined to control the limits for a long lived Multi-Payment consent:

• MaximumCumulativeValueOfPayments MUST be set to confirm the total payment amount for the whole consent duration.

• MaximumCumulativeNumberOfPayments MUST be set to confirm the total number of payments for the whole consent duration.

• PeriodicSchedule MAY further define any period specific maximum payment numbers and/or amounts, and is one of these Types:

  • FixedDefinedSchedule - a Payment Schedule denoting a list of pre-defined future dated payments each with a fixed amount and date.

  • VariableDefinedSchedule - a Payment Schedule denoting a list of pre-defined future dated payments each with a fixed date and maximum amount.

  • FixedPeriodicSchedule - The payments for this consent have a fixed amount and must be executed only on the PeriodStartDate, and dates recurring based on the PeriodType.

  • VariablePeriodicSchedule - The payments for this consent have a variable amount and must be executed only on the PeriodStartDate, and dates recurring based on the PeriodType.

  • FixedOnDemand - The payments for this consent have a fixed amount and may be executed on any date, as long as they are within the Controls for a PeriodType.

  • VariableOnDemand - The payments for this consent have a variable amount and may be executed on any date, as long as they are within the Controls for a PeriodType.

6.2.3 Combined Payment Consent Parameters

A Combined Service Initiation MUST be:

• Any one Type of Single Payment

• Any one Type of Multi-Payment

6.2.4 File Payment Consent Parameters

A File Payment consent MUST contain these metadata fields of the file being uploaded:

• FileType MUST be set to the file payment type that is accepted by the LFI.

• FileHash MUST be set to the base64 encoding of a SHA256 hash of the file to be uploaded.

• NumberOfTransactions MUST be set to the number of payments contained in the file.

• ControlSum MUST be set to the total of all individual amounts included in the file, irrespective of currencies.

6.3 OFP Service Initiation Responsibilities

• MUST associate all TPP requests (including retries) with an X-Idempotency-Key

• MUST reject all requests where an X-Idempotency-Key is not provided by the TPP for the /payments resource

• On receiving the RAR request from the TPP, MUST proceed to:

  • Create a Service Initiation Consents resource (ConsentId).

  • Set Consent Status to AwaitingAuthorization

  • Set Meta.MultipleAuthorizers where multiple authorizations are required to authorize the Service Initiation

• On a User Authorizing the Service Initiation, MUST set the following Consent Status to confirm Service Initiation details:

  • Set Consent Status to Authorized

• On Payment rails completion, MUST set the following status based on the Payment rails outcome:

  • Set Status to either Pending, AcceptedSettlementCompleted, AcceptedCreditSettlementCompleted, AcceptedWithoutPosting, Rejected

  • When all Service Initiations have been successfully completed in a consent, the OFP MUST set the Service Initiation Consent Status to Completed.

• MUST set the Links object across both the Payment resource and Consent resource enabling the TPP to locate those resources

• MUST validate that a Payment is within any of the Consent Control parameter limits authorized by the User.

• MUST send payment status Events to the TPP where a Webhook subscription has been received in the Payment request

• MAY return an HTTP Location header for the 201 Status code indicating the URI of the primary resource that has been created (rfc9110)

• MUST use PaymentConsumption to provide the TPP with up-to-date cumulative number and value totals of Payments (initiated under the consent schedule, excluding instructions in a Rejected state) associated with the Authorized Consent.

7. Security

A payments scope (with the ConsentId) is used for POST /payments.