openapi: 3.0.1 info: title: Open Banking Pre-Authentication version: "3.1.1" description: | Some ASPSP’s support the pre-authentication of the PSU. This will allow a PSU to authenticate once for a specific TPP after which the pre-authentication can be used in subsequent payments/consents requests by the TPP (The same PsuId should be used in those requests so that the pre-authentication can be connected). Each individual request still needs to be authorized by the PSU, but authentication is not longer needed. This can speed up the flow for these subsequent payments/consents. x-tpp-buildversion: '1.10' servers: - url: /xs2a/routingservice/services/ob/auth/v3 tags: - name: Pre-Authentication paths: /psus/{psuId}/pre-authentication: post: security: - Authorization: [] tags: - Pre-Authentication summary: Pre-authentication request description: | Use this operation to pre-authenticate the Payment Service User in order to skip the identification request for further requests to the ASPSP. Pre-authentication is available for ASPSP's where in the Reach directory response Details section 'post pre-authentication' is SUPPORTED or MANDATORY. operationId: preAuthenticate parameters: - $ref: '#/components/parameters/psuId' - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/MessageCreateDateTime' - $ref: '#/components/parameters/recurring' - $ref: '#/components/parameters/consentId' - $ref: '#/components/parameters/paymentId' - $ref: '#/components/parameters/InitiatingPartyReturnUrl' - $ref: '#/components/parameters/Scope' requestBody: content: application/json: schema: $ref: '#/components/schemas/PreAuthenticationRequest' required: false responses: 201: description: | Created headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/PreAuthenticationResponse' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 403: $ref: '#/components/responses/403' 404: $ref: '#/components/responses/404' 500: $ref: '#/components/responses/500' 502: $ref: '#/components/responses/502' /psus/{psuId}/pre-authentication/{preAuthenticationId}: put: tags: - Pre-Authentication summary: Update pre-authentication description: | Use this operation to update the pre-authentication. operationId: updatePreAuthentication parameters: - $ref: '#/components/parameters/psuId' - $ref: '#/components/parameters/PreAuthenticationId' - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/MessageCreateDateTime' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdatePreAuthenticationRequest' required: false responses: 200: description: Updated content: application/json: schema: $ref: '#/components/schemas/UpdatePreAuthenticationResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 403: $ref: '#/components/responses/403' 404: $ref: '#/components/responses/404' 500: $ref: '#/components/responses/500' 502: $ref: '#/components/responses/502' delete: tags: - Pre-Authentication summary: Used by the Initiating Party to close a session description: | Use this operation to cancel a pre-authentication for a Payment Service User operationId: deletePreAuthentication parameters: - $ref: '#/components/parameters/psuId' - $ref: '#/components/parameters/PreAuthenticationId' - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/MessageCreateDateTime' responses: 204: $ref: '#/components/responses/204' 400: $ref: '#/components/responses/400' 404: $ref: '#/components/responses/404' 500: $ref: '#/components/responses/500' 502: $ref: '#/components/responses/502' /psus/{psuId}/pre-authentication/{preAuthenticationId}/status: get: tags: - Pre-Authentication summary: Get pre-authentication status description: | Use this operation to get pre-authentication details. operationId: preAuthenticationStatus parameters: - $ref: '#/components/parameters/psuId' - $ref: '#/components/parameters/PreAuthenticationId' - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/MessageCreateDateTime' responses: 200: description: | PreAuthenticationStatusResponse content: application/json: schema: $ref: '#/components/schemas/PreAuthenticationStatusResponse' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 403: $ref: '#/components/responses/403' 404: $ref: '#/components/responses/404' 500: $ref: '#/components/responses/500' 502: $ref: '#/components/responses/502' components: securitySchemes: Authorization: type: http scheme: bearer schemas: PreAuthenticationRequest: type: object properties: PsuData: $ref: '#/components/schemas/PsuData' PsuCredentials: type: array description: | List of credential ids. items: $ref: '#/components/schemas/PsuAuthCredentials' PermittedAccountReferences: type: array items: type: string description: | This field enables the Initiating party to request pre-authentication for a restricted list of account rerferences only. PreAuthenticationResponse: type: object properties: PreAuthenticationId: type: string description: | Id generated by the Open Banking Solution. This should be used to refer to this pre-authentication. PreAuthenticationStatus: $ref: '#/components/schemas/PreAuthenticationStatusEnum' AuthorisationRequiredData: $ref: '#/components/schemas/AuthorisationRequiredData' Links: $ref: '#/components/schemas/PostPreAuthLinks' PsuMessage: maxLength: 1024 minLength: 1 type: string description: | Text to be displayed to the PSU. description: | PreAuthenticationResponse required: - PreAuthenticationId - PreAuthenticationStatus UpdatePreAuthenticationRequest: type: object properties: PsuData: $ref: '#/components/schemas/PsuData' PsuCredentials: type: array description: | List of credentials the PSU has on the ASPSP's system. The PSU has to provide the CredentialValue for each of these (Username & Password). items: $ref: '#/components/schemas/PsuAuthCredentials' AuthenticationMethodId: type: string description: | Id of the selected SCA method. ScaAuthenticationData: type: string description: | Depending on method. In case of binary data it has to be given base64 encoded. UpdatePreAuthenticationResponse: required: - PreAuthenticationId - PreAuthenticationStatus type: object properties: PreAuthenticationId: type: string description: | Id generated by the Open Banking Solution. This should be used to refer to this pre-authentication. PreAuthenticationStatus: $ref: '#/components/schemas/PreAuthenticationStatusEnum' AuthorisationRequiredData: $ref: '#/components/schemas/AuthorisationRequiredData' Links: $ref: '#/components/schemas/UpdatePreAuthLinks' PsuMessage: maxLength: 1024 minLength: 1 type: string description: | Text to be displayed to the PSU. PreAuthenticationStatusResponse: required: - PreAuthenticationId - PreAuthenticationStatus type: object properties: PreAuthenticationId: type: string description: | Id generated by the Open Banking Solution. This should be used to refer to this pre-authentication. PreAuthenticationStatus: $ref: '#/components/schemas/PreAuthenticationStatusEnum' PsuMessage: maxLength: 1024 minLength: 1 type: string description: | Text to be displayed to the PSU. PsuData: type: object properties: AspspId: minLength: 1 type: string description: | The Id of the ASPSP. The Open Banking Solution used this information to route the pre-authentication request. AspspProductCode: type: string description: | This is describing the ProductCode as defined by the ASPSP. AspspPsuId: type: string example: PSU-12345 description: | PSU’s Id at ASPSP. Allows the unique identification of the PSU at the ASPSP. AspspCustomerId: type: string example: PSU-12345 description: | PSU’s second Id at ASPSP. Required for some ASPSPs AspspPsuIdType: type: string description: | Type of the Aspsp PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility. AspspPsuCorporateId: type: string description: | Identification of a Corporate in the Online Channels. AspspPsuCorporateIdType: type: string description: | This is describing the type of the identification needed by the ASPSP to identify the PSUCorporate-ID content. AuthorisationRequiredData: type: object description: | The data required for PSU authentication and transaction authorisation properties: PsuCredentials: type: array description: | List of credentials the PSU has on the ASPSP's system. The PSU has to provide the CredentialValue for each of these (Username & Password). items: $ref: '#/components/schemas/PsuCredentials' ScaMethods: type: array description: | Array of available ScaMethods. items: $ref: '#/components/schemas/ScaMethods' ChosenScaMethods: $ref: '#/components/schemas/ScaMethods' ChallengeData: $ref: '#/components/schemas/ScaChallengeData' PsuAuthCredentials: required: - CredentialId - CredentialValue type: object properties: CredentialId: type: string description: | CredentialId as retrieved in the response of the previous request. CredentialValue: type: string description: | Value of the credential. PsuCredentials: required: - CredentialsDetails type: object properties: AspspProductCode: type: string description: | Product Identification. Used to contextualize the credentials provided by the PSU for those ASPSP that need of it. CredentialsDetails: type: array description: | Credentials Details items: $ref: '#/components/schemas/CredentialDetails' description: | PSU Credentials on the Bank system. CredentialDetails: required: - IsSecret - LabelList type: object properties: IsSecret: type: string description: | Binary identification of the transparancy of the provided credentials by the PSU. Can have 2 values, * true * false Can be provided by ASPSP. If not provided by the ASPSP then by default, * true, if the CredentialId=ewl-password * false, if CredentialId=ewl-user-id CredentialId: type: string description: | Credential detail identification of the PSU credential at the bank (provided bi CBI if approach is Embedded). If not provided by the aspsp, then default values should be, * ewl-user-id, when IsSecret=false * ewl-password, when IsSecret=true LabelList: type: array description: | The list of the labels to show to the PSU. They are internationalized. items: $ref: '#/components/schemas/CredentialLabel' description: | Credentials Details CredentialLabel: required: - Label - Language type: object properties: Label: type: string description: | The label associated to the credentials to show to the PSU. Language: type: string description: | Label internationalization. It specifies the language of the label. The default value is EN. ScaMethods: required: - AuthenticationMethodId - AuthenticationType type: object properties: AuthenticationType: type: string description: | Type of the SCA authentication method. The following methods are commonly seen coming from the ASPSP: - SMS_OTP: The PSU will receive a One Time Password via SMS - CHIP_OTP: The PSU will be presented with a picture or text to create a One Time Password using their bank card - PHOTO_OTP: The PSU will be presented with a picture to create a One Time Password - PUSH_OTP: The PSU will receive a One Time Password via push notification on their mobile device - SMTP_OTP: The PSU will receive a One Time Password via email AuthenticationMethodId: type: string description: | An identification provided by the ASPSP for the later identification of the authentication method selection. Version: type: string description: | Depending on the AuthenticationType. This version can be used by differentiating authentication tools used within performing OTP generation in the same authentication type. This version can be referred to in the ASPSP s documentation. Name: type: string description: | This could be a description provided by the ASPSP likeSMS OTP on phone +49160 xxxxx 28. This name shall be used by the TPP when presenting a list of authentication methods to the PSU, if available. Explanation: type: string description: | Detailed information about the SCA method, meant for the PSU. ScaChallengeData: type: object properties: AdditionalInformation: type: string description: | Additional Information for the PSU describing the method. Data: type: array description: | A collection of strings as challenge data. items: type: string Image: type: string description: | Image in base64 encoding. ImageLink: type: string description: | URL of image. OtpFormat: type: string description: | The OTP format. OtpMaxLength: type: integer description: | The maximum length for the OTP. format: int32 description: | Structure to represent challenge data. PreAuthenticationStatusEnum: type: string description: | PreAuthentication status. enum: - Open - Pending - Rejected - Authorised - Expired - Revoked - Error PostPreAuthLinks: type: object description: | A list of hyperlinks to be recognized by the Initiating Party. The actual hyperlinks used in the response depend on the dynamical decisions on authorization approach for example. Remark - All links are full links. * 'RedirectUrl': In case of an Redirect approach, the Initiating Party has to use this link to redirect the PSU’s browser session. * 'UpdatePsuCredentialsForPreAuthentication': In case to update PSU credentials for pre-authentication. * 'SelectScaMethodsForPreAuthentication': In case of an embedded approach the Initiating Party has to use this link to select the requested SCA method. * 'AuthorizePreAuthentication': In case of an embedded approach the Initiating Party has to authorize the transaction (consent) by providing the SCA OneTimePassword. * 'GetPreAuthenticationStatus': Endpoint to be called for retrieving the pre-authentication status. properties: RedirectUrl: $ref: '#/components/schemas/Link' UpdatePsuCredentialsForPreAuthentication: $ref: '#/components/schemas/Link' SelectScaMethodsForPreAuthentication: $ref: '#/components/schemas/Link' AuthorizePreAuthentication: $ref: '#/components/schemas/Link' GetPreAuthenticationStatus: $ref: '#/components/schemas/Link' UpdatePreAuthLinks: type: object description: | A list of hyperlinks to be recognized by the Initiating Party. The actual hyperlinks used in the response depend on the dynamical decisions on authorization approach for example. Remark - All links are full links. * 'SelectScaMethodsForPreAuthentication': In case of an embedded approach the Initiating Party has to use this link to select the requested SCA method. * 'AuthorizePreAuthentication': In case of an embedded approach the Initiating Party has to authorize the transaction (consent) by providing the SCA OneTimePassword. * 'PostAuthorisationForEmbedded': In case of an embedded approach, the Initiating Party has to use this link to post the PSU credentials. * 'SelectAuthenticationMethod': In case of an embedded approach and an SCA required for the authorization of the pre-authentication the Initiating Party may have to use this link to select the requested SCA method. * 'GetPreAuthenticationStatus': Endpoint to be called for retrieving the pre-authentication status. * 'AuthorizeTransaction': Endpoint to be called for authorizing the transaction by SCA OTP in case of embedded implicit pre-authentication for payments or consents. * 'ConfirmationRequired': Endpoint to be called for confirmation of the payment in embedded implicit pre-authentication for payments. * 'GetPaymentStatus': Endpoint to be called for retrieving the payment status in case of embedded implicit pre-authentication for payments. * 'GetConsentStatus': Endpoint to be called for retrieving the consent status in case of embedded implicit pre-authentication for consent. properties: SelectScaMethodsForPreAuthentication: $ref: '#/components/schemas/Link' AuthorizePreAuthentication: $ref: '#/components/schemas/Link' PostAuthorisationForEmbedded: $ref: '#/components/schemas/Link' SelectAuthenticationMethod: $ref: '#/components/schemas/Link' GetPreAuthenticationStatus: $ref: '#/components/schemas/Link' AuthorizeTransaction: $ref: '#/components/schemas/Link' ConfirmationRequired: $ref: '#/components/schemas/Link' GetPaymentStatus: $ref: '#/components/schemas/Link' GetConsentStatus: $ref: '#/components/schemas/Link' Link: required: - Href type: object properties: Href: maxLength: 1024 minLength: 1 type: string Error: required: - Code - Message type: object properties: Code: pattern: '[0-9]{1,3}' type: string Message: maxLength: 140 minLength: 1 type: string Details: type: string Link: $ref: '#/components/schemas/Link' description: | |HTTP Status|Code |Description |-----------|-----|--------------------------------------- |400 |001 |Bad client request | |008 |The message does not comply the schema definition | |101 |The client or merchant is unknown | |102 |The client or merchant is inactive | |105 |The aspsp is not active |403 |007 |Initiating Party is not authorised | |017 |Initiating Party access token is expired |404 |104 |The Aspsp is unknown | |110 |Resource could not be found | |150 |No pre-authentication found |405 |137 |Request is not supported by Aspsp |500 |004 |An internal error occurred | |116 |The aspsp responded with an error |502 |012 |Aspsp did not authorise |503 |016 |Request limit of the ASPSP server exceeded xml: name: Error namespace: urn:eu:xs2a:xsd:v1 parameters: psuId: name: psuId in: path required: true schema: type: string description: | This field can be filled with an ID from the Initiating Party which refers to the PSU. recurring: name: recurring in: query required: false schema: type: boolean default: true (Only for ASPSPs which have implemented the CBI protocol the default is false) description: | "true", if the consent is for recurring access to the account data. "false", if the consent is for one access to the account data. consentId: name: consentId in: query required: false schema: type: string description: | Identification of the consent resource if it was generated. paymentId: name: paymentId in: query required: false schema: type: string description: | Resource identification of the generated payment initiation resource. InitiatingPartyReturnUrl: name: InitiatingPartyReturnUrl in: header required: false schema: minLength: 1 maxLength: 4000 type: string example: https://www.example.org description: | The callback URL for the redirection back to the initiating party after authorization. If this field is not filled the value defined in the AIS/PIS subscription will be used. Scope: name: Scope in: header required: false schema: type: string default: AIS+PIS enum: - AIS - PIS - AIS+PIS description: | Scope of the pre-authentication PreAuthenticationId: name: preAuthenticationId in: path required: true schema: type: string description: | The id of the pre-authentication. X-Request-ID: name: X-Request-ID in: header required: true description: | UUID for unique request identification. schema: type: string maxLength: 36 minLength: 1 MessageCreateDateTime: name: MessageCreateDateTime in: header required: true description: | The message create date time. ISO 8601 DateTime. schema: type: string example: "2023-09-25T08:15:00.856Z" format: 'date-time' headers: X-Request-ID: required: true description: | UUID for unique request identification. schema: type: string maxLength: 36 minLength: 1 example: 0f16be60-e379-4b3a-a469-f905f6fa24d0 MessageCreateDateTime: required: true schema: type: string example: "2023-09-25T08:15:00.856Z" format: 'date-time' description: | The message create date time. ISO 8601 DateTime. responses: 204: description: | Deleted content: {} headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' 400: description: | Bad Request headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/Error' 401: description: | Missing or wrong IP Token headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/Error' 403: description: | Expired IP Token headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/Error' 404: description: | Not Found, resource at TPP not found headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/Error' 500: description: | Internal Server Error headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/Error' 502: description: | Bad Gateway, connection to aspsp failed or token to aspsp missing. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' MessageCreateDateTime: $ref: '#/components/headers/MessageCreateDateTime' content: application/json: schema: $ref: '#/components/schemas/Error'