---
swagger: "2.0"
info:
  title: "Tieto OpenBanking XS2A apis - Payment Initiation Service"
  version: "1.2"
host: "openbanking.api.tieto.com"
tags:
- name: "Payment Initiation Service"
  description: "Operations for payments."
schemes:
- "http"
- "https"
parameters:
  envParam:
    name: "sandbox|live"
    in: "path"
    description: "The addressed environment"
    required: true
    type: "string"
    enum:
    - "sandbox"
    - "live"
paths:
  /{sandbox|live}/xs2a/v1.2/payments/{payment-id}:
    get:
      tags:
      - "Payment Initiation Service"
      operationId: "getJSONPayment"
      description: "Returns the content of payment object."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      summary: "Get Payment Details"
      parameters:
      - $ref: "#/parameters/envParam"
      - name: "payment-id"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
      - name: "X-Request-ID"
        in: "header"
        required: true
        description: "ID of the request, unique to the call, as determined by the\
          \ initiating party."
        type: "string"
        format: "uuid"
      - name: "X-API-Key"
        in: "header"
        description: "Authorisation key that can be acquired in Sandbox."
        required: true
        type: "string"
      - name: "PSU-ID"
        in: "header"
        description: "Client ID of the PSU in the bank."
        required: false
        type: "string"
      - name: "PSU-Corporate-ID"
        in: "header"
        description: "Corporate client ID of the PSU in the bank."
        required: false
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/JsonGetPaymentResponse"
  /{sandbox|live}/xs2a/v1.2/payments/{payment-id}/authorisations:
    get:
      tags:
      - "Payment Initiation Service"
      summary: "Payment: Get authorisation sub-resources request"
      description: "Will deliver an array of resource identifications of all generated\
        \ authorisation sub-resources."
      operationId: "paymentsGetAuthorizations"
      produces:
      - "application/json"
      parameters:
      - $ref: "#/parameters/envParam"
      - name: "payment-id"
        in: "path"
        description: "Identification of the related resource"
        required: true
        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
        type: "string"
        format: "uuid"
      - name: "X-API-Key"
        in: "header"
        description: "Authorisation key that can be acquired in Sandbox."
        required: true
        type: "string"
      - name: "PSU-ID"
        in: "header"
        description: "Client ID of the PSU in the bank."
        required: false
        type: "string"
      - name: "PSU-Corporate-ID"
        in: "header"
        description: "Corporate client ID of the PSU in the bank."
        required: false
        type: "string"
      responses:
        200:
          description: "Returns array of authorisation sub-resources."
          schema:
            $ref: "#/definitions/JsonGetAuthorisationsResponse"
    post:
      tags:
      - "Payment Initiation Service"
      summary: "Payment: Start authorisation process"
      description: "Starts the authorisation process for a payment initiation."
      operationId: "paymentsStartAuthorization"
      produces:
      - "application/json"
      parameters:
      - $ref: "#/parameters/envParam"
      - name: "payment-id"
        in: "path"
        description: "Identification of the related resource"
        required: true
        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
        type: "string"
        format: "uuid"
      - name: "X-API-Key"
        in: "header"
        description: "Authorisation key that can be acquired in Sandbox."
        required: true
        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."
        type: "boolean"
        default: false
      - 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: false
        type: "string"
      - name: "PSU-ID"
        in: "header"
        description: "Client ID of the PSU in the bank."
        required: false
        type: "string"
      - name: "PSU-Corporate-ID"
        in: "header"
        description: "Corporate client ID of the PSU in the bank."
        required: false
        type: "string"
      responses:
        201:
          description: "Created authorisation sub-resource."
          schema:
            $ref: "#/definitions/JsonPostAuthorisationsResponse"
  /{sandbox|live}/xs2a/v1.2/payments/{payment-id}/authorisations/{authorisation-id}:
    get:
      tags:
      - "Payment Initiation Service"
      summary: "Payment: Get SCA status request"
      description: "Checks the SCA status of a authorisation sub-resource."
      operationId: "paymentsGetAuthorizationStatus"
      produces:
      - "application/json"
      parameters:
      - $ref: "#/parameters/envParam"
      - name: "payment-id"
        in: "path"
        description: "Identification of the related resource"
        required: true
        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
        type: "string"
        format: "uuid"
      - name: "X-API-Key"
        in: "header"
        description: "Authorisation key that can be acquired in Sandbox."
        required: true
        type: "string"
      - name: "authorisation-id"
        in: "path"
        description: "Identification of the related authorisation sub-resource"
        required: true
        type: "string"
      - name: "PSU-ID"
        in: "header"
        description: "Client ID of the PSU in the bank."
        required: false
        type: "string"
      - name: "PSU-Corporate-ID"
        in: "header"
        description: "Corporate client ID of the PSU in the bank."
        required: false
        type: "string"
      responses:
        200:
          description: "Returns array of authorisation sub-resources."
          schema:
            $ref: "#/definitions/JsonGetAuthorisationStatusResponse"
  /{sandbox|live}/xs2a/v1.2/payments/{payment-id}/status:
    get:
      tags:
      - "Payment Initiation Service"
      summary: "Payment: Get Status Request"
      description: "Can check the status of a payment initiation."
      operationId: "getJSONPaymentStatus"
      produces:
      - "application/json"
      parameters:
      - $ref: "#/parameters/envParam"
      - name: "payment-id"
        in: "path"
        description: "Resource Identification of the related payment."
        required: true
        type: "string"
        format: "uuid"
      - name: "Accept"
        in: "header"
        required: true
        type: "string"
        enum:
        - "application/json"
      - name: "X-Request-ID"
        in: "header"
        required: true
        description: "ID of the request, unique to the call, as determined by the\
          \ initiating party."
        type: "string"
        format: "uuid"
      - name: "X-API-Key"
        in: "header"
        description: "Authorisation key that can be acquired in Sandbox."
        required: true
        type: "string"
      - name: "PSU-ID"
        in: "header"
        description: "Client ID of the PSU in the bank."
        required: false
        type: "string"
      - name: "PSU-Corporate-ID"
        in: "header"
        description: "Corporate client ID of the PSU in the bank."
        required: false
        type: "string"
      responses:
        200:
          description: "No errors ocurred. Returns payment's transactionStatus"
          schema:
            $ref: "#/definitions/JsonGetPaymentStatusResponse"
        400:
          description: "One of mandatory parameters(headers, request body or query\
            \ parameters) missing or in incorrect format"
          schema:
            $ref: "#/definitions/JsonErrorResponse"
        404:
          description: "Payment not found"
          schema:
            $ref: "#/definitions/JsonErrorResponse"
  /{sandbox|live}/xs2a/v1.2/payments/{payment-product}:
    post:
      tags:
      - "Payment Initiation Service"
      summary: "Payment Initiation with JSON encoding of the Payment Instruction"
      description: "Creates a payment initiation request at the ASPSP."
      operationId: "initiateJSONPayment"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - $ref: "#/parameters/envParam"
      - in: "body"
        name: "body"
        required: true
        schema:
          $ref: "#/definitions/JsonPostPaymentRequest"
      - name: "payment-product"
        in: "path"
        required: true
        type: "string"
        enum:
        - "sepa-credit-transfers"
        - "instant-sepa-credit-transfers"
        - "target-2-payments"
        - "cross-border-credit-transfers"
      - name: "Content-Type"
        in: "header"
        required: true
        type: "string"
      - name: "X-Request-ID"
        in: "header"
        required: true
        description: "ID of the request, unique to the call, as determined by the\
          \ initiating party."
        type: "string"
        format: "uuid"
      - name: "X-API-Key"
        in: "header"
        description: "Authorisation key that can be acquired in Sandbox."
        required: true
        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."
        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)."
        type: "string"
        format: "uri"
        required: true
      - 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."
        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: false
        type: "string"
      - name: "PSU-ID"
        in: "header"
        description: "Client ID of the PSU in the bank."
        required: false
        type: "string"
      - name: "PSU-Corporate-ID"
        in: "header"
        description: "Corporate client ID of the PSU in the bank."
        required: false
        type: "string"
      responses:
        201:
          description: "No errors occurred. In _links section redirect and self links\
            \ are used."
          schema:
            $ref: "#/definitions/JsonPostPaymentResponse"
        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"
          schema:
            $ref: "#/definitions/JsonErrorResponse"
        404:
          description: "invalid payment product"
          schema:
            $ref: "#/definitions/JsonErrorResponse"
definitions:
  JsonErrorResponse:
    type: "object"
    required:
    - "transactionStatus"
    properties:
      psuMessage:
        type: "string"
      tppMessages:
        type: "array"
        items:
          $ref: "#/definitions/JsonMessage"
      transactionStatus:
        type: "string"
        enum:
        - "AcceptedCustomerProfile"
        - "AcceptedSettlementCompleted"
        - "AcceptedSettlementInProcess"
        - "AcceptedTechnicalValidation"
        - "AcceptedWithChange"
        - "AcceptedWithoutPosting"
        - "Received"
        - "Pending"
        - "Rejected"
  JsonGetAuthorisationStatusResponse:
    type: "object"
    properties:
      scaStatus:
        type: "string"
  JsonGetAuthorisationsResponse:
    type: "object"
    properties:
      authorisationsIds:
        type: "array"
        items:
          type: "string"
  JsonGetPaymentResponse:
    type: "object"
    required:
    - "creditorAddress"
    - "creditorAccount"
    - "creditorName"
    - "debtorAccount"
    - "instructedAmount"
    properties:
      endToEndIdentification:
        type: "string"
      debtorAccount:
        $ref: "#/definitions/JsonAccountReference"
      instructedAmount:
        $ref: "#/definitions/JsonAmount"
      creditorName:
        type: "string"
      creditorAddress:
        $ref: "#/definitions/JsonAddress"
      creditorAccount:
        $ref: "#/definitions/JsonAccountReference"
      remittanceInformationUnstructured:
        type: "string"
      transactionStatus:
        type: "string"
      _links:
        readOnly: true
        $ref: "#/definitions/JsonLinks"
      requestedExecutionDate:
        type: "string"
        description: "This parameter is indicates that this is future dated payment\
          \ that will execute at this date. The content is date in ISODate Format,\
          \ e.g. 2017-10-30."
      remittanceInformationStructured:
        type: "object"
        required:
        - "reference"
        properties:
          reference:
            type: "string"
          referenceType:
            type: "string"
          referenceIssuer:
            type: "string"
  JsonGetPaymentStatusResponse:
    type: "object"
    required:
    - "transactionStatus"
    properties:
      transactionStatus:
        type: "string"
        enum:
        - "AcceptedCustomerProfile"
        - "AcceptedSettlementCompleted"
        - "AcceptedSettlementInProcess"
        - "AcceptedTechnicalValidation"
        - "AcceptedWithChange"
        - "AcceptedWithoutPosting"
        - "Received"
        - "Pending"
        - "Rejected"
  JsonPostAuthorisationsResponse:
    type: "object"
    properties:
      psuMessage:
        type: "string"
      tppMessages:
        type: "array"
        items:
          $ref: "#/definitions/JsonMessage"
      scaStatus:
        type: "string"
      _links:
        readOnly: true
        $ref: "#/definitions/JsonLinks"
  JsonPostPaymentRequest:
    type: "object"
    required:
    - "creditorAddress"
    - "creditorAccount"
    - "creditorName"
    - "debtorAccount"
    - "instructedAmount"
    properties:
      endToEndIdentification:
        type: "string"
      debtorAccount:
        $ref: "#/definitions/JsonAccountReference"
      instructedAmount:
        $ref: "#/definitions/JsonAmount"
      creditorName:
        type: "string"
      creditorAddress:
        $ref: "#/definitions/JsonAddress"
      creditorAccount:
        $ref: "#/definitions/JsonAccountReference"
      remittanceInformationUnstructured:
        type: "string"
      requestedExecutionDate:
        type: "string"
        description: "This parameter is indicates that this is future dated payment\
          \ that will execute at this date. The content is date in ISODate Format,\
          \ e.g. 2017-10-30."
      remittanceInformationStructured:
        type: "object"
        required:
        - "reference"
        properties:
          reference:
            type: "string"
          referenceType:
            type: "string"
          referenceIssuer:
            type: "string"
  JsonPostPaymentResponse:
    type: "object"
    required:
    - "paymentId"
    - "transactionStatus"
    properties:
      psuMessage:
        type: "string"
      tppMessages:
        type: "array"
        items:
          $ref: "#/definitions/JsonMessage"
      paymentId:
        type: "string"
        format: "uuid"
      transactionStatus:
        type: "string"
        enum:
        - "AcceptedCustomerProfile"
        - "AcceptedSettlementCompleted"
        - "AcceptedSettlementInProcess"
        - "AcceptedTechnicalValidation"
        - "AcceptedWithChange"
        - "AcceptedWithoutPosting"
        - "Received"
        - "Pending"
        - "Rejected"
      transactionFeeIndicator:
        type: "boolean"
      transactionFees:
        $ref: "#/definitions/JsonAmount"
      _links:
        readOnly: true
        $ref: "#/definitions/JsonLinks"
  JsonAccountReference:
    type: "object"
    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"
  JsonAddress:
    type: "object"
    required:
    - "country"
    properties:
      street:
        type: "string"
      buildingNumber:
        type: "string"
      city:
        type: "string"
      postalCode:
        type: "string"
      country:
        type: "string"
  JsonAmount:
    type: "object"
    required:
    - "amount"
    - "currency"
    properties:
      currency:
        type: "string"
      amount:
        type: "string"
  JsonHref:
    type: "object"
    properties:
      href:
        type: "string"
  JsonLinks:
    type: "object"
    properties:
      scaRedirect:
        $ref: "#/definitions/JsonHref"
      scaOAuth:
        $ref: "#/definitions/JsonHref"
      self:
        $ref: "#/definitions/JsonHref"
      status:
        $ref: "#/definitions/JsonHref"
      account:
        $ref: "#/definitions/JsonHref"
      balances:
        $ref: "#/definitions/JsonHref"
      transactions:
        $ref: "#/definitions/JsonHref"
      transactionDetails:
        $ref: "#/definitions/JsonHref"
      first:
        $ref: "#/definitions/JsonHref"
      next:
        $ref: "#/definitions/JsonHref"
      previous:
        $ref: "#/definitions/JsonHref"
      last:
        $ref: "#/definitions/JsonHref"
      download:
        $ref: "#/definitions/JsonHref"
      updatePsuIdentification:
        $ref: "#/definitions/JsonHref"
      startAuthorisation:
        $ref: "#/definitions/JsonHref"
      scaStatus:
        $ref: "#/definitions/JsonHref"
  JsonMessage:
    type: "object"
    required:
    - "category"
    - "code"
    properties:
      category:
        type: "string"
      code:
        type: "string"
      path:
        type: "string"
      text:
        type: "string"