--- swagger: "2.0" info: version: 1.0.3 title: BT - BG PSD2 PIISP API description: "The **NextGenPSD2** *Framework Version 1.2* offers a modern, open, harmonised and interoperable set of \nApplication Programming Interfaces (APIs) as the safest and most efficient way to provide data securely. \nThe NextGenPSD2 Framework reduces XS2A complexity and costs, addresses the problem of multiple competing standards \nin Europe and, aligned with the goals of the Euro Retail Payments Board,\nenables European banking customers to benefit from innovative products and services ('Banking as a Service') \nby granting TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data.\n\nThe BT chosen approach is:\n * OAuth SCA Approach\n\n Futhermore this API definition contains only a subset of the methods, the ones which are mandatory or which are applicable in the BT ecosystem.\n \n## Some General Remarks Related to this version of the OpenAPI Specification:\n* **This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API.** \n It is not an replacement in any sense.\n The main specification is (at the moment) allways the Implementation Guidelines of the Berlin Group PSD2 API.\n* **This API definition contains the REST-API for requests from the PIISP to the ASPSP.**\n* **This API definition contains the messages for all different approaches defined in the Implementation Guidelines.**\n*\n\nChangelog:\n- Added POST Consent, GET Consent Details, GET Consent Status, DELETE Consent APIs\n- tppMessages error parameter is array instead of object\n- various minor corrections and additions" x-ibm-name: bt-bg-psd2-piisp-api host: datapower basePath: /bt-psd2-piisp schemes: - https consumes: - application/json produces: - application/json paths: /v2/funds-confirmations: post: description: Creates a confirmation of funds request at the ASPSP. Checks whether a specific amount is available at point of time of the request on an account linked to a given tuple card issuer(TPP)/card number, or addressed by IBAN and TPP respectively summary: Confirmation of Funds Request tags: - Confirmation of Funds Service operationId: V1FundsConfirmationsPost produces: - application/json parameters: - name: X-Request-ID in: header required: true type: string format: uuid description: ID of the request, unique to the call, as determined by the initiating party. - name: body in: body required: true description: Request body for a confirmation of funds request. schema: $ref: '#/definitions/ConfirmationOfFunds' - name: Consent-ID type: string required: true in: header description: This contains the consentId of the related PIISP consent, which was performed prior to this call. - name: Authorization type: string required: true in: header description: This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 responses: 200: description: OK schema: $ref: '#/definitions/V1FundsConfirmationsResponse' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 404: description: Not found 405: description: Method Not Allowed 406: description: Not Acceptable 408: description: Request Timeout 415: description: Unsupported Media Type 429: description: Too Many Requests 503: description: Service Unavailable default: description: Internal Server Error security: [] x-unitTests: [] x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false /v2/consents/confirmation-of-funds: post: description: "This method create a consent resource, defining access rights to dedicated accounts of \na given PSU-ID. These accounts are addressed explicitly in the method as \nparameters as a core function.\n\n**Side Effects**\nWhen this Consent Request is a request where the \"recurringIndicator\" equals \"true\", \nand if it exists already a former consent for recurring access on account information \nfor the addressed PSU, then the former consent automatically expires as soon as the new \nconsent request is authorised by the PSU.\n\nOptional Extension:\nAs an option, an ASPSP might optionally accept a specific access right on the access on all psd2 related services for all available accounts. \n\nAs another option an ASPSP might optionally also accept a command, where only access rights are inserted without mentioning the addressed account. \nThe relation to accounts is then handled afterwards between PSU and ASPSP. \nThis option is supported only within the Decoupled, OAuth2 or Re-direct SCA Approach. \nAs a last option, an ASPSP might in addition accept a command with access rights\n * to see the list of available payment accounts or\n \ * to see the list of available payment accounts with balances.\n" summary: Create consent tags: - Account Information Service (AIS) operationId: V1ConsentsPost produces: - application/json parameters: - name: X-Request-ID in: header required: true type: string format: uuid description: ID of the request, unique to the call, as determined by the initiating party. - name: PSU-IP-Address in: header required: true type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP. - name: PSU-Geo-Location in: header required: false type: string pattern: (GEO:)[0-9]{1,3}\.[-][0-9]{6}\,[-][0-9]{1,3}\.[0-9]{6} description: The forwarded Geo Location of the corresponding http request between PSU and TPP if available. - name: body in: body required: false description: Requestbody for a consents request schema: $ref: '#/definitions/Consents' example: access: availableAccounts: allAccounts recurringIndicator: true validUntil: "2019-04-22" combinedServiceIndicator: false frequencyPerDay: 4 responses: 201: description: Created schema: $ref: '#/definitions/Consentsresponse201' example: consentStatus: received consentId: 15535944504672sfbf51fa _links: scaOAuth: href: https://apistorebt.ro/bt/sb/oauth/.well-known/oauth-authorization-server self: href: https://apistorebt.ro/bt/sb/bt-psd2-aisp/v1/consents/15535944504672sfbf51fa status: href: https://apistorebt.ro/bt/sb/bt-psd2-aisp/v1/consents/15535944504672sfbf51fa/status 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 404: description: Not found 405: description: Method Not Allowed 406: description: Not Acceptable 408: description: Request Timeout 415: description: Unsupported Media Type 429: description: Too Many Requests 503: description: Service Unavailable default: description: Internal Server Error security: [] x-unitTests: [] x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false /v2/consents/confirmation-of-funds/{consentId}: get: description: "Returns the content of an account information consent object. \nThis is returning the data for the TPP especially in cases, \nwhere the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach.\n" summary: Get Consent Request tags: - Account Information Service (AIS) operationId: V1ConsentsByConsentIdGet produces: - application/json parameters: - name: consentId in: path required: true type: string description: ID of the corresponding consent object as returned by an Account Information Consent Request. - name: X-Request-ID in: header required: true type: string format: uuid description: ID of the request, unique to the call, as determined by the initiating party. - name: PSU-IP-Address in: header required: false type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP. - name: PSU-Geo-Location in: header required: false type: string pattern: (GEO:)[0-9]{1,3}\.[-][0-9]{6}\,[-][0-9]{1,3}\.[0-9]{6} description: The forwarded Geo Location of the corresponding http request between PSU and TPP if available. - name: Authorization type: string required: true in: header description: This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 responses: 200: description: OK schema: $ref: '#/definitions/Consentinformationresponse-200Json' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 404: description: Not found 405: description: Method Not Allowed 406: description: Not Acceptable 408: description: Request Timeout 415: description: Unsupported Media Type 429: description: Too Many Requests 503: description: Service Unavailable default: description: Internal Server Error security: [] x-unitTests: [] x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false delete: description: The TPP can delete an account information consent object if needed. summary: Delete Consent tags: - Account Information Service (AIS) operationId: V1ConsentsByConsentIdDelete produces: - application/json parameters: - name: consentId in: path required: true type: string description: ID of the corresponding consent object as returned by an Account Information Consent Request. - name: X-Request-ID in: header required: true type: string format: uuid description: ID of the request, unique to the call, as determined by the initiating party. - name: PSU-IP-Address in: header required: false type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP. - name: PSU-Geo-Location in: header required: false type: string pattern: (GEO:)[0-9]{1,3}\.[-][0-9]{6}\,[-][0-9]{1,3}\.[0-9]{6} description: The forwarded Geo Location of the corresponding http request between PSU and TPP if available. - name: X-IBM-Client-ID type: string required: true in: header description: Oauth2 Client Id - name: X-IBM-Client-Secret type: string required: true in: header description: Oauth2 Client Secret - name: Authorization type: string required: true in: header description: This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 responses: 204: description: No Content 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 404: description: Not found 405: description: Method Not Allowed 406: description: Not Acceptable 408: description: Request Timeout 415: description: Unsupported Media Type 429: description: Too Many Requests 503: description: Service Unavailable default: description: Internal Server Error security: [] x-unitTests: [] x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false /v2/consents/confirmation-of-funds/{consentId}/status: get: description: Read the status of an account information consent resource. summary: Consent status request tags: - Account Information Service (AIS) operationId: V1ConsentsStatusByConsentIdGet produces: - application/json parameters: - name: consentId in: path required: true type: string description: ID of the corresponding consent object as returned by an Account Information Consent Request. - name: X-Request-ID in: header required: true type: string format: uuid description: ID of the request, unique to the call, as determined by the initiating party. - name: PSU-IP-Address in: header required: false type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP. - name: PSU-Geo-Location in: header required: false type: string pattern: (GEO:)[0-9]{1,3}\.[-][0-9]{6}\,[-][0-9]{1,3}\.[0-9]{6} description: The forwarded Geo Location of the corresponding http request between PSU and TPP if available. - name: Authorization type: string required: true in: header description: This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 responses: 200: description: OK schema: $ref: '#/definitions/Consentstatusresponse200' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 404: description: Not found 405: description: Method Not Allowed 406: description: Not Acceptable 408: description: Request Timeout 415: description: Unsupported Media Type 429: description: Too Many Requests 503: description: Service Unavailable default: description: Internal Server Error security: [] x-unitTests: [] x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false definitions: Amount: title: amount example: currency: EUR amount: "123" type: object properties: currency: description: ISO 4217 Alpha 3 currency code example: EUR type: string pattern: '[A-Z]{3}' amount: description: |- The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot. **Example:** Valid representations for EUR with up to two decimals are: * 1056 * 5768.2 * -1.50 * 5877.78 example: "5877.78" type: string pattern: -?[0-9]{1,14}(\.[0-9]{1,3})? required: - currency - amount ConfirmationOfFunds: title: confirmationOfFunds description: "JSON Request body for the \"Confirmation of Funds Service\"\n\n \n \n \n \n \n \n \n\n \n \n \n \ \n \n \n \n \n \ \n \n \n\n \n \n \ \n \n \n
cardNumberString OptionalCard Number of the card issued by the PIISP. Should be delivered if available.
account Account ReferenceMandatoryPSU's account number.
payeeMax70TextOptionalThe merchant where the card is accepted as an information to the PSU.
instructedAmountAmountMandatoryTransaction amount to be checked within the funds check mechanism.
" type: object properties: account: description: "" $ref: '#/definitions/AccountList' instructedAmount: $ref: '#/definitions/Amount' cardNumber: description: "Card Number of the card issued by the PIISP. \nShould be delivered if available." type: string payee: description: Name payee type: string maxLength: 70 required: - account - instructedAmount example: cardNumber: "12345678901234" account: iban: ' RO98BTRLRONCRT0ABCDEFGHI' instructedAmount: currency: EUR amount: "123" V1FundsConfirmationsResponse: title: V1 Funds Confirmations Response description: "Equals \"true\" if sufficient funds are available at the time of the request, \n\"false\" otherwise." type: object properties: fundsAvailable: description: "" type: boolean required: - fundsAvailable BT-TppMessage_Error: properties: tppMessages: $ref: '#/definitions/TppMessages' additionalProperties: false TppMessages: type: array items: $ref: '#/definitions/TppMessage' TppMessage: properties: category: type: string code: properties: [] type: string text: properties: [] type: string additionalProperties: false AccountList: type: object properties: iban: properties: [] type: string additionalProperties: false required: - iban Account: type: object properties: iban: properties: [] type: string minLength: 1 required: - iban additionalProperties: false Consents: title: consents description: Content of the body of a consent request. type: object properties: account: $ref: '#/definitions/Account' description: Account, where the confirmation of funds service is aimed to be submitted to. cardNumber: properties: [] type: string description: Card Number of the card issued by the PIISP. Should be delivered if available. cardExpiryDate: properties: [] type: string description: Expiry date of the card issued by the PIISP cardInformation: properties: [] type: string description: Additional explanation for the card product. registrationInformation: properties: [] type: string description: Additional information about the registration process for the PSU, e.g. a reference to the TPP / PSU contract required: - account example: account: iban: RO98BTRLRONCRT0ABCDEFGHI cardNumber: "12345678912345" cardExpiryDate: "2019-04-22" cardInformation: MyMerchant Loyalty Card registrationInformation: Your contract Number 1234 with MyMerchant is completed with the registration with your bank. additionalProperties: false AccountAccess: title: accountAccess type: object properties: accounts: description: "Is asking for detailed account information. \n\nIf the array is empty, the TPP is asking for an accessible account list. \nThis may be restricted in a PSU/ASPSP authorization dialogue.\nIf the array is empty, also the arrays for balances or transactions shall be empty, if used." items: type: object $ref: '#/definitions/IBANList' balances: description: "Is asking for balances of the addressed accounts.\n\nIf the array is empty, the TPP is asking for the balances of all accessible account lists. \nThis may be restricted in a PSU/ASPSP authorization dialogue.\nIf the array is empty, also the arrays for accounts or transactions shall be empty, if used." items: type: object $ref: '#/definitions/IBANList' transactions: description: "Is asking for transactions of the addressed accounts. \n\nIf the array is empty, the TPP is asking for the transactions of all accessible account lists. \nThis may be restricted in a PSU/ASPSP authorization dialogue.\nIf the array is empty, also the arrays for accounts or balances shall be empty, if used." items: type: object $ref: '#/definitions/IBANList' availableAccounts: description: |- Optional if supported by API provider. Only the value "allAccounts" is admitted. example: allAccounts type: string default: allAccounts additionalProperties: false Consentsresponse201: title: consentsResponse-201 description: Body of the JSON response for a successful conset request. type: object properties: consentStatus: $ref: '#/definitions/ConsentStatus' consentId: description: ID of the corresponding consent object as returned by an Account Information Consent Request. type: string _links: description: "A list of hyperlinks to be recognised by the TPP.\n\nType of links admitted in this response (which might be extended by single ASPSPs as indicated in its XS2A \ndocumentation):\n - 'scaRedirect': \n In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the \n PSU browser.\n - 'scaOAuth': \n In case of an OAuth2 based Redirect Approach, the ASPSP is transmitting the link where the configuration \n of the OAuth2 Server is defined. \n The configuration follows the OAuth 2.0 Authorisation Server Metadata specification. \n - 'startAuthorisation': \n In case, where an explicit start of the transaction authorisation is needed, \n but no more data needs to be updated (no authentication method to be selected, \n no PSU identification nor PSU authentication data to be uploaded).\n - 'startAuthorisationWithPsuIdentification': \n The link to the authorisation end-point, where the authorisation sub-resource has to be generated \n while uploading the PSU identification data.\n \ - 'startAuthorisationWithPsuAuthentication':\n The link to the authorisation end-point, where the authorisation sub-resource has to be generated \n while uploading the PSU authentication data.\n - 'startAuthorisationWithAuthenticationMethodSelection':\n \ The link to the authorisation end-point, where the authorisation sub-resource has to be generated \n while selecting the authentication method. This link is contained under exactly the same conditions \n as the data element 'scaMethods' \n - 'startAuthorisationWithTransactionAuthorisation':\n The link to the authorisation end-point, where the authorisation sub-resource has to be generated \n while authorising the transaction e.g. by uploading an OTP received by SMS.\n - 'self': \n The link to the Establish Account Information Consent resource created by this request. \n This link can be used to retrieve the resource data. \n - 'status': \n The link to retrieve the status of the account information consent.\n - 'scaStatus': The link to retrieve the scaStatus of the corresponding authorisation sub-resource. \n This link is only contained, if an authorisation sub-resource has been already created." type: object additionalProperties: type: object scaMethods: 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. type: array items: $ref: '#/definitions/AuthenticationObject' chosenScaMethod: $ref: '#/definitions/AuthenticationObject' challengeData: $ref: '#/definitions/ChallengeData' message: description: Text to be displayed to the PSU, e.g. in a Decoupled SCA Approach. type: string maxLength: 512 required: - consentStatus - consentId - _links example: consentStatus: received consentId: 15535944504672sfbf51fa _links: scaOAuth: href: https://apistorebt.ro/bt/sb/oauth/.well-known/oauth-authorization-server self: href: https://apistorebt.ro/bt/sb/bt-psd2-aisp/v1/consents/15535944504672sfbf51fa status: href: https://apistorebt.ro/bt/sb/bt-psd2-aisp/v1/consents/15535944504672sfbf51fa/status ConsentStatus: title: consentStatus example: received x-enum-elements: - name: received description: "" - name: rejected description: "" - name: valid description: "" - name: revokedByPsu description: "" - name: expired description: "" - name: terminatedByTpp description: "" type: string enum: - received - rejected - valid - revokedByPsu - expired - terminatedByTpp Consentinformationresponse-200Json: title: consentInformationResponse-200_json description: Body of the JSON response for a successfull get consent request. type: object properties: access: $ref: '#/definitions/AccountAccess' recurringIndicator: 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: false type: boolean validUntil: description: "This parameter is requesting a valid until date for the requested consent. \nThe content is the local ASPSP date in ISO-Date Format, e.g. 2017-10-30. \n\nIf a maximal available date is requested, a date in far future is to be used: \"9999-12-31\". \nThe consent object to be retrieved by the GET Consent Request will contain the adjusted date." example: "2020-12-31" type: string format: date 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". example: 4 type: integer format: int32 lastActionDate: description: "This date is containing the date of the last action on the consent object either through \nthe XS2A interface or the PSU/ASPSP interface having an impact on the status." example: "2018-07-01" type: string format: date consentStatus: $ref: '#/definitions/ConsentStatus' required: - access - recurringIndicator - validUntil - frequencyPerDay - lastActionDate - consentStatus example: access: allPSD2: allAccounts recurringIndicator: true validUntil: "2019-04-22" frequencyPerDay: "4" consentStatus: valid lastActionDate: "2019-03-26" Consentstatusresponse200: title: consentStatusResponse-200 description: Body of the JSON response for a successful get status request for a consent. type: object properties: consentStatus: $ref: '#/definitions/ConsentStatus' required: - consentStatus example: consentStatus: valid IBANList: type: array items: $ref: '#/definitions/IBAN' IBAN: type: object properties: iban: type: string additionalProperties: false required: - iban AuthenticationObject: title: authenticationObject description: Authentication Object type: object properties: authenticationType: $ref: '#/definitions/AuthenticationType' authenticationMethodId: description: An identification provided by the ASPSP for the later identification of the authentication method selection. example: myAuthenticationID type: string maxLength: 35 authenticationVersion: 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. type: string name: 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 type: string explanation: description: Detailed information about the SCA method for the PSU. example: Detailed information about the SCA method for the PSU. type: string required: - authenticationType - authenticationMethodId AuthenticationType: title: authenticationType example: SMS_OTP x-enum-elements: - name: SMS_OTP description: "" - name: CHIP_OTP description: "" - name: PHOTO_OTP description: "" - name: PUSH_OTP description: "" type: string enum: - SMS_OTP - CHIP_OTP - PHOTO_OTP - PUSH_OTP ChallengeData: title: challengeData type: object properties: image: description: |- PNG data (max. 512 kilobyte) to be displayed to the PSU, Base64 encoding, cp. [RFC4648]. This attribute is used only, when PHOTO_OTP or CHIP_OTP is the selected SCA method. type: string data: description: String challenge data type: string imageLink: description: A link where the ASPSP will provides the challenge image for the TPP. type: string otpMaxLength: description: The maximal length for the OTP to be typed in by the PSU. type: integer format: int32 otpFormat: $ref: '#/definitions/OtpFormat' additionalInformation: description: |- Additional explanation for the PSU to explain e.g. fallback mechanism for the chosen SCA method. The TPP is obliged to show this to the PSU. type: string OtpFormat: title: OtpFormat example: characters x-enum-elements: - name: characters description: "" - name: integer description: "" type: string enum: - characters - integer x-ibm-configuration: enforced: true testable: true phase: realized x-ibm-endpoints: - endpointUrl: https://api.apistorebt.ro/bt/sb type: - production - development ...