--- swagger: "2.0" info: version: 1.3.2.1 title: Consent API description: "" x-ibm-name: psd2-bgs-consent-api-132 basePath: /psd2-bgs-consent-api-1.3.2/v1 schemes: - https paths: /consents: post: description: | TPP Requests a new Consent. tags: - Request a new Consent parameters: - name: X-Request-ID in: header description: Request ID required: true type: string format: UUID - name: PSU-ID in: header description: 'Client ID of the PSU in the ASPSP client interface. Might be mandated in the ASPSP''s documentation. Is not contained if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in an preceding AIS service in the same session. Example: PSU-1234' type: string - name: PSU-ID-Type in: header description: Type of the PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility. type: string - name: PSU-Corporate-ID in: header description: Might be mandated in the ASPSP's documentation. Only used in a corporate context. type: string - name: PSU-Corporate-ID-Type in: header description: Might be mandated in the ASPSP's documentation. Only used in a corporate context. type: string - name: TPP-Redirect-Preferred in: header description: |- If it equals "true", the TPP prefers a redirect over an embedded SCA approach. If it equals "false", the TPP prefers not to be redirected for SCA. The ASPSP will then choose between the Embedded or the Decoupled SCA approach, depending on the choice of the SCA procedure by the TPP/PSU. If the parameter is not used, the ASPSP will choose the SCA approach to be applied depending on the SCA method chosen by the TPP/PSU. type: boolean - name: TPP-Redirect-URI in: header description: |- URI of the TPP, where the transaction flow shall be redirected to after a Redirect. Mandated for the Redirect SCA Approach, specifically when TPP-Redirect-Preferred equals "true". It is recommended to always use this header field. **Remark for Future:** This field might be changed to mandatory in the next version of the specification. type: string - name: TPP-Nok-Redirect-URI in: header description: |- If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the TPP-Redirect-URI in case of a negative result of the redirect SCA method. This might be ignored by the ASPSP. type: string - name: PSU-IP-Address in: header description: |- The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initiated by the PSU. type: string - name: PSU-IP-Port in: header description: The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available. type: string - name: PSU-Accept in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. type: string - name: PSU-Accept-Charset in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. type: string - name: PSU-Accept-Encoding in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. type: string - name: PSU-Accept-Language in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. type: string - name: PSU-User-Agent in: header description: |- The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Examples * Android: "Myappa/1.2 Dalvik/2.1.0 (Linux; U; Android 6.0.1; vivo 1610 Build/MMB29M)" * iOS: "MyApp/1 iPhone5,2 iOS/10_1 CFNetwork/808.3 Darwin/16.3.0" type: string - name: PSU-Http-Method in: header description: |- HTTP method used at the PSU ? TPP interface, if available. Valid values are: * GET * POST * PUT * PATCH * DELETE type: string - name: PSU-Device-ID in: header description: |- UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device. type: string format: uuid - name: PSU-Geo-Location in: header description: The forwarded Geo Location of the corresponding http request between PSU and TPP if available. pattern: GEO:-?[0-9]{1,2}\.[0-9]{6};-?[0-9]{1,3}\.[0-9]{6} type: string - name: body in: body description: Consent body request required: true schema: $ref: '#/definitions/XS2A_Berlin_Create_Consent_Request' responses: 200: description: Successful response headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Create_Consent_Response' 400: description: Bad Request headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 404: description: Not Found headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 408: description: Request Timeout headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 500: description: Internal Server Error headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' /consents/{consentId}: get: description: | Returns the content of an account information consent object. tags: - Request a new Consent parameters: - name: X-Request-ID in: header description: Request ID required: true type: string format: UUID - name: consentId in: path description: ID of the corresponding consent object as returned by an Account Information Consent Request. required: true type: string format: UUID responses: 200: description: Successful response headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Consent' 400: description: Bad Request headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 404: description: Not Found headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 408: description: Request Timeout headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 500: description: Internal Server Error headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' delete: description: | Deletes an account information consent object. tags: - Request a new Consent parameters: - name: X-Request-ID in: header description: Request ID required: true type: string format: UUID - name: Authorization in: header description: OAuth2 based SCA was performed in the corresponding consent transaction or if OAuth2 has been used in a pre-step. required: true type: string - name: consentId in: path description: Contains the resource-ID of the consent to be deleted. required: true type: string format: UUID responses: 204: description: Successful response headers: X-Request-ID: type: string 400: description: Bad Request headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 404: description: Not Found headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 408: description: Request Timeout headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 500: description: Internal Server Error headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' security: - oauth-1: - AISP clientIdHeader: [] /consents/{consentId}/status: get: description: | Returns the content of an account information consent object. tags: - Request a new Consent parameters: - name: X-Request-ID in: header description: Request ID required: true type: string format: UUID - name: consentId in: path description: The consent identification assigned to the created resource. required: true type: string format: UUID responses: 200: description: Successful response headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Get_Consent_Status_Response' 404: description: Not Found headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 408: description: Request Timeout headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' 500: description: Internal Server Error headers: X-Request-ID: type: string schema: $ref: '#/definitions/XS2A_Berlin_Error' definitions: XS2A_Berlin_Error: type: object properties: errorCode: type: string description: Optional error code for reporting purposes. errorDescription: type: string description: The description of the error. XS2A_Berlin_Create_Consent_Request: type: object properties: access: $ref: '#/definitions/XS2A_Berlin_Consent_Account_Access' recurringIndicator: type: boolean 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 example: true validUntil: description: Datetime the transaction was created. type: string format: date example: "2017-11-01" frequencyPerDay: description: This field indicates the requested maximum frequency for an access per day. For a one-off access, this attribute is set to "1". type: integer example: 4 combinedServiceIndicator: type: boolean description: true - indicates that a payment initiation service will be addressed in the same "session" - NOT IMPLEMENTED AT THE MOMENT example: true required: - access - recurringIndicator - validUntil - frequencyPerDay - combinedServiceIndicator XS2A_Berlin_Consent_Account_Access: description: All attributes are optional but at minimum one of these should exist. type: object properties: accounts: type: array items: $ref: '#/definitions/XS2A_Berlin_Consent_Resources' balances: type: array items: $ref: '#/definitions/XS2A_Berlin_Consent_Resources' transactions: type: array items: $ref: '#/definitions/XS2A_Berlin_Consent_Resources' additionalInformation: type: object properties: ownerName: $ref: '#/definitions/ownerName' ownerName: type: array items: $ref: '#/definitions/XS2A_Berlin_Consent_Resources' XS2A_Berlin_Create_Consent_Response: type: object properties: consentStatus: $ref: '#/definitions/XS2A_Berlin_Consent_Status' consentId: type: string description: Identification of the consent resource as it is used in the API structure. Shall be contained, if a consent resource was generated. scaMethods: type: array items: $ref: '#/definitions/XS2A_Sca_Methods' _links: $ref: '#/definitions/XS2A_Berlin_Links' required: - consentStatus - _links XS2A_Sca_Methods: type: array description: |- This data element might be contained, if SCA is required and if the PSU has a choice between different authentication methods. Depending on the risk management of the ASPSP this choice might be offered before or after the PSU has been identified with the first relevant factor, or if an access token is transported. If this data element is contained, then there is also an hyperlink of type 'startAuthorisationWithAuthenticationMethodSelection' contained in the response body. These methods shall be presented towards the PSU for selection by the TPP. items: $ref: '#/definitions/authenticationObject' authenticationObject: title: authenticationObject required: - authenticationMethodId - authenticationType type: object properties: authenticationType: $ref: '#/definitions/authenticationType' authenticationVersion: 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. authenticationMethodId: maxLength: 35 type: string description: An identification provided by the ASPSP for the later identification of the authentication method selection. example: myAuthenticationID name: type: string description: |- This is the name of the authentication method defined by the PSU in the Online Banking frontend of the ASPSP. Alternatively this could be a description provided by the ASPSP like "SMS 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. example: SMS OTP on phone +49160 xxxxx 28 explanation: type: string description: Detailed information about the SCA method for the PSU. example: Detailed information about the SCA method for the PSU. description: Authentication Object authenticationType: title: authenticationType type: string enum: - SMS_OTP - CHIP_OTP - PHOTO_OTP - PUSH_OTP - APP_TO_APP_IOS - APP_TO_APP_ANDROID - SCAREDIRECT XS2A_Berlin_Get_Consent_Status_Response: type: object properties: consentStatus: $ref: '#/definitions/XS2A_Berlin_Consent_Status' required: - consentStatus XS2A_Berlin_Links: type: object properties: scaRedirect: $ref: '#/definitions/XS2A_Berlin_Href' description: In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browse. status: $ref: '#/definitions/XS2A_Berlin_Href' description: The link to retrieve the transaction status of the account information consent. required: - scaRedirect - status XS2A_Berlin_Href: type: object properties: href: type: string example: https://api.testbank.com required: - href XS2A_Berlin_Consent_Resources: type: object properties: iban: type: string description: IBAN of an account. pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{12,30}$ example: DE2310010010123456789 currency: type: string description: Currency of an account. pattern: ^[A-Z]{3,3}$ example: USD XS2A_Berlin_Consent: type: object properties: access: $ref: '#/definitions/XS2A_Berlin_Consent_Account_Access' recurringIndicator: type: boolean 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 validUntil: description: Datetime the transaction was created. type: string format: date example: "2017-11-01" frequencyPerDay: description: This field indicates the requested maximum frequency for an access per day. For a one-off access, this attribute is set to "1". type: number format: integer example: 4 lastActionDate: description: This date is containing the date of the last action on the consent object either through the XS2A interface or the PSU/ASPSP interface having an impact on the status. type: string format: date example: "2017-11-01" consentStatus: $ref: '#/definitions/XS2A_Berlin_Consent_Status' required: - access - recurringIndicator - validUntil - frequencyPerDay XS2A_Berlin_Consent_Status: type: string description: Authentication status of the consent. enum: - received - valid - rejected - revokedByPsu - expired - terminatedByTpp x-ibm-configuration: enforced: true testable: true phase: realized consumes: - application/json produces: - application/json securityDefinitions: oauth-1: type: oauth2 description: "" flow: accessCode scopes: AISP: Account access authorizationUrl: https://api-public.rba.hr/psd2-rbhr-oauth2-api/oauth2/authorize tokenUrl: https://api-public.rba.hr/psd2-rbhr-oauth2-api/oauth2/token clientIdHeader: type: apiKey description: "" in: header name: X-IBM-Client-Id security: - clientIdHeader: [] x-ibm-endpoints: - endpointUrl: https://api.rba.hr type: - production - development ...