> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment initiation request

> Creates a payment initiation resource for the specified payment product



## OpenAPI

````yaml post /open-banking/v1/payments/{payment-product}
openapi: 3.0.3
info:
  title: Ledger Client API
  version: 1.0.0
  description: API for ledger operations - parties, accounts, transactions
servers: []
security: []
tags:
  - name: Account Statements
    description: Retrieve account transaction history
  - name: Accounts
    description: Account management operations
  - name: Open Banking - Accounts
    description: PSD2 Account Information Service (AIS) - Account endpoints
  - name: Open Banking - Funds Confirmation
    description: PSD2 Confirmation of Funds Service (PIIS)
  - name: Open Banking - Payments
    description: PSD2 Payment Initiation Service (PIS)
  - name: Open Banking - Transactions
    description: PSD2 Account Information Service (AIS) - Transaction endpoints
  - name: Parties
    description: Party management operations
  - name: Payments
    description: Payment operations
  - name: Transaction Postings
    description: Retrieve transaction postings
  - name: Transactions
    description: Transaction execution operations
paths:
  /open-banking/v1/payments/{payment-product}:
    post:
      tags:
        - Open Banking - Payments
      summary: Payment initiation request
      description: >-
        Creates a payment initiation resource addressable under {paymentId} with
        all data relevant for the corresponding payment product
      parameters:
        - description: >-
            The addressed payment product. Standard products are:
            sepa-credit-transfers, instant-sepa-credit-transfers,
            target-2-payments, cross-border-credit-transfers
          example: sepa-credit-transfers
          required: true
          name: payment-product
          in: path
          schema:
            type: string
        - description: >-
            Shall be contained if the payment initiation transaction is part of
            a session, i.e. combined AIS/PIS service
          name: Consent-ID
          in: header
          schema:
            type: string
            nullable: true
        - description: >-
            The forwarded IP Address header field consists of the corresponding
            HTTP request IP Address field between PSU and TPP
          example: 192.168.8.78
          required: true
          name: PSU-IP-Address
          in: header
          schema:
            type: string
        - description: >-
            ID of the request, unique to the call, as determined by the
            initiating party
          example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
          required: true
          name: X-Request-ID
          in: header
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInitiationRequest'
        required: true
      responses:
        '201':
          description: Payment initiation request was correctly performed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiationResponse'
        '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'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PaymentInitiationRequest:
      description: >-
        Payment initiation request body based on Section 11.1 core payment
        structures
      required:
        - debtorAccount
        - instructedAmount
        - creditorAccount
        - creditorName
      type: object
      properties:
        endToEndIdentification:
          description: End-to-end identification of the payment
          maxLength: 35
          type: string
          example: Payment-123
          nullable: true
        debtorAccount:
          description: Debtor account reference
          type: object
          allOf:
            - $ref: '#/components/schemas/AccountReference'
        instructedAmount:
          description: Amount to be transferred
          type: object
          allOf:
            - $ref: '#/components/schemas/Amount'
        creditorAccount:
          description: Creditor account reference
          type: object
          allOf:
            - $ref: '#/components/schemas/AccountReference'
        creditorAgent:
          description: >-
            BIC of the creditor agent (creditor's bank). Optional for SEPA,
            conditional for cross-border
          type: string
          example: DEUTDEDBFRA
          nullable: true
        creditorName:
          description: Name of the creditor
          maxLength: 70
          type: string
          example: Merchant AG
        creditorAddress:
          description: Address of the creditor
          type: object
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
        remittanceInformationUnstructured:
          description: Unstructured remittance information
          maxLength: 140
          type: string
          example: Ref Number Merchant
          nullable: true
        requestedExecutionDate:
          description: Requested execution date for future-dated payments in ISODate format
          type: string
          example: '2025-12-01T00:00:00.000Z'
          nullable: true
    PaymentInitiationResponse:
      required:
        - transactionStatus
        - paymentId
        - _links
      type: object
      properties:
        transactionStatus:
          description: ISO 20022 transaction status
          enum:
            - ACCC
            - ACCP
            - ACSC
            - ACSP
            - ACTC
            - ACWC
            - ACWP
            - RCVD
            - PDNG
            - RJCT
            - CANC
            - ACFC
            - PATC
            - PART
            - RVCM
            - RVNC
            - RCVC
          type: string
          example: RCVD
        paymentId:
          description: Resource identification of the generated payment initiation resource
          type: string
          example: 1234-payment-567
        transactionFees:
          description: >-
            Transaction fees for the payment initiation, including currency
            conversion fees if applicable
          type: object
          allOf:
            - $ref: '#/components/schemas/Amount'
          nullable: true
        currencyConversionFee:
          description: Currency conversion fees related to the initiated credit transfer
          type: object
          allOf:
            - $ref: '#/components/schemas/Amount'
          nullable: true
        estimatedTotalAmount:
          description: >-
            Estimated total amount to be debited from the debtor account,
            including fees
          type: object
          allOf:
            - $ref: '#/components/schemas/Amount'
          nullable: true
        estimatedInterbankSettlementAmount:
          description: Estimated amount to be transferred to the payee
          type: object
          allOf:
            - $ref: '#/components/schemas/Amount'
          nullable: true
        transactionFeeIndicator:
          description: If true, the transaction will involve specific transaction cost
          type: boolean
          nullable: true
        scaMethods:
          description: >-
            Available SCA methods for the PSU, if SCA is required and the PSU
            has a choice
          type: array
          items:
            $ref: '#/components/schemas/AuthenticationObject'
          nullable: true
        _links:
          description: HATEOAS links
          type: object
          allOf:
            - $ref: '#/components/schemas/Links'
        psuMessage:
          description: Text to be displayed to the PSU
          type: string
          example: Please check your bank app
          nullable: true
        tppMessages:
          description: Messages to the TPP on operational issues
          type: array
          items:
            $ref: '#/components/schemas/TppMessage'
          nullable: true
    ErrorResponse:
      description: NextGenPSD2 error response body
      type: object
      properties:
        tppMessages:
          description: Messages to the TPP on operational issues
          type: array
          items:
            $ref: '#/components/schemas/TppMessage'
          nullable: true
        _links:
          description: HATEOAS links
          type: object
          allOf:
            - $ref: '#/components/schemas/Links'
          nullable: true
    AccountReference:
      description: >-
        Reference to an account by IBAN, BBAN, PAN, or MSISDN. Exactly one of
        the account reference identifiers shall be used
      type: object
      properties:
        iban:
          description: IBAN of the account
          type: string
          example: DE40100100103307118608
          nullable: true
        bban:
          description: BBAN of the account, for payment accounts which have no IBAN
          type: string
          example: '1234567890'
          nullable: true
        pan:
          description: >-
            Primary Account Number (PAN) of a card, can be tokenised by the
            ASPSP
          maxLength: 35
          type: string
          example: '5409050000000000'
          nullable: true
        maskedPan:
          description: Masked PAN of a card in masked form
          maxLength: 35
          type: string
          example: 123456xxxxxx1234
          nullable: true
        msisdn:
          description: >-
            Alias to access a payment account via a registered mobile phone
            number
          maxLength: 35
          type: string
          example: '+49170123456'
          nullable: true
        currency:
          description: ISO 4217 currency code
          maxLength: 3
          minLength: 3
          type: string
          example: EUR
          nullable: true
    Amount:
      description: Amount information
      required:
        - currency
        - amount
      type: object
      properties:
        currency:
          description: ISO 4217 currency code
          maxLength: 3
          minLength: 3
          type: string
          example: EUR
        amount:
          description: >-
            The amount given with fractional digits, where fractions must be
            compliant to the currency definition. Up to 14 significant figures.
            Negative amounts are signed by minus
          type: string
          example: '123.50'
    Address:
      description: Postal address as defined in Section 14.4
      required:
        - country
      type: object
      properties:
        department:
          description: Identification of a division of a large organisation or building
          maxLength: 70
          type: string
          example: Finance Department
          nullable: true
        subDepartment:
          description: Identification of a sub-division of a large organisation or building
          maxLength: 70
          type: string
          example: Accounting Unit
          nullable: true
        streetName:
          description: Name of a street or thoroughfare
          maxLength: 70
          type: string
          example: Hauptstrasse
          nullable: true
        buildingNumber:
          description: Number that identifies the position of a building on a street
          maxLength: 16
          type: string
          example: '42'
          nullable: true
        buildingName:
          description: Name of the building or house
          maxLength: 35
          type: string
          example: Tower A
          nullable: true
        floor:
          description: Floor or storey within a building
          maxLength: 70
          type: string
          example: '3'
          nullable: true
        postBox:
          description: Numbered box in a post office
          maxLength: 16
          type: string
          example: PO Box 123
          nullable: true
        room:
          description: Building room number
          maxLength: 70
          type: string
          example: '301'
          nullable: true
        postCode:
          description: Post code
          maxLength: 16
          type: string
          example: '60311'
          nullable: true
        townName:
          description: >-
            Name of a built-up area with defined boundaries and a local
            government. Mandatory if address lines are not used
          maxLength: 35
          type: string
          example: Frankfurt am Main
          nullable: true
        townLocationName:
          description: Specific location name within the town
          maxLength: 35
          type: string
          example: Sachsenhausen
          nullable: true
        districtName:
          description: Identifies a subdivision within a country sub-division
          maxLength: 35
          type: string
          example: Bayern
          nullable: true
        countrySubDivision:
          description: Identifies a subdivision of a country such as state, region, county
          maxLength: 35
          type: string
          example: Hessen
          nullable: true
        country:
          description: ISO 3166 two-character country code
          pattern: '[A-Z]{2}'
          type: string
          example: DE
    AuthenticationObject:
      description: Authentication object as defined in Section 14.8
      required:
        - authenticationType
        - authenticationMethodId
        - name
      type: object
      properties:
        authenticationType:
          description: Type of the authentication method
          enum:
            - SMS_OTP
            - CHIP_OTP
            - PHOTO_OTP
            - PUSH_OTP
            - SMTP_OTP
          type: string
          example: SMS_OTP
        authenticationVersion:
          description: >-
            Version of the authentication type, depending on the
            authenticationType
          type: string
          nullable: true
        authenticationMethodId:
          description: >-
            Identification provided by the ASPSP for the later identification of
            the authentication method selection
          maxLength: 35
          type: string
          example: myAuthenticationID
        name:
          description: >-
            Name of the authentication method as defined by the PSU in the
            Online Banking frontend of the ASPSP
          type: string
          example: SMS OTP on phone +49160 xxxxx 28
        explanation:
          description: Detailed information about the SCA method for the PSU
          type: string
          nullable: true
    Links:
      description: HATEOAS links as defined in Section 14.6, conforming to HAL
      type: object
      properties:
        scaRedirect:
          description: >-
            Link to an ASPSP site where SCA is performed within the Redirect SCA
            approach
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        scaOAuth:
          description: Link to the OAuth2 authorisation server configuration of the ASPSP
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        confirmation:
          description: URL to be updated with confirmation code or access token after SCA
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        startAuthorisation:
          description: Link to start the authorisation process
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        startAuthorisationWithPsuIdentification:
          description: Link to start authorisation with PSU identification
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        updatePsuIdentification:
          description: Link to update PSU identification
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        startAuthorisationWithProprietaryData:
          description: Link to start authorisation with proprietary data
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        updateProprietaryData:
          description: Link to update proprietary data
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        startAuthorisationWithPsuAuthentication:
          description: Link to start authorisation with PSU authentication
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        updatePsuAuthentication:
          description: Link to update PSU authentication
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        updateAdditionalPsuAuthentication:
          description: Link to update additional PSU authentication
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        startAuthorisationWithEncryptedPsuAuthentication:
          description: Link to start authorisation with encrypted PSU authentication
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        updateEncryptedPsuAuthentication:
          description: Link to update encrypted PSU authentication
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        updateAdditionalEncryptedPsuAuthentication:
          description: Link to update additional encrypted PSU authentication
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        startAuthorisationWithAuthenticationMethodSelection:
          description: Link to start authorisation with authentication method selection
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        selectAuthenticationMethod:
          description: Link to select an authentication method
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        creditorNameConfirmation:
          description: Creditor name confirmation link for VOP services
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        self:
          description: >-
            Link to the payment initiation or consent resource created by this
            request
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        status:
          description: Link to retrieve the transaction status of the payment initiation
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        scaStatus:
          description: Link to retrieve the SCA status
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        account:
          description: Link to the resource providing details of one account
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        balances:
          description: Link to the resource providing the balance of a dedicated account
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        transactions:
          description: >-
            Link to the resource providing the transaction history of a
            dedicated account
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        cardAccount:
          description: Link to the resource providing the details of one card account
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        cardTransactions:
          description: >-
            Link to the resource providing the transaction history of a
            dedicated card account
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        transactionDetails:
          description: Link to the resource providing details of a dedicated transaction
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        first:
          description: Navigation link for paginated account reports - first page
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        next:
          description: Navigation link for paginated account reports - next page
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        previous:
          description: Navigation link for paginated account reports - previous page
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        last:
          description: Navigation link for paginated account reports - last page
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
        download:
          description: Download link for huge AIS data packages
          type: object
          allOf:
            - $ref: '#/components/schemas/HrefType'
          nullable: true
    TppMessage:
      description: TPP message information
      required:
        - category
        - code
      type: object
      properties:
        category:
          description: Category of the error
          enum:
            - ERROR
            - WARNING
          type: string
          example: ERROR
        code:
          description: Message code as defined by the Berlin Group
          type: string
          example: SERVICE_UNAVAILABLE
        path:
          description: Path of the field causing the error, if applicable
          type: string
          example: access.balances
          nullable: true
        text:
          description: Additional explaining text
          type: string
          example: The ASPSP server is currently unavailable
          nullable: true
    HrefType:
      description: Hyperlink reference
      required:
        - href
      type: object
      properties:
        href:
          description: Link URL
          type: string
          example: /v1/payments/sepa-credit-transfers/1234-payment-567

````