--- swagger: "2.0" info: version: 3.1.5 title: Periodic Payments x-ibm-name: sibs-psd2-periodic-payments-stub-api description: "The Payment Initiation API enables you to initiate a payment using one of the payment products made available by the Bank of the Payment Service User in his internet Banking.\n\nWith this API it is possible to integrate this type of of payments in an online store as well as to provide personal finance services to both private and corporate clients.\n\n\nThis API intends to provide an interface to access PSD2 Payments services.\n\nThe API is designed on a REST model using JSON structures. \n" contact: name: "" url: "" license: name: "" url: "" termsOfService: "" schemes: - https produces: - application/json consumes: - application/json paths: /{aspsp-cde}/v1-0-3/periodic-payments/{payment-product}: post: operationId: paymentInitiationRequest tags: - Payment Initiation Request summary: Payment Initiation Request description: Requests the creation of a payment initiation. parameters: - $ref: '#/parameters/TPP-Transaction-ID' - $ref: '#/parameters/TPP-Request-ID' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-ID-Type' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-Corporate-ID-Type' - $ref: '#/parameters/PSU-Consent-ID' - $ref: '#/parameters/PSU-Agent' - $ref: '#/parameters/PSU-IP-Address' - $ref: '#/parameters/PSU-IP-Port' - $ref: '#/parameters/PSU-Device-ID' - $ref: '#/parameters/PSU-Device-Fingerprint' - $ref: '#/parameters/Transaction-SCA-Performed' - $ref: '#/parameters/PSU-Geo-Location' - $ref: '#/parameters/TPP-Redirect-URI' - $ref: '#/parameters/TPP-Delegated-Preferred' - $ref: '#/parameters/Signature' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Certificate' - $ref: '#/parameters/Delegation-ID' - $ref: '#/parameters/Date' - $ref: '#/parameters/aspsp-cde' - $ref: '#/parameters/payment-product' - $ref: '#/parameters/tppRedirectPreferred' - $ref: '#/parameters/PaymentRequest' responses: 201: description: Created headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/PaymentResponseResource' 400: description: Bad Request. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 401: description: Unauthorized. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 403: description: Forbidden. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 404: description: Not Found. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 405: description: Method Not Allowed. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 406: description: Not Acceptable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 408: description: Request Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 415: description: Unsupported Media Type. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 429: description: Too Many Requests. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 500: description: Internal Server Error. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 503: description: Service Unavailable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 504: description: Gatewaty Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' /{aspsp-cde}/v1-0-3/periodic-payments/{payment-product}/{payment-id}: put: operationId: updatePSUData tags: - Update PSU Data summary: Update PSU Data description: Updates user data requested by the ASPSP parameters: - $ref: '#/parameters/TPP-Request-ID' - $ref: '#/parameters/TPP-Transaction-ID' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-ID-Type' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-Corporate-ID-Type' - $ref: '#/parameters/Signature' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Certificate' - $ref: '#/parameters/Date' - $ref: '#/parameters/aspsp-cde' - $ref: '#/parameters/payment-product' - $ref: '#/parameters/payment-id' - $ref: '#/parameters/PaymentUpdateRequest' responses: 201: description: Created headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/PaymentUpdateResponseResource' 400: description: Bad Request. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 401: description: Unauthorized. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 403: description: Forbidden. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 404: description: Not Found. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 405: description: Method Not Allowed. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 406: description: Not Acceptable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 408: description: Request Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 415: description: Unsupported Media Type. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 429: description: Too Many Requests. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 500: description: Internal Server Error. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 503: description: Service Unavailable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 504: description: Gatewaty Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' get: operationId: getPaymentRequest tags: - Get Payment Request summary: Get Payment Request description: Requests properties of a payment initiation parameters: - $ref: '#/parameters/TPP-Request-ID' - $ref: '#/parameters/TPP-Transaction-ID' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-ID-Type' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-Corporate-ID-Type' - $ref: '#/parameters/Signature' - $ref: '#/parameters/TPP-Certificate' - $ref: '#/parameters/Date' - $ref: '#/parameters/aspsp-cde' - $ref: '#/parameters/payment-product' - $ref: '#/parameters/payment-id' responses: 200: description: OK headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/PaymentDetailsResponseResource' 400: description: Bad Request. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 401: description: Unauthorized. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 403: description: Forbidden. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 404: description: Not Found. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 405: description: Method Not Allowed. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 406: description: Not Acceptable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 408: description: Request Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 415: description: Unsupported Media Type. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 429: description: Too Many Requests. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 500: description: Internal Server Error. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 503: description: Service Unavailable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 504: description: Gatewaty Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' delete: responses: 200: description: OK. schema: $ref: '#/definitions/PaymentCancelResponseResource' 400: description: Bad Request. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 401: description: Unauthorized. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 403: description: Forbidden. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 404: description: Not Found. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 405: description: Method Not Allowed. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 406: description: Not Acceptable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 408: description: Request Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 415: description: Unsupported Media Type. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 429: description: Too Many Requests. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 500: description: Internal Server Error. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 503: description: Service Unavailable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 504: description: Gatewaty Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' tags: - Cancel Payment Request summary: Cancel Payment Request operationId: CancelPaymentRequest parameters: - $ref: '#/parameters/aspsp-cde' - $ref: '#/parameters/payment-id' - $ref: '#/parameters/payment-product' - $ref: '#/parameters/TPP-Request-ID' - $ref: '#/parameters/TPP-Redirect-URI' - $ref: '#/parameters/PSU-Geo-Location' - $ref: '#/parameters/PSU-Agent' - $ref: '#/parameters/PSU-IP-Address' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-ID-Type' - $ref: '#/parameters/PSU-Corporate-ID-Type' - $ref: '#/parameters/TPP-Transaction-ID' - $ref: '#/parameters/Signature' - $ref: '#/parameters/TPP-Certificate' - $ref: '#/parameters/Date' description: Cancels a given periodic payment initiaton resource. /{aspsp-cde}/v1-0-3/periodic-payments/{payment-product}/{payment-id}/status: get: operationId: getStatusRequest tags: - Get Status Request summary: Get Status Request description: Requests status of a payment initiation parameters: - $ref: '#/parameters/TPP-Request-ID' - $ref: '#/parameters/TPP-Transaction-ID' - $ref: '#/parameters/Signature' - $ref: '#/parameters/TPP-Certificate' - $ref: '#/parameters/Date' - $ref: '#/parameters/aspsp-cde' - $ref: '#/parameters/payment-product' - $ref: '#/parameters/payment-id' responses: 200: description: OK headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/PaymentStatusResponseResource' 400: description: Bad Request. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 401: description: Unauthorized. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 403: description: Forbidden. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 404: description: Not Found. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 405: description: Method Not Allowed. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 406: description: Not Acceptable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 408: description: Request Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 415: description: Unsupported Media Type. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 429: description: Too Many Requests. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 500: description: Internal Server Error. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 503: description: Service Unavailable. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' 504: description: Gatewaty Timeout. headers: Location: type: string description: Response Location. schema: $ref: '#/definitions/ErrorMessageWithStatus' definitions: AccountReference: description: Identifier of the addressed account. type: object properties: iban: description: This data element is used in a mutually exclusive way with BBAN. type: string pattern: ^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}$ default: PT000 bban: description: This data element is used for payment accounts which have no IBAN. type: string default: "1" pattern: ^[a-zA-Z0-9]{1,30}$ pan: description: Reserved for future use. Primary Account Number (PAN) of a card, can be tokenised by the ASPSP due to PCI DSS requirements. type: string maxLength: 35 default: "" maskedPan: description: Reserved for future use. Primary Account Number (PAN) of a card in a masked form. type: string maxLength: 35 default: "" msisdn: description: Reserved for future use. An alias to access a payment account via a registered mobile phone number type: string maxLength: 35 default: "" currency: description: ISO 4217 Alpha 3 currency code. type: string default: EUR pattern: ^[A-Z]{3,3}$ additionalProperties: false Address: description: Address type: object required: - country properties: street: description: Street type: string maxLength: 70 default: "" buildingNumber: description: Building Number type: string default: "" city: description: City type: string default: "" postalCode: description: Postal Code type: string default: "" country: description: Country type: string default: "" additionalProperties: false Amount: description: Amount type: object required: - currency - content properties: currency: description: | ISO 4217 currency code type: string pattern: ^[A-Z]{3,3}$ default: EUR content: description: | The amount given with fractional digits, where fractions must be compliant to the currency definition. The decimal separator is a dot. type: string pattern: ^\-{0,1}[0-9]{1,9}(\.[0-9]{0,2}){0,1}$ default: "0" additionalProperties: false AuthenticationArray: description: Array of Authentication object type: array items: $ref: '#/definitions/Authentication' description: Authentication Data additionalProperties: false Authentication: description: Authentication Data type: object required: - authenticationType - authenticationMethodId properties: authenticationType: description: Type of the authentication method. $ref: '#/definitions/AuthenticationType' 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 default: "" authenticationMethodId: description: | An identification provided by the ASPSP for the later identification of the authentication method selection. type: string maxLength: 35 default: "" 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. type: string default: "" explanation: description: | detailed information about the sca method for the PSU. type: string default: "" additionalProperties: false AuthenticationType: description: | authentication types: * SMS_OTP - An SCA method, where an OTP linked to the transaction to be authorised is sent to the PSU through a SMS channel. * CHIP_OTP - An SCA method, where an OTP is generated by a chip card, e.g. an TOP derived from an EMV cryptogram. To contact the card, the PSU normally needs a (handheld) device. With this device, the PSU either reads the challenging data through a visual interface like flickering or the PSU types in the challenge through the device key pad. The device then derives an OTP from the challenge data and displays the OTP to the PSU. * PHOTO_OTP - An SCA method, where the challenge is a QR code or similar encoded visual data which can be read in by a consumer device or specific mobile app. The device resp. the specific app than derives an OTP from the visual challenge data and displays the OTP to the PSU. * PUSH_OTP - An OTP is pushed to a dedicated authentication APP and displayed to the PSU. type: string enum: - SMS_OTP - CHIP_OTP - PHOTO_OTP - PUSH_OTP default: SMS_OTP additionalProperties: false Challenge: description: Requested Authentication Data type: object properties: image: description: | PNG data (max. 512 kilobyte) to be displayed to the PSU, Base64 encoding , cp. [RFC 4648]. This attribute is used only, when PHOTO_OTP or CHIP_OTP is the selected SCA method. type: string format: byte default: "" data: description: String challenge data type: string default: "" imageLink: description: A link where the ASPSP will provides the challenge image for the TPP. type: string default: "" otpMaxLength: description: The maximal length for the OTP to be typed in by the PSU. type: number default: 0 otpFormat: description: The format type of the OTP to be typed in. type: string enum: - characters - integer default: integer 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 default: "" additionalProperties: false ChargeBearer: description: TBD type: string enum: - DEBT - CRED - SHAR - SLEV default: SHAR additionalProperties: false ErrorMessage: description: Error Information. type: object properties: tppMessages: $ref: '#/definitions/TppMessageArray' description: Messages to the TPP on operational issues. additionalProperties: false ErrorMessageWithStatus: description: Error and status Information. type: object properties: transactionStatus: $ref: '#/definitions/TransactionStatusType' description: The transaction status is filled with codes of the ISO 20022 corresponding element. tppMessages: $ref: '#/definitions/TppMessageArray' description: Messages to the TPP on operational issues. additionalProperties: false ExecutionRule: description: following/preceeding type: string enum: - following - preceeding additionalProperties: false FrequencyCode: description: |- Daily Weekly EveryTwoWeeks Monthly EveryTwoMonths Quarterly SemiAnnual Annual type: string enum: - Daily - Weekly - EveryTwoWeeks - Monthly - EveryTwoMonths - Quarterly - SemiAnnual - Annual default: Monthly additionalProperties: false MessageCode: description: Message error codes. type: string enum: - SERVICE_BLOCKED - CORPORATE_ID_IVALID - CONSENT_UNKNOWN - CONSENT_INVALID - CONSENT_EXPIRED - RESOURCE_UNIKNOWN - RESOURCE_EXPIRED - TIMESTAMP_INVALID - PERIOD_INVALID - SCA_METHOD_UNKKNOWN - TRANSACTION_ID_INVALID - PRODUCT_INVALID - PRODUCT_UNKNOWN - PAYMENT_FAILED - REQUIRED_KID_MISSING - SESSIONS_NOT_SUPPORTED - ACCESS_EXCEEDED - REQUESTED_FORMATS_INVALID - CARD_INVALID - NO_PIIS_ACTIVATION default: CONSENT_INVALID additionalProperties: false PaymentCancelResponseResource: type: object properties: transactionStatus: description: The transaction status is filled with codes of the ISO 20022 data table. $ref: '#/definitions/TransactionStatusType' _links: $ref: '#/definitions/PaymentLink' description: 'A list of hyperlinks to be recognised by the TPP. The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request. Remark: All links can be relative or full links, to be decided by the ASPSP. Type of links admitted in this response, (further links might be added for ASPSP defined extensions): “redirect”: In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browser. “updatePsuIdentification”: The link to the payment initiation resource, which needs to be updated by the PSU identification. This might be used in an embedded, redirect or decoupled SCA Approach, where the PSU ID was missing in the first request. “updatePsuAuthentication”: The link to the payment initiation resource, which needs to be updated by a PSU password and eventually the PSU identification if not delivered yet. This is used in case of the Embedded or Decoupled SCA approach. “selectAuthenticationMethod” : This is a link to a resource, where the TPP can select the applicable strong customer authentication methods for the PSU, if there were several available authentication methods. This link contained under exactly the same conditions as the data element “authenticationMethods”, see above. “authoriseTransaction” : The link to the payment initiation resource, where the “Payment Authorisation Request” is sent to. This is the link to the resource which will authorise the payment by checking the SCA authentication data within the Embedded SCA approach.' psuMessage: type: string description: Text to be displayed to the PSU. tppMessages: $ref: '#/definitions/TppMessageArray' description: Messages to the TPP on operational issues. transactionFees: description: Can be used by the ASPSP to transport transaction fees relevant for the underlying payments. $ref: '#/definitions/Amount' transactionFeeIndicator: type: boolean description: If equals “true”, the transaction will involve specific transaction cost as shown by the ASPSP in their public price list or as agreed between ASPSP and PSU. If equals “false”, the transaction will not involve additional specific transaction costs to the PSU. 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 “selectAuthenticationMethods” contained in the response body. These methods shall be presented towards the PSU for selection by the TPP. $ref: '#/definitions/AuthenticationArray' additionalProperties: false description: Cancels a given periodic payment initiaton resource. PaymentDetailsResponseResource: description: Returns the content of a payment initiation object. type: object required: - transactionStatus - paymentId properties: transactionStatus: $ref: '#/definitions/TransactionStatusType' description: Status paymentId: description: Resource identification of the generated payment initiation resource. type: string default: "" debtorAccount: $ref: '#/definitions/AccountReference' description: Debtor account instructedAmount: $ref: '#/definitions/Amount' description: Instructed amount (inc. Curr.). creditorAccount: $ref: '#/definitions/AccountReference' description: Creditor account creditorAgent: description: BICFI type: string pattern: ^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$ default: ABCDEFABC0A creditorName: description: Name of the creditor if a “Debited” transaction type: string maxLength: 70 default: "" creditorAddress: $ref: '#/definitions/Address' description: Address remittanceInformationUnstructured: description: Unstructured Remittance Information type: string maxLength: 140 default: "" transactionFees: $ref: '#/definitions/Amount' description: Can be used by the ASPSP to transport transaction fees relevant for the underlying payments. transactionFeeIndicator: description: If equals “true”, the transaction will involve specific transaction cost as shown by the ASPSP in their public price list or as agreed between ASPSP and PSU. If equals “false”, the transaction will not involve additional specific transaction costs to the PSU. type: boolean default: false startDate: type: string format: date description: StartDate purposeCode: type: string description: Specifies the external purpose code in the format of character string with a maximum length of 4 characters. The list of valid codes is an external code list published. maxLength: 4 ultimateCreditor: type: string ultimateDebtor: type: string requestedExecutionTime: type: string format: date-time requestedExecutionDate: type: string format: date default: "9999-12-31" chargeBearer: $ref: '#/definitions/ChargeBearer' description: Specifies which party/parties will bear the charges associated with the processing of the payment transaction. endDate: type: string format: date description: EndDate frequency: $ref: '#/definitions/FrequencyCode' description: YEAR - Annual ADHO - Adhoc MNTH - Monthly DAIL - Daily INDA - Intraday WEEK - Weekly . . . executionRule: $ref: '#/definitions/ExecutionRule' description: Following/Preceeding dayOfExecution: type: integer format: int32 description: 'Month day to execute payment. The format is following the regular expression \d{1,2}. Example: The first day is addressed by "1".' creditorClearingCode: type: string maxLength: 35 description: Clearing Code of the Creditor Finantial Institution. creditorAgentName: description: Name of the creditor's agent type: string maxLength: 140 default: "" creditorAgentAddress: $ref: '#/definitions/Address' description: Address additionalProperties: false PaymentLink: description: | A list of hyperlinks to be recognized by the TPP. properties: redirect: description: | A link to an ASPSP site where SCA is performed within the Redirect SCA approach. type: string default: "" updatePsuIdentification: description: | The link to the payment initiation or account information resource, which needs to be updated by the PSU NextGenPSD2 XS2A Framework – Implementation Guidelines Complex Data Types and Code Lists Published by the Berlin Group under Creative Commons Attribution-NoDerivatives 4.0 International Public License Page 133(ref. License Notice for full license conditions) Attribute Type Condition Description identification if not delivered yet. type: string default: "" updatePsuAuthentication: description: | The link to the payment initiation or account information resource, which needs to be updated by a PSU password and eventually the PSU identification if not delivered yet. type: string default: "" selectAuthenticationMethod: description: | This is a link to a resource, where the TPP can select the applicable second factor authentication methods for the PSU, if there were several available authentication methods. type: string default: "" authoriseTransaction: description: | The link to the payment initiation or consent resource, where the “Transaction Authorisation”Request” is sent to. This is the link to the resource which will authorise the payment or the consent by checking the SCA authentication data within the Embedded SCA approach. type: string default: "" self: description: | The link to the payment initiation resource created by the request itself. This link can be used later to retrieve the transaction status of the payment initiation. type: string default: "" updateProprietaryData: description: | The link to the payment initiation or account information resource, which needs to be updated by the proprietary data. type: string default: "" status: description: Stgatus of the resource. type: string default: "" additionalProperties: false PaymentRequestResource: description: Creates a payment initiation request at the ASPSP. type: object required: - instructedAmount - creditorAccount - creditorName - startDate - frequency properties: endToEndIdentification: description: Unique identification as assigned by the sending party to unambiguously identify this payment. type: string maxLength: 35 default: "" debtorAccount: $ref: '#/definitions/AccountReference' description: Debtor account instructedAmount: $ref: '#/definitions/Amount' description: Instructed amount (inc. Curr.) creditorAccount: $ref: '#/definitions/AccountReference' description: Creditor account creditorAgent: description: BICFI type: string pattern: ^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$ default: ABCDEFABC0A creditorName: description: Name of the creditor if a “Debited” transaction type: string maxLength: 70 minLength: 1 default: a creditorAddress: $ref: '#/definitions/Address' description: Address remittanceInformationUnstructured: description: Unstructured Remittance Information type: string maxLength: 140 default: "" startDate: type: string format: date description: StartDate purposeCode: type: string description: Specifies the category purpose, as published in an external category purpose code list. maxLength: 4 ultimateCreditor: type: string description: Reserved for future use ultimateDebtor: type: string description: Reserved for future use requestedExecutionTime: type: string format: date-time description: Reserved for future use requestedExecutionDate: type: string format: date description: Reserved for future use default: "9999-12-31" chargeBearer: $ref: '#/definitions/ChargeBearer' description: Specifies which party/parties will bear the charges associated with the processing of the payment transaction. endDate: type: string format: date description: EndDate frequency: $ref: '#/definitions/FrequencyCode' description: Daily, Weekly, EveryTwoWeeks, Monthly, EveryTwoMonths, Quarterly, SemiAnnual, Annual, executionRule: $ref: '#/definitions/ExecutionRule' description: Following/Preceeding dayOfExecution: type: integer format: int32 description: 'Month day to execute payment. The format is following the regular expression \d{1,2}. Example: The first day is addressed by "1".' creditorClearingCode: type: string maxLength: 35 description: Clearing Code of the Creditor Finantial Institution creditorAgentName: description: Name of the creditor's agent type: string maxLength: 140 default: "" creditorAgentAddress: $ref: '#/definitions/Address' description: Address additionalProperties: false PaymentResponseResource: description: Creates a payment initiation response to TPP. type: object required: - transactionStatus - paymentId - _links properties: transactionStatus: $ref: '#/definitions/TransactionStatusType' description: The transaction status is filled with codes of the ISO 20022 data table. paymentId: description: | Resource identification of the generated payment initiation resource. type: string default: "" transactionFees: $ref: '#/definitions/Amount' description: Can be used by the ASPSP to transport transaction fees relevant for the underlying payments. transactionFeeIndicator: description: | If equals "true" the transaction will involve specific transaction cost as shown by the ASPSP in their public price list or as agreed between ASPSP and PSU. If equals "false" the transaction will not involve additional specific transaction costs to the PSU. type: boolean default: false scaMethods: $ref: '#/definitions/AuthenticationArray' 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 “selectAuthenticationMethods” contained in the response body. These methods shall be presented towards the PSU for selection by the TPP. chosenScaMethod: $ref: '#/definitions/Authentication' description: | This data element is only contained in the response if the APSPS has chosen the Embedded SCA Approach, if the PSU is already identified e.g. with the first relevant factor or alternatively an access token, if SCA is required and if the authentication method is implicitly selected. challengeData: $ref: '#/definitions/Challenge' description: | It is contained in addition to the data element chosenScaMethod if challenge data is needed for SCA. In rare cases this attribute is also used in the context of the psuAuthentication link. _links: $ref: '#/definitions/PaymentLink' psuMessage: description: Text to be displayed to the PSU. type: string default: "" tppMessages: $ref: '#/definitions/TppMessageArray' description: Messages to the TPP on operational issues. creditorClearingCode: type: string maxLength: 35 description: Clearing Code of the Creditor Finantial Institution. additionalProperties: false PaymentStatusResponseResource: description: Informs TPP about status of a payment initiation. type: object required: - transactionStatus properties: transactionStatus: $ref: '#/definitions/TransactionStatusType' description: In case where the Payment Initiation Request was JSON encoded as defined in Section 5.3.1, the status is returned in this JSON based encoding. additionalProperties: false PaymentUpdateRequestResource: description: Update information related to a previous payment initiation in order to obtain PSUId credentials. It is only to be used to support Embedded method. type: object properties: psuData: $ref: '#/definitions/PSUData' description: Include all credentials related data (e.g., user, password and additional data accordingly with ASPSP requests) scaAuthenticationData: description: | SCA authentication data, depending on the chosen authentication method. if the data is binary, then it is base64 encoded. type: string default: "" authenticationMethodId: description: | The authentication method ID as provided by the ASPSP This property is mandatory in a Select Authentication Method type: string default: "" additionalProperties: false PaymentUpdateResponseResource: description: Sends an update information related to a previous payment initiation to TPP. type: object required: - transactionStatus properties: chosenScaMethod: $ref: '#/definitions/Authentication' description: If the ASPSP has chosen the Embedded SCA Approach, if the PSU is already identified e.g. with the first relevant factor or alternatively an access token, if SCA is required and if the authentication method is implicitly selected. challengeData: $ref: '#/definitions/Challenge' description: | It is contained in addition to the data element chosenScaMethod if challenge data is needed for SCA. In rare cases this attribute is also used in the context of the psuAuthentication link. scaMethods: $ref: '#/definitions/AuthenticationArray' 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 "startAuthorisationWith AuthenticationMethodSelection" contained in the response body. These methods shall be presented towards the PSU for selection by the TPP. _links: $ref: '#/definitions/PaymentLink' description: | A list of hyperlinks to be recognised by the TPP. The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request. Remark: All links can be relative or full links, to be decided by the ASPSP. Type of links admitted in this response, (further links might be added for ASPSP defined extensions): - “redirect”: In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browser. “oAuth”: In case of a SCA OAuth2 Approach, the ASPSP is transmitting the URI where the configuration of the Authorisation Server can be retrieved. The configuration follows the OAuth 2.0 Authorisation Server Metadata specification. “updatePsuIdentification”: The link to the payment initiation resource, which needs to be updated by the PSU identification. This might be used in an embedded, redirect or decoupled SCA Approach, where the PSU ID was missing in the first request. “updatePsuAuthentication”: The link to the payment initiation resource, which needs to be updated by a PSU password and eventually the PSU identification if not delivered yet. This is used in case of the Embedded or Decoupled SCA approach. “selectAuthenticationMethod” : This is a link to a resource, where the TPP can select the applicable strong customer authentication methods for the PSU, if there were several available authentication methods. This link contained under exactly the same conditions as the data element “authenticationMethods”, see above. “authoriseTransaction” : The link to the payment initiation resource, where the “Payment Authorisation Request” is sent to. This is the link to the resource which will authorise the payment by checking the SCA authentication data within the Embedded SCA approach. “self” : The link to the payment initiation resource created by this request. This link can be used to retrieve the resource data. “updateProprietaryData” : The link to the payment initiation or account information resource, which needs to be updated by the proprietary data. “status”: The link to retrieve the transaction status of the payment initiation. transactionStatus: $ref: '#/definitions/TransactionStatusType' description: This is the “authentication status” of the consent. psuMessage: description: Include all credentiText to be displayed to the PSUals related data (e.g., user, password and additional data accordingly with ASPSP requests) type: string default: "" additionalProperties: false PSUData: description: The password or encryptedPassword subfield is used, depending on encryption requirements of the ASPSP as indicated in the corresponding hyperlink contained in the last response message of the ASPSP. type: object properties: password: description: PSU Password. type: string minLength: 1 default: "1" additionalProperties: false TppMessage: required: - category - code description: Transports additional error information. properties: category: type: string default: "" description: Category of the error. Only "ERROR" or "WARNING" permitted. code: $ref: '#/definitions/MessageCode' description: Message error code. path: type: string default: "" description: Path of the element of the request message which provoked this error message. text: type: string maxLength: 512 default: "" description: Additional explaining text. additionalProperties: false TppMessageArray: type: array description: Messages to the TPP on operational issues. items: $ref: '#/definitions/TppMessage' description: Transports additional error information. additionalProperties: false TransactionStatusType: description: |- ISO20022: The transaction status is filled with value of the ISO20022 data table. RCVD : RECEIVED PDNG : PENDING PATC : PARTIALLY ACCEPTED TECHNICAL CORRECT ACTC : ACCEPTED TECHNICAL VALIDATION ACFC : ACCEPTED FUNDS CHECKED ACWC : ACCEPTED WITH CHANGE ACWP : ACCEPTED WITHOUT POSTING ACSP : ACCEPTED SETTLEMENT IN PROCESS ACSC : ACCEPTED SETTLEMENT COMPLETED ACCC : ACCEPTED SETTLEMENT COMPLETED CREDITOR CANC : CANCELED RJCT : REJECTED type: string enum: - RCVD - PDNG - PATC - ACTC - ACFC - ACWC - ACWP - ACSP - ACSC - ACCC - CANC - RJCT default: RJCT additionalProperties: false parameters: aspsp-cde: name: aspsp-cde in: path description: Identification of the aspsp required: true type: string default: "" payment-id: name: payment-id in: path description: Identification of the payment required: true type: string default: "" payment-product: name: payment-product in: path description: Type of payment required: true type: string default: sepa-credit-transfers enum: - sepa-credit-transfers - cross-border-credit-transfers - instant-sepa-credit-transfers - target-2-payments tppRedirectPreferred: name: tppRedirectPreferred in: query 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. required: false type: boolean default: false TPP-Transaction-ID: name: TPP-Transaction-ID in: header description: ID of the transaction as determined by the initiating party. required: true type: string format: uuid default: "" TPP-Request-ID: name: TPP-Request-ID in: header description: ID of the request, unique to the call, as determined bu the initiating party. required: true type: string format: uuid default: "" PSU-ID: name: PSU-ID in: header description: User identification in ASPSP required: false type: string default: "" PSU-ID-Type: name: PSU-ID-Type in: header description: Type of the PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility. required: false type: string default: "" PSU-Corporate-ID: name: PSU-Corporate-ID in: header description: Corporate User identification in ASPSP required: false type: string default: "" PSU-Corporate-ID-Type: name: PSU-Corporate-ID-Type in: header description: Might be mandated in the ASPSPs documentation. Only used in a corporate context. required: false type: string default: "" PSU-Consent-ID: name: PSU-Consent-ID in: header description: This data element may be contained, if the payment initiation transaction is part of a session, i.e. combined AIS/PIS service. This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation. required: false type: string default: "" PSU-Agent: name: PSU-Agent in: header description: The forwarded Agent header field of the http request between PSU and TPP. required: false type: string default: "" PSU-IP-Address: 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. required: true type: string default: "" PSU-IP-Port: 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. required: false type: string default: "" PSU-Device-ID: 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. required: false type: string default: "" PSU-Device-Fingerprint: name: PSU-Device-Fingerprint in: header description: Fingerprint of the device used in the request between PSU and TPP, if available. required: false type: string default: "" Transaction-SCA-Performed: name: Transaction-SCA-Performed in: header description: Only used for Delegated Authentication Approach. \n "NSCA" - "SCA Not performed"; \n "SUCC" - "SCA Performed with Success"; \n If this data element is not used, there is no information about transaction SCA authentication required: false type: string enum: - NSCA - SUCC PSU-Geo-Location: name: PSU-Geo-Location in: header description: The forwarded Geo Location of the corresponding http request between PSU and TPP if available. required: false type: string pattern: ^GEO:[-?+?(\d){1,3}.(\d){6}]{8,11};[-?+?(\d){1,3}.(\d){6}]{8,11}$ default: GEO:1.111111;-1.111111 TPP-Redirect-URI: name: TPP-Redirect-URI in: header description: URI of the TPP, where the transaction flow shall be redirected to after a Redirect. Shall be contained at least if the tppRedirectPreferred parameter is set to true or is missing. required: false type: string default: "" TPP-Delegated-Preferred: name: TPP-Delegated-Preferred in: header description: If it equals "true", the TPP requests a delegated SCA approach. If it equals "false", the TPP do not request a delegated SCA approach. If the parameter is not used, the TPP do not request a delegated SCA approach. required: false type: boolean Signature: name: Signature in: header description: A signature of the request by the TPP on application level. This might be mandated by ASPSP. required: true type: string default: "" Digest: name: Digest type: string required: false in: header description: Hash of the message body. Should be present when Request body exists default: "" TPP-Certificate: name: TPP-Certificate in: header description: The certificate used for signing the request, in base64 encoding. Shall be contained if the signature is used. required: true type: string default: "" Delegation-ID: name: Delegation-ID in: header description: An identification provided by the ASPSP for the later identification of the authentication delegated. required: false type: string default: "" Accept: name: Accept in: header description: | The TPP can indicate the formats of account reports supported together with a priorisation following the http header definition. The formats supported by this specification are - xml - JSON - text Further definition of content by ASPSP/ communities cp. Annex B. required: false type: string default: JSON Date: name: Date in: header description: Request date required: true type: string format: date-time PaymentRequest: name: paymentRequest in: body description: Payment Initiation Request required: true schema: $ref: '#/definitions/PaymentRequestResource' PaymentUpdateRequest: name: consentUpdateRequest in: body description: Account Consent Request Update required: false schema: $ref: '#/definitions/PaymentUpdateRequestResource' x-ibm-configuration: enforced: true testable: true phase: realized securityDefinitions: x-ibm-client-id: type: apiKey description: "" in: header name: X-IBM-Client-Id security: - x-ibm-client-id: [] basePath: / x-ibm-endpoints: - endpointUrl: https://site2.sibsapimarket.com:8445/sibs/apimarket-sb type: - production - development - endpointUrl: https://site1.sibsapimarket.com:8445/sibs/apimarket-sb type: - production - development ...