Triodos Bank UK Payment Initiation Service API

openapi: 3.2.0
info:
  title: Triodos XS2A BG service Payment Initiation 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: Payment Initiation Service
  description: This service may be used by a PISP to initiate a single payment on behalf of a PSU using a given account of that 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 66 of PSD2.
  externalDocs:
    description: 'Berlin Group XS2A Implementation Version 1.3 - Chapter 5: Payment Initiation Service'
    url: https://docs.wixstatic.com/ugd/c2914b_bec5f9d0d3c94cfca2ad1b9da36dc752.pdf
paths:
  /{tenant}/v1/bulk-payments/sepa-credit-transfers/{resource-id}/authorisations:
    get:
      tags:
      - Payment Initiation Service
      summary: Get authorisations
      description: Will deliver an array of resource ids of all generated authorisation sub-resources.
      operationId: getAuthorisations
      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 payment.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Authorisations returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationsRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    post:
      tags:
      - Payment Initiation Service
      summary: Create authorisation
      description: Creates a payment authorisation sub-resource.
      operationId: createAuthorisation
      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 payment 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: Payment authorisation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/bulk-payments/sepa-credit-transfers/{resource-id}/authorisations/{authorisation-id}:
    get:
      tags:
      - Payment Initiation Service
      summary: Get authorisation status
      description: Checks the SCA status of an authorisation sub-resource.
      operationId: getAuthorisation
      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 payment.
        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: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    put:
      tags:
      - Payment Initiation Service
      summary: Submit payment authorisation
      description: Submits an access token to authorise a payment initiation.
      operationId: submitAuthorisation
      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 payment
        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
      - name: Authorization
        in: header
        description: OAuth2 access token.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payment SCA status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: AuthorisationID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/bulk-payments/sepa-credit-transfers/{resource-id}/cancellation-authorisations:
    get:
      tags:
      - Payment Initiation Service
      summary: Get cancellation authorisations
      description: Will deliver an array of resource ids of all generated cancellation authorisation sub-resources.
      operationId: getCancellationAuthorisations
      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 payment to get cancellation authorisations for.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Cancellation authorisations returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationsRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    post:
      tags:
      - Payment Initiation Service
      summary: Create cancellation authorisation
      description: Creates a payment cancellation authorisation sub-resource.
      operationId: createCancellationAuthorisation
      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 payment to create cancellation 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: Payment cancellation authorisation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/bulk-payments/sepa-credit-transfers/{resource-id}/cancellation-authorisations/{authorisation-id}:
    get:
      tags:
      - Payment Initiation Service
      summary: Get cancellation authorisation status
      description: Checks the SCA status of a cancellation authorisation sub-resource.
      operationId: getCancellationAuthorisation
      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 payment.
        required: true
        schema:
          type: string
          format: uuid
      - name: authorisation-id
        in: path
        description: ID of the cancellation authorisation sub-resource.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Cancellation 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: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    put:
      tags:
      - Payment Initiation Service
      summary: Update payment cancellation authorisation with access token
      description: Updates the payment cancellation data on the server by PSU data, if requested by the ASPSP. Also cancels the payment if sufficient privileges are present.
      operationId: submitCancellationAuthorisation
      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 payment to cancel
        required: true
        schema:
          type: string
          format: uuid
      - name: authorisation-id
        in: path
        description: ID of the cancellation authorisation sub-resource
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Payment submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: PaymentID is invalid/ Payment status is invalid/ Payment failed
          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 has insufficient rights to authorize the payment/ Authorization timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP/ Given currency is not supported for given payment product/ Given IBAN belongs to product with unsupported producttype/ Given IBAN belongs to product that is blocked or inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/bulk-payments/sepa-credit-transfers/{resource-id}:
    delete:
      tags:
      - Payment Initiation Service
      summary: Cancel payment
      description: If the payment is not authorized yet, the payment request is directly cancelled. Otherwise a cancellation authorization sub-resource is created.
      operationId: deletePayment
      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: resource-id
        in: path
        description: ID of the payment.
        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:
        '200':
          description: Payment cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aPaymentRequestResponse'
        '202':
          description: Cancellation authorization sub-resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aPaymentRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/bulk-payments/sepa-credit-transfers/{resource-id}/status:
    get:
      tags:
      - Payment Initiation Service
      summary: Get payment status
      description: Can check the status of a payment initiation.
      operationId: getStatus
      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 payment.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Payment status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aStatusRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/bulk-payments/sepa-credit-transfers:
    post:
      tags:
      - Payment Initiation Service
      summary: Initiate Sepa Bulk Payment
      description: Creates a Sepa bulk payment initiation request and corresponding authorisation sub-resource.
      operationId: initiateSepaBulkPayment
      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: Consent-ID
        in: header
        description: Must be empty, sessions are not supported.
        schema:
          type: string
      - name: TPP-Signature-Certificate
        in: header
        description: The certificate used for signing the request, in base64 encoding.
        required: true
        schema:
          type: string
      requestBody:
        description: PAIN.001.001.03 or PAIN.001.001.09 formatted bulk payment request.
        content:
          text/xml:
            schema:
              type: string
          application/xml:
            schema:
              type: string
        required: true
      responses:
        '201':
          description: Payment initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aPaymentRequestResponse'
        '400':
          description: Missing or invalid body (e.g. invalid IBAN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: The addressed payment product is not available for the PSU
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '404':
          description: No product found for given IBAN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/payments/cross-border-credit-transfers/{resource-id}/authorisations:
    get:
      tags:
      - Payment Initiation Service
      summary: Get authorisations
      description: Will deliver an array of resource ids of all generated authorisation sub-resources.
      operationId: getAuthorisations_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: resource-id
        in: path
        description: ID of the payment.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Authorisations returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationsRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
        '403':
          description: PaymentID not found, or not registered for this TPP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
    post:
      tags:
      - Payment Initiation Service
      summary: Create authorisation
      description: Creates a payment authorisation sub-resource.
      operationId: createAuthorisation_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: resource-id
        in: path
        description: ID of the payment 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: Payment authorisation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Xs2aAuthorisationRequestResponse'
        '400':
          description: PaymentID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TppMessages'
  /{tenant}/v1/payments/cross-border-credit-transfers/{resource-id}/authorisations/{authorisation-id}:
    get:
      tags:
      - Payment Initiation Service
      summary: Get authorisation status
      description: Checks the SCA status of an authorisation sub-resource.
      operationId: getAuthorisation_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: resource-id
        in: path
        description: ID of the payment.
        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:
            appli

# --- truncated at 32 KB (158 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/triodos-bank-uk/refs/heads/main/openapi/triodos-bank-uk-payment-initiation-service-api-openapi.yml