---
openapi: "3.0.1"
info:
  title: "Premium - Recall payments"
  version: "1.3.4"
servers:
- url: "https://openbanking.api.tieto.com/sandbox"
- url: "https://openbanking.api.tieto.com/live"
tags:
- name: "Payment Recall Initiation Service"
  description: "Operations for recalling the payments."
paths:
  /xs2a-premium/v1.3/recall-payments/{payment-product}/{payment-id}:
    get:
      tags:
      - "Payment Recall Initiation Service"
      summary: "Recall Payments: Get Payments recall details"
      description: "Returns the content for Payment recalls."
      operationId: "getJSONPaymentRecall"
      parameters:
      - 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: "Resource Identification of the related payment."
        required: true
        schema:
          type: "string"
          format: "uuid"
      - name: "X-Request-ID"
        in: "header"
        required: true
        schema:
          type: "string"
          format: "uuid"
      responses:
        200:
          description: "No errors occurred. Returns consent. link is used."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonGetPaymentRecallResponse"
        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: "Consent not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
  /xs2a-premium/v1.3/recall-payments/{payment-product}/{payment-id}/authorisations:
    get:
      tags:
      - "Payment Recall Initiation Service"
      summary: "Recall payments: Get authorisation sub-resources request"
      description: "Will deliver an array of resource identifications of all generated\
        \ authorisation sub-resources."
      operationId: "recallpaymentsGetAuthorizations"
      parameters:
      - 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: "Resource Identification of the related payment recall."
        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"
      responses:
        200:
          description: "Returns array of authorisation sub-resources."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonGetAuthorisationsResponse"
        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: "Consent not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
    post:
      tags:
      - "Payment Recall Initiation Service"
      summary: "Recall payments: Start authorisation process"
      description: "Starts the authorisation process for a payment initiation."
      operationId: "PaymentRecallStartAuthorization"
      parameters:
      - 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: "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."
        schema:
          type: "string"
      responses:
        201:
          description: "Created authorisation sub-resource."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonPostAuthorisationsResponse"
        400:
          description: "One of mandatory parameters(headers, request body or query\
            \ parameters) missing or in incorrect format; No matching subResourceService\
            \ for the requested SCA approach."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
        403:
          description: "Can't create authorisation sub-resource because consent is\
            \ in Pending state. Initial consent request may contain some validation\
            \ errors, e.g. outdated expiration date."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
        404:
          description: "Consent not found;"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
  /xs2a-premium/v1.3/recall-payments/{payment-product}/{payment-id}/authorisations/{authorisation-id}:
    get:
      tags:
      - "Payment Recall Initiation Service"
      summary: "Recall payments: Get SCA status request"
      description: "Checks the SCA status of a authorisation sub-resource."
      operationId: "PaymentRecallGetAuthorizationStatus"
      parameters:
      - 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: "authorisation-id"
        in: "path"
        description: "Identification of the related authorisation sub-resource"
        required: true
        schema:
          type: "string"
      responses:
        200:
          description: "Returns authorisation SCA status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonGetAuthorisationStatusResponse"
        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"
        403:
          description: "Can't create authorisation sub-resource because consent is\
            \ in Pending state. Initial consent request may contain some validation\
            \ errors, e.g. outdated expiration date."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
        404:
          description: "Consent not found; Authorisation sub-resource not found;"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonErrorResponse"
  /xs2a-premium/v1.3/recall-payments/{payment-product}/{payment-id}/status:
    get:
      tags:
      - "Payment Recall Initiation Service"
      summary: "Recall payments: Get Status Request"
      description: "Can check the status of a payment initiation."
      operationId: "getJSONPaymentRecallStatus"
      parameters:
      - 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"
      responses:
        200:
          description: "No errors ocurred. Returns payment's transactionStatus"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonGetPaymentRecallStatusResponse"
        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"
  /xs2a-premium/v1.3/recall-payments/{payment-product}:
    post:
      tags:
      - "Payment Recall Initiation Service"
      summary: "Recall Payments: Recall Payments Initiation with JSON encoding of\
        \ the Recall Payments Instruction"
      description: "Creates a payment recall initiation request at the ASPSP."
      operationId: "initiateJSONPaymentsRecall"
      parameters:
      - 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: "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."
        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"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonPostPaymentRecallRequest"
        required: true
      responses:
        201:
          description: "No errors occurred. In _links section redirect and self links\
            \ are used."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonPostPaymentRecallResponse"
        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; Only EUR currency\
            \ was used when payment product isn't 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"
      x-codegen-request-body-name: "body"
components:
  schemas:
    JsonErrorResponse:
      required:
      - "transactionStatus"
      type: "object"
      properties:
        psuMessage:
          type: "string"
        tppMessages:
          type: "array"
          items:
            $ref: "#/components/schemas/JsonMessage"
        transactionStatus:
          $ref: "#/components/schemas/TransactionStatus"
    JsonPostPaymentRecallRequest:
      required:
      - "paymentIdentification"
      - "creditorAccount"
      - "creditorAddress"
      - "creditorName"
      - "debtorAccount"
      - "instructedAmount"
      - "reason"
      type: "object"
      properties:
        endToEndIdentification:
          type: "string"
          description: "Unique end to end identity."
        debtorAccount:
          $ref: "#/components/schemas/JsonAccountReference"
        instructedAmount:
          $ref: "#/components/schemas/JsonAmount"
        creditorName:
          type: "string"
        creditorAddress:
          $ref: "#/components/schemas/JsonAddress"
        creditorAccount:
          $ref: "#/components/schemas/JsonAccountReference"
        paymentIdentification:
          type: "string"
        reason:
          $ref: "#/components/schemas/JsonReason"
        remittanceInformationUnstructured:
          type: "string"
          description: "Reference issued used to establish a link between the payment\
            \ of an invoice and the invoice instance."
    JsonPostPaymentRecallResponse:
      required:
      - "paymentId"
      - "transactionStatus"
      type: "object"
      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:
          $ref: "#/components/schemas/JsonLinks"
    JsonGetPaymentRecallResponse:
      required:
      - "paymentIdentification"
      - "creditorAccount"
      - "creditorAddress"
      - "creditorName"
      - "debtorAccount"
      - "instructedAmount"
      - "reason"
      type: "object"
      properties:
        endToEndIdentification:
          type: "string"
          description: "Unique end to end identity."
        debtorAccount:
          $ref: "#/components/schemas/JsonAccountReference"
        instructedAmount:
          $ref: "#/components/schemas/JsonAmount"
        reason:
          $ref: "#/components/schemas/JsonReason"
        creditorName:
          type: "string"
        creditorAddress:
          $ref: "#/components/schemas/JsonAddress"
        creditorAccount:
          $ref: "#/components/schemas/JsonAccountReference"
        remittanceInformationUnstructured:
          type: "string"
          description: "Reference issued used to establish a link between the payment\
            \ of an invoice and the invoice instance."
        transactionStatus:
          $ref: "#/components/schemas/TransactionStatus"
        _links:
          $ref: "#/components/schemas/JsonLinks"
    JsonGetPaymentRecallStatusResponse:
      required:
      - "transactionStatus"
      type: "object"
      properties:
        transactionStatus:
          $ref: "#/components/schemas/TransactionStatus"
    JsonPostAuthorisationsResponse:
      type: "object"
      properties:
        psuMessage:
          type: "string"
        tppMessages:
          type: "array"
          items:
            $ref: "#/components/schemas/JsonMessage"
        scaStatus:
          $ref: "#/components/schemas/ScaStatus"
        _links:
          $ref: "#/components/schemas/JsonLinks"
    JsonGetAuthorisationStatusResponse:
      type: "object"
      properties:
        scaStatus:
          $ref: "#/components/schemas/ScaStatus"
        authorisationId:
          type: "string"
        _links:
          $ref: "#/components/schemas/JsonLinks"
    JsonGetAuthorisationsResponse:
      type: "object"
      properties:
        authorisationsIds:
          type: "array"
          items:
            type: "string"
    JsonAccountReference:
      type: "object"
      properties:
        iban:
          type: "string"
        bban:
          type: "string"
        pan:
          type: "string"
        maskedPan:
          type: "string"
        msisdn:
          type: "string"
        currency:
          type: "string"
        code:
          type: "string"
      description: "Must contain one of iban,bban,maskedPan,msisdn or pan field"
    JsonAddress:
      required:
      - "country"
      type: "object"
      properties:
        country:
          type: "string"
    JsonAmount:
      required:
      - "amount"
      - "currency"
      type: "object"
      properties:
        currency:
          type: "string"
        amount:
          type: "string"
    JsonReason:
      required:
      - "code"
      - "information"
      type: "object"
      properties:
        code:
          type: "string"
        information:
          type: "string"
    JsonHref:
      type: "object"
      properties:
        href:
          type: "string"
    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"
    JsonMessage:
      required:
      - "category"
      - "code"
      type: "object"
      properties:
        category:
          type: "string"
        code:
          type: "string"
        path:
          type: "string"
        text:
          type: "string"
    TransactionStatus:
      type: "string"
      enum:
      - "ACCC"
      - "ACCP"
      - "ACSC"
      - "ACSP"
      - "ACTC"
      - "ACWC"
      - "ACWP"
      - "RCVD"
      - "PDNG"
      - "RJCT"
      - "CANC"
      - "ACFC"
      - "PATC"
      - "PART"
      - "CNCL"
      - "PDCR"
      - "RJCR"
      - "PNDG"
    ScaStatus:
      type: "string"
      enum:
      - "received"
      - "psuIdentified"
      - "psuAuthenticated"
      - "scaMethodSelected"
      - "started"
      - "finalised"
      - "failed"
      - "exempted"