Enable Banking Payments API

openapi: 3.1.0
info:
  title: API reference Accounts data Payments API
  version: 1.0.0-3030f99c
servers:
- url: https://api.enablebanking.com
- url: https://api.tilisy.com
  description: (deprecated)
security:
- bearerAuth: []
tags:
- name: Payments
paths:
  /payments:
    post:
      tags:
      - Payments
      summary: Create payment
      description: Creating a payment consisting of one or multiple payment transactions
      operationId: create_payment_payments_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
              description: Contains data necessary for initiating a payment
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/{payment_id}:
    get:
      tags:
      - Payments
      summary: Get payment
      description: Fetching payment status and details
      operationId: get_payment_payments__payment_id__get
      parameters:
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
          description: Payment ID
          title: Payment Id
        description: Payment ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Timeout
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
    delete:
      tags:
      - Payments
      summary: Delete payment
      description: Delete finished or failed payment
      operationId: delete_payment_payments__payment_id__delete
      parameters:
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
          description: Payment ID
          title: Payment Id
        description: Payment ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Timeout
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
  /payments/{payment_id}/transactions/{transaction_id}:
    get:
      tags:
      - Payments
      summary: Get payment transaction
      description: Fetching transaction details for a single transaction within a bulk payment
      operationId: get_payment_transaction_payments__payment_id__transactions__transaction_id__get
      parameters:
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
          description: Payment ID
          title: Payment Id
        description: Payment ID
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          description: Transaction ID
          title: Transaction Id
        description: Transaction ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentTransactionResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Timeout
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
components:
  schemas:
    PaymentTypeInformation:
      properties:
        instruction_priority:
          description: Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply
          $ref: '#/components/schemas/PriorityCode'
        service_level:
          description: Agreement under which or rules under which the transaction should be processed. Specifies a pre-agreed service or level of service between the parties, as published in an external service level code list
          $ref: '#/components/schemas/ServiceLevelCode'
        category_purpose:
          description: Specifies the high level purpose of the instruction based on a set of pre-defined categories. This is used by the initiating party to provide information concerning the processing of the payment. It is likely to trigger special processing by any of the agents involved in the payment chain.
          $ref: '#/components/schemas/CategoryPurposeCode'
        local_instrument:
          title: Local Instrument
          description: User community specific instrument
          type: string
      type: object
      title: PaymentTypeInformation
    PaymentRequestResource:
      properties:
        payment_information_id:
          description: Reference assigned by a sending party to unambiguously identify the payment information block within the message
          $ref: '#/components/schemas/PaymentInformationId'
        payment_type_information:
          description: Set of elements used to further specify the type of payment
          $ref: '#/components/schemas/PaymentTypeInformation'
        debtor:
          description: Identification of the party sending funds
          $ref: '#/components/schemas/PartyIdentification'
        debtor_account:
          description: Identification of the account from which funds are sent when the payment is executed. When the debtor account is not provided it is to be chosen by the PSU during payment authorisation flow.
          $ref: '#/components/schemas/GenericIdentification'
        debtor_agent:
          description: Identification of the financial institution where the debtor account is held. To be provided only in case the financial institution can not be unambiguously identified the ASPSP name towards which the payment is initiated.
          $ref: '#/components/schemas/FinancialInstitutionIdentification'
        debtor_currency:
          type: string
          title: Debtor Currency
          description: ISO 4217 code, in which debtor account is held
          default: XXX
        purpose:
          description: Underlying reason for the payment
          $ref: '#/components/schemas/PurposeCode'
        charge_bearer:
          description: Specifies which party/parties will bear the charges associated with the processing of the payment
          $ref: '#/components/schemas/ChargeBearerCode'
        credit_transfer_transaction:
          items:
            $ref: '#/components/schemas/CreditTransferTransaction'
          type: array
          minItems: 1
          title: Credit Transfer Transaction
          description: Payment instructions to be executed towards one or multiple beneficiaries in the payment process. Maximum number of transactions depend on the ASPSP and type of the payment taking into accounts its specificities about payment request handling.
      type: object
      required:
      - credit_transfer_transaction
      title: PaymentRequestResource
      example:
        credit_transfer_transaction:
        - beneficiary:
            creditor:
              name: Organisation/Person Name
            creditor_account:
              identification: FI0455231152453547
              scheme_name: IBAN
          instructed_amount:
            amount: '10.33'
            currency: EUR
        debtor_account:
          identification: FI7727551317119265
          scheme_name: IBAN
    GetPaymentResponse:
      properties:
        payment_id:
          type: string
          format: uuid
          title: Payment Id
          description: Payment ID
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: Payment status
        payment_details:
          $ref: '#/components/schemas/PaymentRequestResourceDetails'
          description: Payment request
        payment_type:
          $ref: '#/components/schemas/PaymentType'
          description: Specifies the type of payment used
        aspsp:
          $ref: '#/components/schemas/ASPSP'
          description: ASPSP used for the payment
          examples:
          - country: FI
            name: Nordea
        final_status:
          type: boolean
          title: Final Status
          description: Indicates whether the payment has reached the status expected to be final (i.e. if the value of the field is `true`, the payment status is not expected to change on later requests)
        status_reason_information:
          description: Details explaining the payment status, provided when the cause can be determined unambiguously, mainly for rejected payments
          $ref: '#/components/schemas/StatusReasonInformation'
        psu_id_hash:
          type: string
          title: Psu Id Hash
          description: Hashed unique identification of a PSU used by the client application. In case PSU ID is not passed by the client application, the hash is calculated based on a random value. The hash also inherits the application ID, so different hashes will be calculated when using the same PSU ID with different applications.
      type: object
      required:
      - payment_id
      - status
      - payment_details
      - payment_type
      - aspsp
      - final_status
      - psu_id_hash
      title: GetPaymentResponse
    EndDate:
      type: string
      format: date
      title: EndDate
      description: 'The last applicable day of execution for a given standing order.

        If not given, the standing order is considered as endless.

        '
    GenericIdentification:
      properties:
        identification:
          type: string
          title: Identification
          description: An identifier
          examples:
          - '12345678'
        scheme_name:
          $ref: '#/components/schemas/SchemeName'
          description: Name of the identification scheme. Partially based on ISO20022 external code list
          examples:
          - BBAN
        issuer:
          title: Issuer
          description: Entity that assigns the identification. This could be a country code or any organisation name or identifier that can be recognized by both parties
          examples:
          - FR
          type: string
      type: object
      required:
      - identification
      - scheme_name
      title: GenericIdentification
      example:
        identification: '123456'
        scheme_name: BBAN
    PaymentStatus:
      type: string
      enum:
      - ACCC
      - ACCP
      - ACSC
      - ACSP
      - ACTC
      - ACWC
      - ACWP
      - PART
      - RCVD
      - PDNG
      - RJCT
      - ACPT
      - ACCR
      - RJCR
      - PACR
      - PDCR
      - CNCL
      - 'NULL'
      title: PaymentStatus
      example: ACCC
      x-enum-descriptions:
      - AcceptedCreditSettlementCompleted. Settlement on the creditor's account has been completed.
      - AcceptedCustomerProfile. Preceding check of technical validation was successful. Customer profile check was also successful.
      - AcceptedCancellationRequest. Cancellation is accepted.
      - Accepted. Request is accepted.
      - AcceptedSettlementCompleted. Settlement on the debtor's account has been completed.
      - AcceptedSettlementInProcess. All preceding checks such as technical validation and customer profile were successful. Dynamic risk assessment is now also successful and therefore the Payment Request has been accepted for execution.
      - AcceptedTechnicalValidation. Authentication and syntactical and semantical validation are successful.
      - AcceptedWithChange. Instruction is accepted but a change will be made, such as date or remittance not sent.
      - AcceptedWithoutPosting. Payment instruction included in the credit transfer is accepted without being posted to the creditor's account.
      - PaymentCancelled. Payment is cancelled.
      - NoCancellationProcess. There is no cancellation process ongoing.
      - PartiallyAcceptedCancellationRequest. Cancellation is partially accepted.
      - PartiallyAccepted. A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status.
      - PendingCancellationRequest. Cancellation request is pending.
      - Pending. Payment request or individual transaction included in the Payment Request is pending. Further checks and status update will be performed.
      - Received. Payment initiation has been received by the receiving agent.
      - RejectedCancellationRequest. Cancellation request is rejected.
      - Rejected. Payment request  has been rejected.
    StatusReasonInformation:
      properties:
        status_reason_code:
          type: string
          title: Status Reason Code
          description: ISO20022 status reason code
        status_reason_description:
          type: string
          title: Status Reason Description
          description: Status reason description
      type: object
      required:
      - status_reason_code
      - status_reason_description
      title: StatusReasonInformation
    CreditTransferTransactionDetails:
      properties:
        instructed_amount:
          $ref: '#/components/schemas/AmountType'
          description: Structure aiming to embed the amount and the currency to be used
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
          description: Specification of a beneficiary
        payment_id:
          description: Set of elements used to reference a payment instruction
          $ref: '#/components/schemas/PaymentIdentification'
        requested_execution_date:
          $ref: '#/components/schemas/RequestedExecutionDate'
        reference_number:
          $ref: '#/components/schemas/ReferenceNumber'
        end_date:
          $ref: '#/components/schemas/EndDate'
        execution_rule:
          description: Execution date shifting rule for standing orders
          $ref: '#/components/schemas/ExecutionRule'
        frequency:
          description: Frequency rule for standing orders
          $ref: '#/components/schemas/FrequencyCode'
        ultimate_debtor:
          description: Identifies the original party from whom the funds originate in the payment transaction
          $ref: '#/components/schemas/PartyIdentification'
        ultimate_creditor:
          description: Identifies the final party receiving the funds in the payment transaction
          $ref: '#/components/schemas/PartyIdentification'
        regulatory_reporting:
          title: Regulatory Reporting
          description: List of needed regulatory reporting codes for international payments
          items:
            $ref: '#/components/schemas/RegulatoryReporting'
          type: array
          maxItems: 10
          minItems: 1
        remittance_information:
          $ref: '#/components/schemas/UnstructuredRemittanceInformation'
        transaction_id:
          title: Transaction Id
          description: Unique identifier of the payment transaction, which can be used for fetching details through the get payment transaction endpoint
          type: string
        transaction_status:
          description: Status of the payment transaction
          $ref: '#/components/schemas/PaymentStatus'
      type: object
      required:
      - instructed_amount
      - beneficiary
      title: CreditTransferTransactionDetails
      description: Details of the payment instruction executed (to be executed) by the ASPSP
    ASPSP:
      properties:
        name:
          type: string
          title: Name
          description: Name of the ASPSP (i.e. a bank or a similar financial institution)
          examples:
          - Nordea
        country:
          type: string
          title: Country
          description: Two-letter ISO 3166 code of the country, in which ASPSP operates
          examples:
          - FI
      type: object
      required:
      - name
      - country
      title: ASPSP
    AmountType:
      properties:
        currency:
          type: string
          title: Currency
          description: ISO 4217 code of the currency of the amount
          examples:
          - EUR
        amount:
          type: string
          pattern: ^-?\d+(\.\d+)?$
          title: Amount
          description: Numerical value or monetary figure associated with a particular transaction, representing balance on an account, a fee or similar. Represented as a decimal number, using . (dot) as a decimal separator. Allowed precision (number of digits after the decimal separator) varies depending on the currency and is validated differently depending on the context.
          examples:
          - '1.23'
      type: object
      required:
      - currency
      - amount
      title: AmountType
    GetPaymentTransactionResponse:
      properties:
        payment_id:
          type: string
          format: uuid
          title: Payment Id
          description: Payment ID
        transaction_details:
          $ref: '#/components/schemas/CreditTransferTransactionDetails'
          description: Payment transaction details
      type: object
      required:
      - payment_id
      - transaction_details
      title: GetPaymentTransactionResponse
    RequestedExecutionDate:
      type: string
      format: date
      title: RequestedExecutionDate
      description: 'Date at which the initiating party requests the clearing agent to process the payment.

        API:

        This date can be used in the following cases:

        - the single requested execution date for a payment having several instructions. In this case, this field must be set at the payment level.

        - the requested execution date for a given instruction within a payment. In this case, this field must be set at each instruction level.

        - The first date of execution for a standing order.

        When the payment cannot be processed at this date, the ASPSP is allowed to shift the applied execution date to the next possible execution date for non-standing orders.

        For standing orders, the [executionRule] parameter helps to compute the execution date to be applied.

        '
    PaymentRequestResourceDetails:
      properties:
        payment_information_id:
          description: Reference assigned by a sending party to unambiguously identify the payment information block within the message
          $ref: '#/components/schemas/PaymentInformationId'
        payment_type_information:
          description: Set of elements used to further specify the type of payment
          $ref: '#/components/schemas/PaymentTypeInformation'
        debtor:
          description: Identification of the party sending funds
          $ref: '#/components/schemas/PartyIdentification'
        debtor_account:
          description: Identification of the account from which funds are sent when the payment is executed. When the debtor account is not provided it is to be chosen by the PSU during payment authorisation flow.
          $ref: '#/components/schemas/GenericIdentification'
        debtor_agent:
          description: Identification of the financial institution where the debtor account is held. To be provided only in case the financial institution can not be unambiguously identified the ASPSP name towards which the payment is initiated.
          $ref: '#/components/schemas/FinancialInstitutionIdentification'
        debtor_currency:
          type: string
          title: Debtor Currency
          description: ISO 4217 code, in which debtor account is held
          default: XXX
        purpose:
          description: Underlying reason for the payment
          $ref: '#/components/schemas/PurposeCode'
        charge_bearer:
          description: Specifies which party/parties will bear the charges associated with the processing of the payment
          $ref: '#/components/schemas/ChargeBearerCode'
        credit_transfer_transaction:
          title: Credit Transfer Transaction
          items:
            $ref: '#/components/schemas/CreditTransferTransactionDetails'
          type: array
      type: object
      title: PaymentRequestResourceDetails
      example:
        credit_transfer_transaction:
        - beneficiary:
            creditor:
              name: Organisation/Person Name
            creditor_account:
              identification: FI0455231152453547
              scheme_name: IBAN
          instructed_amount:
            amount: '10.33'
            currency: EUR
        debtor_account:
          identification: FI7727551317119265
          scheme_name: IBAN
    ServiceLevelCode:
      type: string
      enum:
      - BKTR
      - G001
      - G002
      - G003
      - G004
      - NUGP
      - NURG
      - PRPT
      - SDVA
      - SEPA
      - SVDE
      - URGP
      - URNS
      title: ServiceLevelCode
      example: BKTR
      x-enum-descriptions:
      - 'Book Transaction: Payment through internal book transfer'
      - 'Tracked Customer Credit Transfer: Tracked Customer Credit Transfer'
      - 'Tracked Stop And Recall: Tracked Stop and Recall'
      - 'Tracked Corporate Transfer: Tracked Corporate Transfer'
      - 'Tracked Financial Institution Transfer: Tracked Financial Institution Transfer'
      - 'Non-urgent Priority Payment: Payment must be executed as a non-urgent transaction with priority settlement'
      - 'Non-urgent Payment: Payment must be executed as a non-urgent transaction, which is typically identified as an ACH or low value transaction'
      - 'EBA Priority Service: Transaction must be processed according to the EBA Priority Service'
      - 'Same Day Value: Payment must be executed with same day value to the creditor'
      - 'Single Euro Payments Area: Payment must be executed following the Single Euro Payments Area scheme'
      - 'Domestic Cheque Clearing and Settlement: Payment execution following the cheque agreement and traveller cheque agreement of the German Banking Industry Committee (Die Deutsche Kreditwirtschaft - DK) and Deutsche Bundesbank – Scheck Verrechnung Deutschland'
      - 'Urgent Payment: Payment must be executed as an urgent transaction cleared through a real-time gross settlement system, which is typically identified as a wire or high value transaction'
      - 'Urgent Payment Net Settlement: Payment must be executed as an urgent transaction cleared through a real-time net settlement system, which is typically identified as a wire or high value transaction'
    PostalAddress:
      properties:
        address_type:
          description: Available address type values
          examples:
          - DeliveryTo
          $ref: '#/components/schemas/AddressType'
        department:
          title: Department
          description: Identification of a division of a large organisation or building.
          examples:
          - Department of resources
          type: string
        sub_department:
          title: Sub Department
          description: Identification of a sub-division of a large organisation or building.
          examples:
          - Sub Department of resources
          type: string
        street_name:
          title: Street Name
          description: Name of a street or thoroughfare.
          examples:
          - Vasavagen
          type: string
        building_number:
          title: Building Number
          description: Number that identifies the position of a building on a street.
          examples:
          - '4'
          type: string
        post_code:
          title: Post Code
          description: 'Identifier consisting of a group of letters and/or numbers that is

            added to a postal address to assist the sorting of mail.'
          examples:
          - '00123'
          type: string
        town_name:
          title: Town Name
          description: Name of a built-up area, with defined boundaries, and a local government.
          examples:
          - Helsinki
          type: string
        country_sub_division:
          title: Country Sub Division
          description: Identifies a subdivision of a country such as state, region, county.
          examples:
          - Uusimaa
          type: string
        country:
          title: Country
          description: Two-letter ISO 3166 code of the country in which a person resides (the place of a person's home). In the case of a company, it is the country from which the affairs of that company are directed.
          examples:
          - FI
          type: string
        address_line:
          title: Address Line
          description: Unstructured address. The two lines must embed zip code and town name
          examples:
          - - Mr Asko Teirila PO Box 511
            - 39140 AKDENMAA FINLAND
          items:
            type: string
          type: array
      type: object
      title: PostalAddress
    CreatePaymentRequest:
      properties:
        payment_type:
          $ref: '#/components/schemas/PaymentType'
          description: Specifies the type of payment used
        payment_request:
          $ref: '#/components/schemas/PaymentRequestResource'
          description: Specifies the details required to initiate a payment
        aspsp:
          $ref: '#/components/schemas/ASPSP'
          description: ASPSP that PSU is going to be authenticated to
          examples:
          - country: FI
            name: Nordea
        state:
          type: string
          title: State
          description: Arbitrary string. Same string will be returned in query parameter when redirecting to the URL passed via redirect_url parameter
          examples:
          - 3a57e2d3-2e0c-4336-af9b-7fa94f0606a3
        redirect_url:
          type: string
          minLength: 1
          format: uri
          title: Redirect Url
          description: URL that PSU will be redirected to after authorization
        psu_type:
          $ref: '#/components/schemas/PSUType'
          description: PSU type which consent is created for
        auth_method:
          title: Auth Method
          description: Desired authorization method (in case ASPSP integration supports multiple). Supported methods can be obtained from the `auth_methods` field available in ASPSP details.
          type: string
        credentials:
          title: Credentials
          description: PSU credentials (e.g., user and/or company ID). If not provided through the API, they will be requested from the PSU during authorization. Credentials can be supplied only if `auth_method` is specified; otherwise, a `WRONG_REQUEST_PARAMETERS` error will be returned.
          examples:
          - userId: MyUsername
          type: object
        language:
          title: Language
          description: Preferred PSU language. Two-letter lowercase language code
          examples:
          - fi
          type: string
          pattern: ^[a-z]{2}$
        webhook_url:
          title: Webhook Url
          description: URL that will receive POST requests notifying about payment changes. See the [webhooks documentation](../webhooks/index.md#payment-status-webhook) for more details
          examples:
          - https://app.com/payment-webhook-handler
          type: string
          minLengt

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/enable-banking/refs/heads/main/openapi/enable-banking-payments-api-openapi.yml