IF Direct Debit Payments API

openapi: 3.2.0
info:
  title: Outgoing Transfer Direct Debit Payments API
  description: Operations for Outgoing Transfers
  version: '1'
servers:
- url: https://sandbox-api.integrated.finance/v1/{instanceId}
  description: Sandbox
  variables: {}
- url: https://api.integrated.finance/v1/{instanceId}
  description: Production
  variables: {}
tags:
- name: Direct Debit Payments
paths:
  /direct-debit-payments:
    get:
      tags:
      - Direct Debit Payments
      summary: List Direct Debit Payments
      operationId: direct-debit-payments.list
      responses:
        '200':
          description: Direct debit payment list returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitPaymentListResponse'
  /direct-debit-payments/{id}:
    get:
      tags:
      - Direct Debit Payments
      summary: Get a Direct Debit Payment
      operationId: direct-debit-payments.get
      parameters:
      - name: id
        in: path
        description: ID of the direct debit payment in UUID format
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Direct debit payment returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitPaymentGetResponse'
    patch:
      tags:
      - Direct Debit Payments
      summary: Update a Direct Debit Payment
      operationId: direct-debit-payments.update
      parameters:
      - name: id
        in: path
        description: ID of the direct debit payment in UUID format
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectDebitPaymentUpdateRequestBody'
        required: true
      responses:
        '202':
          description: Direct debit payment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitPaymentUpdateResponse'
components:
  schemas:
    DirectDebitPaymentUpdateDataContainer:
      required:
      - directDebitPayment
      type: object
      properties:
        directDebitPayment:
          $ref: '#/components/schemas/DirectDebitPaymentResource'
    DirectDebitPaymentUpdateConnectContainer:
      type: object
      properties:
        type:
          type: string
        serviceProvider:
          type: string
    ConnectMethod:
      type: string
      enum:
      - built-in
      - plug-in
    DirectDebitPaymentReturnReason:
      type: string
      enum:
      - account-closed
      - advance-notice-disputed
      - amount-not-matched
      - amount-not-yet-due
      - insufficient-balance
      - mandate-not-active
      - no-account
      - no-mandate
      - presentation-overdue
      - service-user-not-match
    DirectDebitPaymentUpdateCommandInput:
      required:
      - returnContext
      type: object
      properties:
        returnContext:
          $ref: '#/components/schemas/DirectDebitPaymentReturnContextUpdateCommandInput'
    DirectDebitPaymentGetResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/DirectDebitPaymentGetWorkflowContainer'
        data:
          $ref: '#/components/schemas/DirectDebitPaymentGetDataContainer'
        connect:
          $ref: '#/components/schemas/DirectDebitPaymentGetConnectContainer'
        metadata:
          $ref: '#/components/schemas/DirectDebitPaymentGetMetadataContainer'
      description: response model
    DirectDebitPaymentGetWorkflowContainer:
      type: object
      description: workflow container
    DirectDebitPaymentListDataContainer:
      type: object
      properties:
        directDebitPayment:
          $ref: '#/components/schemas/DirectDebitPaymentResourceQueryInput'
        directDebitPayments:
          type: array
          description: direct debit payment list
          readOnly: true
          items:
            $ref: '#/components/schemas/DirectDebitPaymentResource'
    DirectDebitPaymentConnectionResource:
      type: object
      properties:
        id:
          type: string
        reference:
          type: string
        serviceProvider:
          type: string
        status:
          $ref: '#/components/schemas/ThirdPartyDirectDebitPaymentStatus'
        state:
          $ref: '#/components/schemas/ServiceProviderConnectionState'
        method:
          $ref: '#/components/schemas/ConnectMethod'
        error:
          $ref: '#/components/schemas/ConnectionErrorResource'
      description: Direct Debit Payment Connection Resource Object
    Owner:
      type: string
      enum:
      - organization
      - client
    DirectDebitPaymentReturnContextUpdateCommandInput:
      required:
      - reason
      - status
      type: object
      properties:
        status:
          type: string
          description: processing to request a return; completed and failed are set by the service provider
          enum:
          - processing
        reason:
          $ref: '#/components/schemas/DirectDebitPaymentReturnReason'
      description: return request of the direct debit payment
    DirectDebitPaymentGetConnectContainer:
      type: object
      properties:
        connection:
          $ref: '#/components/schemas/DirectDebitPaymentConnectionResource'
    ErrorOrigin:
      type: string
      enum:
      - customer
      - platform
      - provider
    ServiceProviderConnectionState:
      type: string
      enum:
      - pending
      - creation-in-progress
      - update-in-progress
      - dependency-completed
      - completed-up-to-date
      - completed-outdated
      - dependency-failed
      - creation-failed
    DirectDebitPaymentResource:
      type: object
      properties:
        id:
          type: string
          description: ID of the direct debit payment in UUID format
          format: uuid
          readOnly: true
        owner:
          $ref: '#/components/schemas/Owner'
        clientId:
          type: string
          description: ID of client in UUID format
          format: uuid
          readOnly: true
        mandateId:
          type: string
          description: ID of the direct debit mandate the payment is collected under, in UUID format
          format: uuid
          readOnly: true
        accountId:
          type: string
          description: ID of the payer account in UUID format
          format: uuid
          readOnly: true
        scheme:
          $ref: '#/components/schemas/TransferScheme'
        status:
          $ref: '#/components/schemas/DirectDebitPaymentStatus'
        amount:
          type: number
          description: amount of the collection in the payer account currency
          readOnly: true
        currency:
          maxLength: 3
          minLength: 3
          type: string
          description: ISO 4217 currency code of the payer account
          readOnly: true
        transferDate:
          type: string
          description: settlement date of the collection
          format: date
          readOnly: true
        returnContext:
          $ref: '#/components/schemas/DirectDebitPaymentReturnContext'
        outgoingTransferId:
          type: string
          description: ID of the outgoing transfer that charges the payer account, in UUID format
          format: uuid
          readOnly: true
        incomingTransferId:
          type: string
          description: ID of the incoming transfer that credits the returned funds back to the payer account, in UUID format; filled after the return completes, only when the payer account had been charged
          format: uuid
          readOnly: true
        attributes:
          $ref: '#/components/schemas/AttributeMap'
      description: Direct Debit Payment Resource Object
    DirectDebitPaymentListMetadataContainer:
      required:
      - page
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageMetadata'
      description: metadata container
    DirectDebitPaymentUpdateWorkflow:
      type: string
      enum:
      - direct
      - client.direct
    DirectDebitPaymentResourceQueryInput:
      type: object
      properties:
        clientId:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        mandateId:
          type: string
          format: uuid
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/DirectDebitPaymentStatus'
        owner:
          $ref: '#/components/schemas/Owner'
    AttributeMap:
      type: object
      description: outgoing transfer attributes
    DirectDebitPaymentUpdateRequestBody:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateWorkflowContainer'
        data:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateRequestBodyDataContainer'
        connect:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateConnectContainer'
        metadata:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateMetadataContainer'
      description: request model
    DirectDebitPaymentListResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/DirectDebitPaymentListWorkflowContainer'
        data:
          $ref: '#/components/schemas/DirectDebitPaymentListDataContainer'
        connect:
          $ref: '#/components/schemas/DirectDebitPaymentListConnectContainer'
        metadata:
          $ref: '#/components/schemas/DirectDebitPaymentListMetadataContainer'
      description: response model
    ConnectionErrorResource:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
        origin:
          $ref: '#/components/schemas/ErrorOrigin'
        code:
          type: string
        message:
          type: string
        attributes:
          type: object
          additionalProperties:
            type: string
    DirectDebitPaymentUpdateWorkflowContainer:
      required:
      - code
      type: object
      properties:
        code:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateWorkflow'
      description: workflow container
    DirectDebitPaymentStatus:
      type: string
      description: 'status of the collection: pending, completed (payer account charged), failed (payer account not charged); a return is tracked on returnContext'
      enum:
      - completed
      - failed
      - pending
    DirectDebitPaymentGetDataContainer:
      type: object
      properties:
        directDebitPayment:
          $ref: '#/components/schemas/DirectDebitPaymentResource'
    ThirdPartyDirectDebitPaymentStatus:
      type: string
      enum:
      - completed
      - failed
      - pending
      - returning
      - returned
    DirectDebitPaymentListConnectContainer:
      type: object
    ErrorCategory:
      type: string
      enum:
      - functional
      - technical
    DirectDebitPaymentUpdateRequestBodyDataContainer:
      required:
      - directDebitPayment
      type: object
      properties:
        directDebitPayment:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateCommandInput'
      description: data container of the update request
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        size:
          minimum: 0
          type: integer
          description: number of elements in this page
          format: int32
        number:
          minimum: 0
          type: integer
          description: index of page starting from 0
          format: int32
        totalElements:
          minimum: 0
          type: integer
          description: total number of elements in all of the pages
          format: int64
          readOnly: true
        totalPages:
          minimum: 0
          type: integer
          description: number of total pages
          format: int32
          readOnly: true
    DirectDebitPaymentUpdateMetadataContainer:
      type: object
      description: metadata container
    TransferScheme:
      type: string
      description: transfer scheme depending on the scope of the transfer
      enum:
      - swift
      - local
      - sepa
      - sepa-instant
      - sepa-target-2
      - sepa-target-2-pacs009
      - sepa-direct-debit
      - chaps
      - bacs
      - faster-payments
      - faster-payments-poo
      - npp
      - becs
      - rits
      - tips-dkk
      - intradag
      - t2-dkk
      - rix-inst
      - rix-rtgs
      - swish
      - nbo
      - viber
      - sic-inst
      - sic-ach
      - sic-rtgs
      - chats
      - ach
      - wire
      - eft
    DirectDebitPaymentListWorkflowContainer:
      type: object
      description: workflow container
    DirectDebitPaymentReturnContext:
      type: object
      properties:
        enabled:
          type: boolean
        cutOffDateTime:
          type: string
          format: date-time
        reason:
          $ref: '#/components/schemas/DirectDebitPaymentReturnReason'
        status:
          $ref: '#/components/schemas/DirectDebitPaymentReturnStatus'
      description: return state of the payment; request a return by setting status to processing together with a reason
    DirectDebitPaymentGetMetadataContainer:
      type: object
      description: metadata container
    DirectDebitPaymentReturnStatus:
      type: string
      enum:
      - processing
      - completed
      - failed
    DirectDebitPaymentUpdateResponse:
      required:
      - connect
      - data
      - metadata
      - workflow
      type: object
      properties:
        workflow:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateWorkflowContainer'
        data:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateDataContainer'
        connect:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateConnectContainer'
        metadata:
          $ref: '#/components/schemas/DirectDebitPaymentUpdateMetadataContainer'
      description: response model
x-provenance:
  method: searched
  source: https://developer.integrated.finance/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.integrated.finance/reference/beneficiariesbankaccountscreate.md
  - https://developer.integrated.finance/reference/beneficiariesbankaccountsget.md
  - https://developer.integrated.finance/reference/beneficiariesbankaccountslist.md
  - https://developer.integrated.finance/reference/beneficiariesbankaccountsrequirementsget.md
  - https://developer.integrated.finance/reference/beneficiariesbankaccountsupdate.md
  - https://developer.integrated.finance/reference/beneficiariescreate.md
  - https://developer.integrated.finance/reference/beneficiariesget.md
  - https://developer.integrated.finance/reference/beneficiarieslist.md
  - https://developer.integrated.finance/reference/beneficiariesupdate.md
  - https://developer.integrated.finance/reference/beneficiary-verificationscreate.md
  - https://developer.integrated.finance/reference/direct-debit-mandatescreate.md
  - https://developer.integrated.finance/reference/direct-debit-mandatesget.md
  - https://developer.integrated.finance/reference/direct-debit-mandateslist.md
  - https://developer.integrated.finance/reference/direct-debit-mandatesupdate.md
  - https://developer.integrated.finance/reference/direct-debit-paymentsget.md
  - https://developer.integrated.finance/reference/direct-debit-paymentslist.md
  - https://developer.integrated.finance/reference/direct-debit-paymentsupdate.md
  - https://developer.integrated.finance/reference/outgoing-transferscompliance-checkget.md
  - https://developer.integrated.finance/reference/outgoing-transferscompliance-checkupdate.md
  - https://developer.integrated.finance/reference/outgoing-transferscreate.md
  - https://developer.integrated.finance/reference/outgoing-transfersdate-metadataget.md
  - https://developer.integrated.finance/reference/outgoing-transfersdate-metadataget_1.md
  - https://developer.integrated.finance/reference/outgoing-transfersget.md
  - https://developer.integrated.finance/reference/outgoing-transferslist.md
  - https://developer.integrated.finance/reference/outgoing-transfersupdate.md
  merge:
    pages: 25
    deduped: 237
    conflicts_kept_first: 0