TietoEVRY Debtor API

openapi: 3.2.0
info:
  title: SEPA Direct Debits Debtor API
  description: 'This service enables clients to initiate and accept SEPA Direct Debit payments.

    It includes an API for Creditor and for Debtor roles, which allows to initiate Payments and Refunds, accept payments and create Chargebacks.

    The API also includes an Event Notification mechanism to stay notified about the state changes of Payments, Refunds and about incoming Payments.'
  version: '1'
  contact:
    name: Tietoevry Payment Services
    url: https://tieto.ob5.konts.lv/documentation/payment-services/sepa-direct-debit/v1.0
servers:
- url: https://payments.api.tieto.com/sandbox/v1/sepadd
  description: Sepa DD Sandbox service
- url: https://payments.api.tieto.com/live/v1/sepadd
  description: Sepa DD Live service
security:
- bearerToken: []
tags:
- name: Debtor
  description: Operation for debtors
paths:
  /{receiveRefund}:
    post:
      operationId: receiveRefund
      summary: (Webhook) Receive a Refund
      description: To receive creditor-initiated refunds, the client must host an endpoint, which the system will invoke. The Refund references one or more original payments.
      tags:
      - Debtor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                properties:
                  refundId:
                    type: string
                    description: Refund identification
                    example: 3d9bbfe2-1942-4036-b1e3-d49e65c26a29
                  payments:
                    type: array
                    items:
                      type: object
                      properties:
                        paymentId:
                          type: string
                          description: Payment identification
                          example: 3d9bbfe2-1942-4036-b1e3-d49e65c26a28
              - $ref: '#/components/schemas/PaymentRequest'
      responses:
        '204':
          description: Received a refund processed successfully
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
  /{receivePaymentCharge}:
    post:
      operationId: receivePaymentCharge
      summary: (Webhook) Receive Payment Charge
      description: To receive incoming Direct Debits, the client must host a payment charges endpoint, which will be called by the system.
      tags:
      - Debtor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                properties:
                  paymentId:
                    type: string
                    description: Payment identification
                    example: 6aa06e57-031d-4359-ae5d-0188cb7817c7
              - $ref: '#/components/schemas/PaymentRequest'
      responses:
        '204':
          description: Payment charge is received successfully
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
  /{confirmAvailabilityOfFunds}:
    post:
      operationId: confirmAvailabilityOfFunds
      summary: (Webhook) Confirm availability of funds
      description: 'When processing incoming Direct Debits, the payment engine requires early on the information about the availability of funds on the debtor account.

        The client must host an endpoint, which will be called by the system for that purpose, during pre-processing of incoming payments.'
      tags:
      - Debtor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  $ref: '#/components/schemas/AccountReference'
                instructedAmount:
                  $ref: '#/components/schemas/Amount'
      responses:
        '204':
          description: Funds available
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/debtor/payments/{payment-id}/actions/reject:
    parameters:
    - $ref: '#/components/parameters/payment-id'
    post:
      operationId: rejectPayment
      summary: Reject payment
      description: 'To reject a payment, the following request can be used.


        The reason code of rejection should be specified, e.g. "MD01" - "No Mandate".'
      tags:
      - Debtor
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/Digest'
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Signature-Certificate'
      requestBody:
        description: Reason
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reasonCode:
                  $ref: '#/components/schemas/ReasonCode'
      responses:
        '204':
          description: Payment rejection message processed successfully
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
  /v1/debtor/payments/{payment-id}/chargebacks:
    parameters:
    - $ref: '#/components/parameters/payment-id'
    post:
      operationId: chargebackPayment
      summary: Create a chargeback
      description: 'To create a Chargeback, the following request can be used.


        The reason code of rejection should be specified, e.g. "MD06" - "Refund Request By End Customer".'
      tags:
      - Debtor
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/Digest'
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Signature-Certificate'
      - name: Debtor-Notification-URI
        in: header
        description: URI of a webhook, which will receive event notifications about the particular initiated payment
        schema:
          type: string
      requestBody:
        description: Reason
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reasonCode:
                  $ref: '#/components/schemas/ReasonCode'
      responses:
        '201':
          description: Chargeback creation message processed successfully
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackStatus'
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
  /{receiveChargebackStatus}:
    post:
      operationId: receiveChargebackStatus
      summary: (Callback) Receive Chargeback Status
      description: Notifications about the client-initiated Chargeback status shall be posted to the Debtor-Notification-URI, which has been specified during the creation of the Chargeback.
      tags:
      - Debtor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ChargebackStatus'
              - $ref: '#/components/schemas/Event'
      responses:
        '204':
          description: Received chargeback status message processed successfully
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
  /v1/debtor/payments/{payment-id}/chargebacks/{chargeback-id}:
    parameters:
    - $ref: '#/components/parameters/payment-id'
    - name: chargeback-id
      in: path
      required: true
      description: Chargeback identification
      schema:
        type: string
    get:
      operationId: getChargeback
      summary: Get chargeback
      description: Get previously initiated chargeback message
      tags:
      - Debtor
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/Digest'
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Signature-Certificate'
      responses:
        '200':
          description: Previously initiated chargeback message is found
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackStatus'
        4XX:
          description: Bad request
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal server error
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID-5XX'
components:
  schemas:
    MandateInformation:
      type: object
      properties:
        mandateId:
          type: string
          description: Identification of Mandates, e.g. a SEPA Mandate ID.
        recurringIndicator:
          type: boolean
          description: '"true", if the transaction is for recurring.


            "false", if the transaction is for one time.

            '
          example: true
        amount:
          type: string
          description: "The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. Negative amounts are signed by minus.\nThe decimal separator is a dot.\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n\n  * 1056\n  * 5768.2\n  * -1.50\n  * 5877.78\n"
        currency:
          type: string
          description: ISO 4217 Alpha 3 currency code
          example: EUR
    ChargebackStatus:
      type: object
      properties:
        chargebackId:
          type: string
          description: Chargeback identification
          example: 3d9bbfe2-1942-4036-b1e3-d49e65c26a29
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
        _links:
          type: object
          properties:
            chargeback:
              type: object
              description: Link to chargeback resource
              properties:
                href:
                  type: string
                  description: Link to a resource
    Event:
      type: object
      properties:
        event:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/EventName'
            timestamp:
              type: string
              format: date-time
              example: '2021-06-02T12:00:00Z'
    ErrorResponse:
      type: object
      required:
      - transactionStatus
      properties:
        messages:
          type: array
          description: Messages on operational issues.
          items:
            type: object
            required:
            - category
            - code
            properties:
              category:
                type: string
                description: Category of the message category
                enum:
                - ERROR
                - WARNING
              code:
                type: string
                enum:
                - CERTIFICATE_INVALID
                - CERTIFICATE_EXPIRED
                - CERTIFICATE_BLOCKED
                - CERTIFICATE_REVOKED
                - CERTIFICATE_MISSING
                - SIGNATURE_INVALID
                - SIGNATURE_MISSING
                - FORMAT_ERROR
                - PARAMETER_NOT_SUPPORTED
                - PSU_CREDENTIALS_INVALID
                - SERVICE_INVALID
                - SERVICE_BLOCKED
                - TOKEN_UNKNOWN
                - TOKEN_INVALID
                - TOKEN_EXPIRED
                - RESOURCE_UNKNOWN
                - RESOURCE_EXPIRED
                - TIMESTAMP_INVALID
                - PERIOD_INVALID
                - SCA_METHOD_UNKNOWN
                - PRODUCT_INVALID
                - PRODUCT_UNKNOWN
                - PAYMENT_FAILED
                - REQUIRED_KID_MISSING
                - EXECUTION_DATE_INVALID
                - ACCESS_EXCEEDED
                - REQUESTED_FORMATS_INVALID
                - CARD_INVALID
                - NO_PIIS_ACTIVATION
              text:
                type: string
                description: Additional explaining text
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
    PaymentRequest:
      type: object
      description: Data that describes the payment
      properties:
        instructedAmount:
          $ref: '#/components/schemas/Amount'
        debtorAccount:
          $ref: '#/components/schemas/AccountReference'
        debtorName:
          type: string
          description: Debtor Name
        creditorAccount:
          $ref: '#/components/schemas/AccountReference'
        creditorName:
          type: string
          description: Creditor Name
        creditorAgent:
          type: string
          description: BICFI
          example: AAAADEBBXXX
        creditorAgentName:
          type: string
        creditorId:
          type: string
          description: Identification of Creditors, e.g. a SEPA Creditor ID.
          example: DE452399865083
        endToEndIdentification:
          type: string
          example: 123-ZXCV-890
        requestedExecutionDate:
          type: string
          format: date
          example: '2021-06-01'
        remittanceInformationStructured:
          $ref: '#/components/schemas/RemittanceInformationStructured'
        mandateInformation:
          $ref: '#/components/schemas/MandateInformation'
    TransactionStatus:
      description: "The transaction status is filled with codes of the ISO 20022 data table:\n- 'ACCP': 'AcceptedCustomerProfile' -\n  Preceding check of technical validation was successful.\n  Customer profile check was also successful.\n- 'ACSC': 'AcceptedSettlementCompleted' -\n  Settlement on the debtor’s account has been completed.\n\n  **Usage:** this can be used by the first agent to report to the debtor that the transaction has been completed.\n\n  **Warning:** this status is provided for transaction status reasons, not for financial information.\n  It can only be used after bilateral agreement.\n- 'ACSP': 'AcceptedSettlementInProcess' -\n  All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.\n- 'ACTC': 'AcceptedTechnicalValidation' -\n  Authentication and syntactical and semantical validation are successful.\n- 'ACWC': 'AcceptedWithChange' -\n  Instruction is accepted but a change will be made, such as date or remittance not sent.\n- 'ACWP': 'AcceptedWithoutPosting' -\n  Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account.\n- 'RCVD': 'Received' -\n  Payment initiation has been received by the receiving agent.\n- 'PDNG': 'Pending' -\n  Payment initiation or individual transaction included in the payment initiation is pending.\n  Further checks and status update will be performed.\n- 'RJCT': 'Rejected' -\n  Payment initiation or individual transaction included in the payment initiation has been rejected.\n- 'CANC': 'Cancelled'\n  Payment initiation has been cancelled before execution\n\n  **Remark:** *Change Request to ISO20022 is still needed.*\n"
      type: string
      enum:
      - ACCP
      - ACSC
      - ACSP
      - ACTC
      - ACWC
      - ACWP
      - RCVD
      - PDNG
      - RJCT
      - CANC
      example: ACCP
    RemittanceInformationStructured:
      type: object
      description: Structured remittance information
      properties:
        reference:
          type: string
          example: REF123123
    Amount:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          description: "The amount given with fractional digits, where fractions must be compliant to the currency definition.\nUp to 14 significant figures. Negative amounts are signed by minus.\nThe decimal separator is a dot.\n\n**Example:**\nValid representations for EUR with up to two decimals are:\n\n  * 1056\n  * 5768.2\n  * -1.50\n  * 5877.78\n"
          example: '1000'
        currency:
          type: string
          description: ISO 4217 Alpha 3 currency code
          example: EUR
    EventName:
      type: string
      description: Event name
      enum:
      - SettledWithCreditor
    ReasonCode:
      type: string
      description: '"MD05" - "Collection not due"

        "MD06" - "Refund Request By End Customer"

        '
      enum:
      - MD05
      - MD06
    AccountReference:
      type: object
      required:
      - iban
      properties:
        iban:
          type: string
          description: IBAN of an account
          example: DE89370400440532013000
  parameters:
    payment-id:
      name: payment-id
      in: path
      required: true
      description: Payment identification
      schema:
        type: string
    X-Request-ID:
      name: X-Request-ID
      in: header
      description: ID of the request, unique to the call
      required: true
      schema:
        type: string
        format: uuid
    Digest:
      name: Digest
      in: header
      description: Is contained if and only if the "Signature" element is contained in the header of the request.
      schema:
        type: string
      required: false
      example: SHA-256=hl1/Eps8BEQW58FJhDApwJXjGY4nr1ArGDHIT25vq6A=
    Signature-Certificate:
      name: Signature-Certificate
      in: header
      description: 'The certificate used for signing the request, in base64 encoding.

        Must be contained if a signature is contained.

        '
      schema:
        type: string
        format: byte
      required: false
    Signature:
      name: Signature
      in: header
      description: 'A signature of the request by the TPP on application level. This might be mandated by ASPSP.

        '
      schema:
        type: string
      required: false
      example: 'keyId="SN=9FA1,CA=CN=D-TRUST%20CA%202-1%202015,O=D-Trust%20GmbH,C=DE",algorithm="rsa-sha256", headers="Digest X-Request-ID PSU-ID TPP-Redirect-URI Date", signature="Base64(RSA-SHA256(signing string))"

        '
  headers:
    X-Request-ID:
      description: ID of the request, unique to the call
      required: true
      schema:
        type: string
        format: uuid
    X-Request-ID-5XX:
      description: ID of the request, unique to the call
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerToken:
      type: openIdConnect
      openIdConnectUrl: http://example/openid-connect