TietoEVRY Bulk Payment Initiation Service API

openapi: 3.2.0
info:
  title: Tieto OpenBanking XS2A apis - Bulk payment service Bulk…
  version: 1.3.4
  description: Operations for bulk payments.
servers:
- url: http://openbanking.api.tieto.com
- url: https://openbanking.api.tieto.com
tags:
- name: Bulk Payment Initiation Service
  description: Operations for bulk payments.
paths:
  /{sandbox|live}/xs2a/v1.3/bulk-payments/{payment-product}/{payment-id}:
    get:
      tags:
      - Bulk Payment Initiation Service
      operationId: getJSONBulkPayment
      description: Returns the content of nulk payment object.
      summary: Get Bulk Payment Details
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
          - target-2-payments
          - cross-border-credit-transfers
      - name: payment-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Request-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in Sandbox.
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetBulkPaymentResponse'
  /{sandbox|live}/xs2a/v1.3/bulk-payments/{payment-product}/{payment-id}/authorisations:
    get:
      tags:
      - Bulk Payment Initiation Service
      summary: 'Bulk Payment: Get authorisation sub-resources request'
      description: Will deliver an array of resource identifications of all generated authorisation sub-resources.
      operationId: bulkPaymentsGetAuthorizations
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
          - target-2-payments
          - cross-border-credit-transfers
      - name: payment-id
        in: path
        description: Identification of the related resource
        required: true
        schema:
          type: string
          format: uuid
      - 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
          format: uuid
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in Sandbox.
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returns array of authorisation sub-resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetAuthorisationsResponse'
    post:
      tags:
      - Bulk Payment Initiation Service
      summary: 'Bulk Payment: Start authorisation process'
      description: Starts the authorisation process for a bulk payment initiation.
      operationId: bulkPaymentsStartAuthorization
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
          - target-2-payments
          - cross-border-credit-transfers
      - name: payment-id
        in: path
        description: Identification of the related resource
        required: true
        schema:
          type: string
          format: uuid
      - 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
          format: uuid
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in Sandbox.
        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. Mandated for the Redirect SCA Approach (including OAuth2 SCA approach).
        required: true
        schema:
          type: string
          format: uri
      - name: TPP-Nok-Redirect-URI
        in: header
        description: If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the TPP-Redirect-URI in case of a negative result of the redirect SCA method.
        schema:
          type: string
          format: uri
      responses:
        201:
          description: Created authorisation sub-resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonPostAuthorisationsResponse'
  /{sandbox|live}/xs2a/v1.3/bulk-payments/{payment-product}/{payment-id}/authorisations/{authorisation-id}:
    get:
      tags:
      - Bulk Payment Initiation Service
      summary: 'Bulk Payment: Get SCA status request'
      description: Checks the SCA status of a authorisation sub-resource.
      operationId: bulkPaymentsGetAuthorizationStatus
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: payment-id
        in: path
        description: Identification of the related resource
        required: true
        schema:
          type: string
          format: uuid
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
          - target-2-payments
          - cross-border-credit-transfers
      - 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
          format: uuid
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in Sandbox.
        required: true
        schema:
          type: string
      - name: authorisation-id
        in: path
        description: Identification of the related authorisation sub-resource
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returns array of authorisation sub-resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetAuthorisationStatusResponse'
  /{sandbox|live}/xs2a/v1.3/bulk-payments/{payment-product}/{payment-id}/status:
    get:
      tags:
      - Bulk Payment Initiation Service
      summary: 'Bulk Payment: Get Status Request'
      description: Can check the status of a bulk payment initiation.
      operationId: getJSONBulkPaymentStatus
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: payment-id
        in: path
        description: Resource Identification of the related payment.
        required: true
        schema:
          type: string
          format: uuid
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
          - target-2-payments
          - cross-border-credit-transfers
      - name: X-Request-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in Sandbox.
        required: true
        schema:
          type: string
      responses:
        200:
          description: No errors ocurred. Returns payment's transactionStatus
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetPaymentStatusResponse'
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        404:
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
  /{sandbox|live}/xs2a/v1.3/bulk-payments/{payment-product}:
    post:
      tags:
      - Bulk Payment Initiation Service
      summary: Bulk Payment Initiation with JSON encoding of the Payment Instruction
      description: Creates a bulk payment initiation request at the ASPSP.
      operationId: initiateJSONBulkPayment
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
          - target-2-payments
          - cross-border-credit-transfers
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        required: true
        schema:
          type: string
          format: uuid
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in Sandbox.
        required: true
        schema:
          type: string
      - name: TPP-Explicit-Authorisation-Preferred
        in: header
        description: If it equals "true", the TPP prefers to start the authorisation process separately, e.g. because of the usage of a signing basket. If it equals "false" or if the parameter is not used, there is no preference of the TPP. This especially indicates that the TPP assumes a direct authorisation of the transaction in the next step, without using a signing basket.
        schema:
          type: boolean
          default: false
      - name: TPP-Redirect-URI
        in: header
        description: URI of the TPP, where the transaction flow shall be redirected to after a Redirect. Mandated for the Redirect SCA Approach (including OAuth2 SCA approach).
        required: true
        schema:
          type: string
          format: uri
      - name: TPP-Nok-Redirect-URI
        in: header
        description: If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the TPP-Redirect-URI in case of a negative result of the redirect SCA method.
        schema:
          type: string
          format: uri
      - 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
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonPostPaymentResponse'
        201:
          description: No errors occurred. In _links section redirect and self links are used.
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format, creditor address is missing when payment product is cross-border-credit-transfers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        404:
          description: invalid payment product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonPostBulkPaymentRequest'
        required: true
components:
  schemas:
    JsonPostAuthorisationsResponse:
      type: object
      properties:
        psuMessage:
          type: string
        tppMessages:
          type: array
          items:
            $ref: '#/components/schemas/JsonMessage'
        scaStatus:
          type: string
        _links:
          readOnly: true
          $ref: '#/components/schemas/JsonLinks'
    JsonAddress:
      type: object
      required:
      - country
      properties:
        street:
          type: string
        buildingNumber:
          type: string
        city:
          type: string
        postalCode:
          type: string
        country:
          type: string
    JsonPostBulkPaymentRequest:
      type: object
      required:
      - debtorAccount
      - payments
      properties:
        debtorAccount:
          $ref: '#/components/schemas/JsonAccountReference'
        batchBookingPreferred:
          type: boolean
          default: false
          description: If this element equals true, the PSU prefers only one booking entry. If this element equals false, the PSU prefers individual booking of all contained individual transactions.
        payments:
          type: array
          items:
            type: object
            required:
            - creditorAddress
            - creditorAccount
            - creditorName
            - instructedAmount
            properties:
              instructedAmount:
                $ref: '#/components/schemas/JsonAmount'
              creditorName:
                type: string
              creditorAddress:
                $ref: '#/components/schemas/JsonAddress'
              creditorAccount:
                $ref: '#/components/schemas/JsonAccountReference'
              remittanceInformationUnstructured:
                type: string
    JsonPostPaymentResponse:
      type: object
      required:
      - paymentId
      - transactionStatus
      properties:
        psuMessage:
          type: string
        tppMessages:
          type: array
          items:
            $ref: '#/components/schemas/JsonMessage'
        paymentId:
          type: string
          format: uuid
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
        transactionFeeIndicator:
          type: boolean
        transactionFees:
          $ref: '#/components/schemas/JsonAmount'
        _links:
          readOnly: true
          $ref: '#/components/schemas/JsonLinks'
    TransactionStatus:
      type: string
      enum:
      - ACCC
      - ACCP
      - ACSC
      - ACSP
      - ACTC
      - ACWC
      - ACWP
      - RCVD
      - PDNG
      - RJCT
      - CANC
      - ACFC
      - PATC
      - PART
    JsonLinks:
      type: object
      properties:
        scaRedirect:
          $ref: '#/components/schemas/JsonHref'
        scaOAuth:
          $ref: '#/components/schemas/JsonHref'
        self:
          $ref: '#/components/schemas/JsonHref'
        status:
          $ref: '#/components/schemas/JsonHref'
        account:
          $ref: '#/components/schemas/JsonHref'
        balances:
          $ref: '#/components/schemas/JsonHref'
        transactions:
          $ref: '#/components/schemas/JsonHref'
        transactionDetails:
          $ref: '#/components/schemas/JsonHref'
        first:
          $ref: '#/components/schemas/JsonHref'
        next:
          $ref: '#/components/schemas/JsonHref'
        previous:
          $ref: '#/components/schemas/JsonHref'
        last:
          $ref: '#/components/schemas/JsonHref'
        download:
          $ref: '#/components/schemas/JsonHref'
        updatePsuIdentification:
          $ref: '#/components/schemas/JsonHref'
        startAuthorisation:
          $ref: '#/components/schemas/JsonHref'
        scaStatus:
          $ref: '#/components/schemas/JsonHref'
    JsonGetAuthorisationStatusResponse:
      type: object
      properties:
        scaStatus:
          $ref: '#/components/schemas/ScaStatus'
        authorisationId:
          type: string
        _links:
          readOnly: true
          $ref: '#/components/schemas/JsonLinks'
    JsonGetPaymentStatusResponse:
      type: object
      required:
      - transactionStatus
      properties:
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
    JsonMessage:
      type: object
      required:
      - category
      - code
      properties:
        category:
          type: string
        code:
          type: string
        path:
          type: string
        text:
          type: string
    ScaStatus:
      type: string
      enum:
      - received
      - psuIdentified
      - psuAuthenticated
      - scaMethodSelected
      - started
      - finalised
      - failed
      - exempted
    JsonGetAuthorisationsResponse:
      type: object
      properties:
        authorisationsIds:
          type: array
          items:
            type: string
    JsonGetBulkPaymentResponse:
      type: object
      required:
      - debtorAccount
      - payments
      properties:
        debtorAccount:
          $ref: '#/components/schemas/JsonAccountReference'
        payments:
          type: array
          items:
            type: object
            required:
            - creditorAddress
            - creditorAccount
            - creditorName
            - instructedAmount
            properties:
              instructedAmount:
                $ref: '#/components/schemas/JsonAmount'
              creditorName:
                type: string
              creditorAddress:
                $ref: '#/components/schemas/JsonAddress'
              creditorAccount:
                $ref: '#/components/schemas/JsonAccountReference'
              remittanceInformationUnstructured:
                type: string
        transactionStatus:
          type: string
        _links:
          readOnly: true
          $ref: '#/components/schemas/JsonLinks'
    JsonErrorResponse:
      type: object
      required:
      - transactionStatus
      properties:
        psuMessage:
          type: string
        tppMessages:
          type: array
          items:
            $ref: '#/components/schemas/JsonMessage'
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
    JsonAccountReference:
      type: object
      required:
      - currency
      properties:
        iban:
          type: string
        bban:
          type: string
        pan:
          type: string
        maskedPan:
          type: string
        msisdn:
          type: string
        currency:
          type: string
      description: Must contain one of iban,bban,maskedPan,msisdn or pan field
    JsonHref:
      type: object
      properties:
        href:
          type: string
    JsonAmount:
      type: object
      required:
      - amount
      - currency
      properties:
        currency:
          type: string
        amount:
          type: string
  parameters:
    envParam:
      name: sandbox|live
      in: path
      description: The addressed environment
      required: true
      schema:
        type: string
        enum:
        - sandbox
        - live