openapi: 3.2.0
info:
  title: Triodos XS2A BG service Confirmation of Funds Service API
  description: Triodos XS2A BG service
  termsOfService: https://www.triodos.com
  contact:
    name: Triodos Support
    url: https://www.triodos.com
    email: info@triodos.com
  license:
    name: Creative Commons Attribution 4.0 International Public License
    url: https://creativecommons.org/licenses/by/4.0/
  version: '1.1'
servers:
- url: https://xs2a-sandbox.triodos.com/xs2a-bg
  description: Triodos XS2A Sandbox
tags:
- name: Confirmation of Funds Service
  description: This service may be used by a PIISP to request a confirmation of the availability of specific funds on the account of a PSU. The account is managed by the ASPSP providing the XS2A Interface. Functionality and restrictions of this service comply with the requirements defined by article 65 of PSD2.
  externalDocs:
    description: 'Berlin Group XS2A Implementation Version 1.3 - Chapter 9: Confirmation of Funds Service'
    url: https://docs.wixstatic.com/ugd/c2914b_bec5f9d0d3c94cfca2ad1b9da36dc752.pdf
paths:
  /{tenant}/v1/funds-confirmations:
    post:
      tags:
      - Confirmation of Funds Service
      summary: Confirmation of funds
      description: Creates a confirmation of funds request at the ASPSP.
      operationId: confirmFundsAvailable
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: Consent-ID
        in: header
        description: ID of registered and authorized consent.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Confirmation of funds request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Xs2aConfirmationOfFundsRequest'
        required: true
      responses:
        '200':
          description: Confirmation of funds returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aConfirmationOfFundsResponse'
        '400':
          description: Missing or invalid body (e.g. invalid IBAN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: User has no access to the given account/ given IBAN belongs to a savings account/ given currency does not correspond to currency of account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '404':
          description: IBAN not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v2/consents/confirmation-of-funds/{resource-id}/authorisations:
    get:
      tags:
      - Confirmation of Funds Service
      summary: Get authorisations
      description: Will deliver an array of resource ids of all generated authorisation sub-resources.
      operationId: getPiisAuthorisations
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Authorisations returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationsRequestResponse'
        '400':
          description: ConsentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: ConsentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    post:
      tags:
      - Confirmation of Funds Service
      summary: Create authorisation
      description: Creates a consent authorisation sub-resource.
      operationId: createPiisAuthorisation
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent to create authorisation sub-resource for.
        required: true
        schema:
          type: string
          format: uuid
      - name: TPP-Redirect-URI
        in: header
        description: URI of the TPP, where the transaction flow shall be redirected to after a Redirect.
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Consent authorisation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: ConsentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v2/consents/confirmation-of-funds/{resource-id}/authorisations/{authorisation-id}:
    get:
      tags:
      - Confirmation of Funds Service
      summary: Get authorisation status
      description: Checks the SCA status of an authorisation sub-resource.
      operationId: getPiisAuthorisationStatus
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent.
        required: true
        schema:
          type: string
          format: uuid
      - name: authorisation-id
        in: path
        description: ID of the authorisation sub-resource.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Authorisation status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationStatusRequestResponse'
        '400':
          description: AuthorisationID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: ConsentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    put:
      tags:
      - Confirmation of Funds Service
      summary: Update consent authorisation with access token
      description: Updates the confirmation of funds consent authorisation with an access token. If the access token has sufficient privileges, the consent will be authorized
      operationId: submitPiisAuthorisation
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent.
        required: true
        schema:
          type: string
          format: uuid
      - name: authorisation-id
        in: path
        description: ID of the authorisation sub-resource
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Consent authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: ConsentID is invalid/ consent status is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '401':
          description: Invalid scope/ Invalid consent/ Given access token is not coupled to the given consent/ User does not have access to all products requested for consent/ Authorization timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: ConsentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v2/consents/confirmation-of-funds/{resource-id}:
    get:
      tags:
      - Confirmation of Funds Service
      summary: Get consent
      description: Returns the content of a confirmation of funds consent object. This is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach.
      operationId: getPiisConsent
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Consent returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aConfirmationOfFundsConsentRequest'
        '400':
          description: ConsentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: ConsentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    delete:
      tags:
      - Confirmation of Funds Service
      summary: Delete consent
      description: Deletes a given consent.
      operationId: deletePiisConsent
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Consent deleted
        '400':
          description: ConsentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '401':
          description: Invalid scope/ Invalid consent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: ConsentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v2/consents/confirmation-of-funds/{resource-id}/status:
    get:
      tags:
      - Confirmation of Funds Service
      summary: Get consent status
      description: Check the status of a confirmation of funds consent resource.
      operationId: getPiisConsentStatus
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          type: string
      - name: resource-id
        in: path
        description: ID of the consent.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Consent status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aConsentStatusResponse'
        '400':
          description: ConsentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: ConsentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v2/consents/confirmation-of-funds:
    post:
      tags:
      - Confirmation of Funds Service
      summary: Register consent
      description: Creates a confirmation of funds consent resource at the ASPSP regarding access to accounts specified in this request.
      operationId: registerConsentRequest_1
      parameters:
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
      - name: tenant
        in: path
        description: Branch of the request.
        required: true
        schema:
          type: string
          enum:
          - uk
          - nl
          - be_fr
          - be_nl
      - name: Signature
        in: header
        description: A signature of the request by the TPP on application level.
        required: true
        schema:
          type: string
      - name: Digest
        in: header
        description: Digest contains a Hash of the message body, used for authentication of the request. The only hash algorithms that may be used to calculate the Digest within the context of this specification are SHA-256 and SHA-512.
        required: true
        schema:
          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.
        required: true
        schema:
          type: string
      - name: TPP-Redirect-URI
        in: header
        description: URI of the TPP, where the transaction flow shall be redirected to after a Redirect.
        required: true
        schema:
          type: string
      - name: TPP-Signature-Certificate
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: Consent request.
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/Xs2aConfirmationOfFundsConsentRequest'
        required: true
      responses:
        '201':
          description: Consent registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aConfirmationOfFundsConsentRequest'
        '400':
          description: Missing or invalid body (e.g. FrequencyPerDay > 4)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
components:
  schemas:
    Xs2aConfirmationOfFundsRequest:
      required:
      - account
      - instructedAmount
      type: object
      properties:
        instructedAmount:
          $ref: '#/components/schemas/Xs2aAmount'
        account:
          $ref: '#/components/schemas/Xs2aAccountReference'
        payee:
          type: string
          description: The merchant where the card is accepted as an information to the PSU.
        cardNumber:
          type: string
          description: Card Number of the card issued by the PIISP. Should be delivered if available.
    Xs2aAccountReference:
      type: object
      properties:
        iban:
          type: string
          description: The iban is used in the body of the Consent or Payment Request Message for retrieving account access consent or initiating a payment for this payment account, cp. Section 6.3. If an iban is provided then ukSortCode and ukAccountNumber should be left empty.
        foreignAccountNumber:
          type: string
          description: The foreignAccountNumber is used in the body of the cross-border-credit-transfers Payment Request Message for creditor account, If a foreignAccountNumber is provided then iban, ukSortCode and ukAccountNumber should be left empty.
        ukSortCode:
          type: string
          description: The ukSortCode and ukAccountNumber are used in the body of the Consent or Payment Request Message for retrieving account access consent or initiating a payment for this payment account, cp. Section 6.3. If ukSortCode and ukAccountNumber are provided then iban should be left empty.
        ukAccountNumber:
          type: string
        currency:
          type: string
          description: Account currency
      description: PSU's account number.
    Xs2aAuthorisationsRequestResponse:
      required:
      - authorisationIds
      type: object
      properties:
        authorisationIds:
          type: array
          description: List of authorisation request ids.
          items:
            type: string
            description: List of authorisation request ids.
            format: uuid
    Xs2aAuthorisationStatusRequestResponse:
      required:
      - scaStatus
      type: object
      properties:
        scaStatus:
          type: string
          description: Status of the authorisation request.
          enum:
          - received
          - psuIdentified
          - psuAuthenticated
          - scaMethodSelected
          - started
          - unconfirmed
          - finalised
          - failed
          - exempted
    TppMessages:
      type: object
      properties:
        tppMessages:
          type: array
          description: List of messages.
          items:
            $ref: '#/components/schemas/TppMessage'
    Xs2aAuthorisationRequestResponseLinks:
      type: object
      properties:
        scaOAuth:
          type: string
          description: A link to the OAuth2 configuration of the ASPSP's authorisation server.
        scaRedirect:
          type: string
          description: A link to the OAuth2 authorization resource.
        scaStatus:
          type: string
          description: A link to the authorisation sub-resource. In practice this is the same as the confirmation link.
        self:
          type: string
          description: The link to the resource created by the undergoing request. This link can be used to retrieve the resource data.
        confirmation:
          type: string
          description: The link to the authorisation sub-resource.
        status:
          type: string
          description: The link to retrieve the transaction status of a resource.
    Xs2aConsentStatusResponse:
      required:
      - consentStatus
      type: object
      properties:
        consentStatus:
          type: string
          description: This is the overall lifecycle status of the consent.
          enum:
          - received
          - valid
          - rejected
          - expired
          - terminatedByTpp
          - revokedByPsu
    Xs2aConfirmationOfFundsResponse:
      type: object
      properties:
        fundsAvailable:
          type: boolean
          description: Equals "true" if sufficient funds are available at the time of the request, "false" otherwise.
    Xs2aConfirmationOfFundsConsentRequest:
      required:
      - account
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Xs2aAccountReference'
        cardNumber:
          type: string
          description: Card Number of the card issued by the PIISP. Should be delivered if available.
        cardExpiryDate:
          type: string
          description: Expiry date of the card issued by the PIISP
          format: date
        cardInformation:
          type: string
          description: Additional explanation for the card product.
        registrationInformation:
          type: string
          description: Additional information about the registration process for the PSU, e.g. a reference to the TPP / PSU contract
    TppMessage:
      type: object
      properties:
        text:
          type: string
          description: Additional explaining text.
        code:
          type: string
          description: Message code.
          enum:
          - CERTIFICATE_INVALID
          - CERTIFICATE_EXPIRED
          - CERTIFICATE_BLOCKED
          - CERTIFICATE_REVOKED
          - CERTIFICATE_MISSING
          - SIGNATURE_INVALID
          - SIGNATURE_MISSING
          - ROLE_INVALID
          - FORMAT_ERROR
          - PARAMETER_NOT_CONSISTENT
          - PARAMETER_NOT_SUPPORTED
          - PSU_CREDENTIALS_INVALID
          - SERVICE_INVALID
          - SERVICE_BLOCKED
          - CORPORATE_ID_INVALID
          - CONSENT_UNKNOWN
          - CONSENT_INVALID
          - CONSENT_EXPIRED
          - TOKEN_UNKNOWN
          - TOKEN_INVALID
          - TOKEN_EXPIRED
          - RESOURCE_UNKNOWN
          - RESOURCE_EXPIRED
          - RESOURCE_BLOCKED
          - TIMESTAMP_INVALID
          - PERIOD_INVALID
          - SCA_METHOD_UNKNOWN
          - SCA_INVALID
          - STATUS_INVALID
          - PRODUCT_INVALID
          - PRODUCT_UNKNOWN
          - PAYMENT_FAILED
          - REQUIRED_KID_MISSING
          - EXECUTION_DATE_INVALID
          - CANCELLATION_INVALID
          - BENEFICIARY_WHITELISTING_REQUIRED
          - FUNDS_NOT_AVAILABLE
          - CONTENT_INVALID
          - SESSIONS_NOT_SUPPORTED
          - ACCESS_EXCEEDED
          - REQUESTED_FORMATS_INVALID
          - CARD_INVALID
          - NO_PIIS_ACTIVATION
          - REFERENCE_MIX_INVALID
          - REFERENCE_STATUS_INVALID
        category:
          type: string
      description: List of messages.
    Xs2aAmount:
      required:
      - amount
      - currency
      type: object
      properties:
        currency:
          type: string
          description: ISO 4217 Alpha 3 currency code
        amount:
          type: number
          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.
          format: double
      description: The amount of the transaction as billed to the account.
    Xs2aAuthorisationRequestResponse:
      type: object
      properties:
        scaStatus:
          type: string
          description: This data element is containing information about the status of the SCA method applied.
          enum:
          - received
          - psuIdentified
          - psuAuthenticated
          - scaMethodSelected
          - started
          - unconfirmed
          - finalised
          - failed
          - exempted
        psuMessage:
          type: string
          description: Text to be displayed to the PSU.
        authorisationId:
          type: string
          description: Resource identification of the authorisation sub-resource.
        _links:
          $ref: '#/components/schemas/Xs2aAuthorisationRequestResponseLinks'
externalDocs:
  description: Berlin Group XS2A Implementation Version 1.3
  url: https://docs.wixstatic.com/ugd/c2914b_bec5f9d0d3c94cfca2ad1b9da36dc752.pdf