Form3 Direct Debits Reads API

openapi: 3.2.0
info:
  title: Form3 Public Direct Debits Reads API
  version: '1'
servers:
- url: https://api.form3.tech/v1
security:
- OAuth2: []
tags:
- name: DirectDebitsReads
paths:
  /transaction/directdebits:
    get:
      operationId: GetDirectdebits
      parameters:
      - description: Which page to select. page[number] * page[size] is restricted to less than 10,000.
        in: query
        name: page[number]
        required: false
        schema:
          type: string
          minimum: 0
          pattern: ^[A-z0-9]{4}$
      - description: Cursor for previous page (this is a base64-encoded UUID continuation token returned from the application and should not be manually generated, unless requesting the last page, where the value should be set to "end").
        in: query
        name: page[before]
        required: false
        schema:
          type: string
      - description: Cursor for next page (this is a base64-encoded UUID continuation token returned from the application and should not be manually generated, unless requesting the first page, where the value should be set to "start").
        in: query
        name: page[after]
        required: false
        schema:
          type: string
      - description: Number of items to select
        in: query
        name: page[size]
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 0
      - description: Filter by organisation id
        in: query
        name: filter[organisation_id]
        required: false
        schema:
          type: array
          items:
            format: uuid
            type: string
      - in: query
        name: filter[created_date_from]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[created_date_to]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[modified_date_from]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[modified_date_to]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[debtor_party.account_number]
        required: false
        schema:
          type: string
      - in: query
        name: filter[debtor_party.bank_id]
        required: false
        schema:
          type: string
      - in: query
        name: filter[beneficiary_party.account_number]
        required: false
        schema:
          type: string
      - in: query
        name: filter[beneficiary_party.bank_id]
        required: false
        schema:
          type: string
      - in: query
        name: filter[currency]
        required: false
        schema:
          type: string
      - in: query
        name: filter[payment_scheme]
        required: false
        schema:
          type: string
      - in: query
        name: filter[payment_type]
        required: false
        schema:
          type: string
      - in: query
        name: filter[processing_date_from]
        required: false
        schema:
          type: string
          format: date
      - in: query
        name: filter[processing_date_to]
        required: false
        schema:
          type: string
          format: date
      - in: query
        name: filter[clearing_id]
        required: false
        schema:
          type: string
      - in: query
        name: filter[admission.admission_date_from]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[admission.admission_date_to]
        required: false
        schema:
          type: string
          format: date-time
      - description: Filter by admission status
        in: query
        name: filter[admission.status]
        required: false
        schema:
          type: string
      - description: Filter by admission scheme status code
        in: query
        name: filter[admission.scheme_status_code]
        required: false
        schema:
          type: string
      - description: Filter by amount
        in: query
        name: filter[amount]
        required: false
        schema:
          type: string
      - description: Filter by reference
        in: query
        name: filter[reference]
        required: false
        schema:
          type: string
      - description: Filter by unique scheme id
        in: query
        name: filter[unique_scheme_id]
        required: false
        schema:
          type: string
      - in: query
        name: filter[submission.submission_date_from]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[submission.submission_date_to]
        required: false
        schema:
          type: string
          format: date-time
      - description: Filter by submission status
        in: query
        name: filter[submission.status]
        required: false
        schema:
          type: string
      - description: Filter by submission scheme status code
        in: query
        name: filter[submission.scheme_status_code]
        required: false
        schema:
          type: string
      - in: query
        name: filter[return_submission.submission_date_from]
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: filter[return_submission.submission_date_to]
        required: false
        schema:
          type: string
          format: date-time
      - description: Filter for direct debits containing all of the requested relationships
        in: query
        name: filter[relationships]
        required: false
        schema:
          type: array
          items:
            enum:
            - direct_debit_submissions
            - direct_debit_admissions
            - reversals
            - recalls
            - returns
            - decisions
            type: string
      - description: Filter for direct debits containing none of the requested relationships
        in: query
        name: filter[not_relationships]
        required: false
        schema:
          type: array
          items:
            enum:
            - direct_debit_submissions
            - direct_debit_admissions
            - reversals
            - recalls
            - returns
            - decisions
            type: string
      responses:
        200:
          description: List of direct debit details
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DirectDebitDetailsListResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitDetailsListResponse'
      summary: List direct debits
      tags:
      - DirectDebitsReads
      x-access:
      - Public
components:
  schemas:
    DirectDebitDecisionSubmissionStatus:
      enum:
      - accepted
      - released_to_gateway
      - delivery_confirmed
      - delivery_failed
      - submitted
      - validation_pending
      - validation_passed
      - queued_for_delivery
      type: string
      x-access:
      - Public
      x-parent: data.attributes
    UltimateEntity:
      properties:
        additional_address_line:
          description: Additional address line of the debtor/beneficiary address
          type: string
          x-length: 70
        address:
          description: Ultimate debtor/beneficiary address
          example:
          - Liverpool Customer Service Centre
          - Stevenson Way, Wavertree, L13 1NW
          items:
            type: string
          type: array
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: Max 2 lines of 70 text.
          x-omitempty: true
        birth_city:
          description: Ultimate debtor/beneficiary birth city
          example: PARIS
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: conditional
          x-description:
            sepa: If a Ultimate Beneficiary/Debtor Identification is used then only one of `organisation_identification`, `private_identification` or date and place of birth can be present.
          x-length: 35
        birth_country:
          description: Ultimate debtor/beneficiary birth country. ISO 3166 format country code
          example: FR
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: conditional
          x-description:
            sepa: If a Ultimate Beneficiary/Debtor Identification is used then only one of `organisation_identification`, `private_identification` or date and place of birth can be present.
          x-length: 2
        birth_date:
          description: Ultimate debtor/beneficiary birth date. Formatted ISO 8601 format YYYY-MM-DD
          example: '1973-01-31'
          format: date
          type:
          - string
          - 'null'
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: conditional
          x-description:
            sepa: If a Ultimate Beneficiary/Debtor Identification is used then only one of `organisation_identification`, `private_identification` or date and place of birth can be present.
        birth_province:
          description: Ultimate debtor/beneficiary birth province
          example: SOUTH SIDE
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: If a Ultimate Beneficiary/Debtor Identification is used then only one of `organisation_identification`, `private_identification` or date and place of birth can be present.
          x-length: 35
        building_number:
          description: Building number of the debtor/beneficiary address
          type: string
          x-length: 16
        city:
          description: City/Town of the Beneficiary address
          example: BRUSSELS
          type: string
          x-length: 30
        country:
          description: Country of ultimate debtor/beneficiary address. ISO 3166 format country code
          example: GB
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-length: 2
        country_of_residence:
          description: Country of residence of the ultimate beneficiary, ISO 3166 format country code
          example: UA
          type: string
          x-length: 2
        name:
          example: Jane Bond
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-length: 70
        organisation_identification:
          description: Organisation identification of an ultimate debtor/beneficiary, in the case that the ultimate debtor/beneficiary is an organisation and not a private person.
          example: ID1234656
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: The Identification can either be a BIC, BEI or Other Identification
          x-length: 35
        organisation_identification_code:
          description: The code that specifies the type of `organisation_identification`
          example: BIC
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: conditional
          x-description:
            sepa: If `organisation_identification` is specified, must be one of `BIC`, `BEI`, `BANK`, `CBID`, `CHID`, `CINC`, `COID`, `CUST`, `DUNS`, `EMPL`, `GS1G`, `SREN`, `SRET`, `TXID` or `Other`
          x-length: 5
        organisation_identification_issuer:
          description: Issuer of the `organisation_identification`
          example: NATIONAL WESTMINSTER BANK PLC
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: May only be present if `organisation_identification_code` is `Other`
          x-length: 35
        organisation_identification_scheme:
          description: The code that specifies the scheme of `organisation_identification`
          example: CustomerId
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: May only be present if `organisation_identification_code` is `Other`
          x-length: 35
        organisation_identifications:
          description: Array for additional ID(s) of ultimate organisation
          items:
            $ref: '#/components/schemas/BeneficiaryDebtorOrganisationIdentification'
          type: array
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: Array for additional ID(s) for ultimate organisation
          x-omitempty: true
        post_code:
          description: Post code of the debtor/beneficiary address
          type: string
          x-length: 16
        postal_address:
          $ref: '#/components/schemas/PostalAddress'
          description: Postal address of the ultimate debtor/beneficiary
          x-omitempty: true
        private_identification:
          $ref: '#/components/schemas/PrivateIdentification'
        province:
          description: Province of the debtor/beneficiary address
          type: string
          x-length: 35
        street_name:
          description: Street name of the debtor/beneficiary address
          example: Park Avenue
          type: string
          x-length: 70
      type: object
      x-access:
      - Public
    DirectDebitRecall:
      properties:
        attributes:
          properties:
            reason:
              description: Further explanation of the reason given in reason_code. Only evaluated for certain reason codes.
              example: Payment was a duplicate
              type: string
              x-omitempty: true
              x-parent: data.attributes
            reason_code:
              description: The reason for the recall. Has to be a valid [recall reason code](http://api-docs.form3.tech/api.html#enumerations-recall-reason-codes).
              example: DUPL
              type: string
              x-parent: data.attributes
            status:
              $ref: '#/components/schemas/RecallStatus'
          type: object
          x-parent: data
        created_on:
          format: date-time
          type:
          - string
          - 'null'
        id:
          description: Unique resource ID
          example: 7826c3cb-d6fd-41d0-b187-dc23ba928772
          format: uuid
          type: string
        modified_on:
          format: date-time
          type:
          - string
          - 'null'
        organisation_id:
          format: uuid
          type: string
        relationships:
          properties:
            direct_debit:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebit'
                  type: array
              type: object
            direct_debit_recall_admission:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebitRecallAdmission'
                  type: array
              type: object
            direct_debit_recall_submission:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebitRecallSubmission'
                  type: array
              type: object
          type: object
        type:
          description: Name of the resource type
          example: direct_debit_recalls
          pattern: ^[A-Za-z_]*$
          type: string
        version:
          description: Version number
          example: 0
          minimum: 0
          type: integer
      required:
      - id
      type: object
      x-access:
      - Public
    DirectDebitRecallAdmissionStatus:
      description: '[Status](http://draft-api-docs.form3.tech/api.html#enumerations-payment-admission-status) of the recall admission'
      enum:
      - confirmed
      - failed
      example: confirmed
      type: string
      x-access:
      - Public
      x-parent: data.attributes
    DirectDebitDecisionAdmissionStatus:
      enum:
      - confirmed
      - failed
      - pending
      type: string
      x-access:
      - Public
      x-parent: data.attributes
    DirectDebitDecisionSubmission:
      properties:
        attributes:
          properties:
            auto:
              default: false
              description: Indicates if the submission was created automatically by the system (`true`) or manually (`false`).
              type: boolean
              x-parent: data.attributes
            scheme_status_code:
              description: Scheme-specific status (if submission has been submitted to a scheme)
              example: '0000'
              type: string
              x-parent: data.attributes
            status:
              $ref: '#/components/schemas/DirectDebitDecisionSubmissionStatus'
            status_reason:
              description: Reason for submission failure if status is `delivery_failed`
              example: direct debit does not exist
              type: string
              x-parent: data.attributes
            submission_datetime:
              description: Date and time of the submission
              example: '2018-03-12T14:11:48.055Z'
              format: date-time
              readOnly: true
              type:
              - string
              - 'null'
              x-parent: data.attributes
          type: object
          x-parent: data
        created_on:
          format: date-time
          type:
          - string
          - 'null'
        id:
          description: Unique resource ID
          example: 2eae8187-7119-470d-abbb-33b11f21d3ad
          format: uuid
          type: string
        modified_on:
          format: date-time
          type:
          - string
          - 'null'
        organisation_id:
          description: Unique ID of the organisation this resource is created by
          example: 763e3cbb-da91-46fd-a0f8-169038a8324e
          format: uuid
          type: string
        relationships:
          properties:
            direct_debit:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebit'
                  type: array
              type: object
            direct_debit_decision:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebitDecision'
                  type: array
              type: object
          type: object
        type:
          description: Name of the resource type
          example: direct_debit_decision_submissions
          pattern: ^[A-Za-z_]*$
          type: string
        version:
          description: Version number
          example: 0
          minimum: 0
          type: integer
      required:
      - id
      - organisation_id
      type: object
      x-access:
      - Public
    DirectDebitRecallSubmissionStatus:
      enum:
      - accepted
      - released_to_gateway
      - delivery_confirmed
      - delivery_failed
      - submitted
      - validation_pending
      - validation_passed
      - queued_for_delivery
      - pending
      type: string
      x-access:
      - Public
      x-parent: data.attributes
    DirectDebitReturnAdmission:
      properties:
        attributes:
          properties:
            admission_datetime:
              format: date-time
              readOnly: true
              type: string
              x-parent: data.attributes
            scheme_status_code:
              type: string
              x-parent: data.attributes
            scheme_status_code_description:
              type: string
              x-parent: data.attributes
            settlement_cycle:
              minimum: 0
              type: integer
              x-parent: data.attributes
            settlement_date:
              format: date
              type:
              - string
              - 'null'
              x-parent: data.attributes
            status:
              $ref: '#/components/schemas/DirectDebitReturnAdmissionStatus'
          type: object
          x-parent: data
        created_on:
          format: date-time
          type:
          - string
          - 'null'
        id:
          format: uuid
          type: string
        modified_on:
          format: date-time
          type:
          - string
          - 'null'
        organisation_id:
          format: uuid
          type: string
        relationships:
          $ref: '#/components/schemas/DirectDebitReturnAdmissionRelationships'
        type:
          pattern: ^[A-Za-z_]*$
          type: string
        version:
          minimum: 0
          type: integer
      required:
      - id
      - organisation_id
      - attributes
      type: object
      x-access:
      - Public
    DirectDebitReversal:
      properties:
        attributes:
          properties:
            charges_amount:
              description: Only present when a DirectDebitReversal contains charges. SEPA only
              properties:
                amount:
                  description: The charges amount
                  example: '10.00'
                  pattern: ^[0-9]{0,20}(?:\.[0-9]{1,10})?$
                  type: string
                  x-parent: data.attributes.charges_amount
                currency:
                  description: ISO currency code for `amount`
                  example: EUR
                  type: string
                  x-parent: data.attributes.charges_amount
              type: object
              x-omitempty: true
              x-parent: data.attributes
            processing_date:
              description: 'Date on which the operation is to be debited from the debtor account. Formatted according to ISO 8601 format: YYYY-MM-DD.'
              example: '2015-02-12'
              format: date
              type:
              - string
              - 'null'
              x-parent: data.attributes
            reason:
              description: Further explanation of the reason given in reason_code. Only evaluated for certain reason codes.
              example: Direct debit was a duplicate
              type: string
              x-omitempty: true
              x-parent: data.attributes
            reason_code:
              description: The reason for the direct debit reversal. Has to be a valid [reversal reason code](http://api-docs.form3.tech/api.html#enumerations-reversal-reason-codes).
              example: AM05
              type: string
              x-parent: data.attributes
            reversal_amount:
              description: SEPA only
              properties:
                amount:
                  description: Full amount of the Direct Debit Reversal including charges
                  example: '10.00'
                  pattern: ^[0-9]{0,20}(?:\.[0-9]{1,10})?$
                  type: string
                  x-parent: data.attributes.reversal_amount
                currency:
                  description: ISO currency code for `amount`
                  example: EUR
                  type: string
                  x-parent: data.attributes.reversal_amount
              type: object
              x-omitempty: true
              x-parent: data.attributes
            scheme_processing_date:
              description: 'Date on which the operation is processed by the scheme. Formatted according to ISO 8601 format: YYYY-MM-DD. Only used if different from `processing_date`.'
              example: '2015-02-12'
              format: date
              type:
              - string
              - 'null'
              x-parent: data.attributes
          type: object
          x-parent: data
        created_on:
          format: date-time
          type:
          - string
          - 'null'
        id:
          format: uuid
          type: string
        modified_on:
          format: date-time
          type:
          - string
          - 'null'
        organisation_id:
          format: uuid
          type: string
        relationships:
          properties:
            direct_debit:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebit'
                  type: array
              type: object
            direct_debit_reversal_admission:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebitReversalAdmission'
                  type: array
              type: object
            direct_debit_reversal_submission:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebitReversalSubmission'
                  type: array
              type: object
          type: object
        type:
          pattern: ^[A-Za-z_]*$
          type: string
        version:
          minimum: 0
          type: integer
      required:
      - id
      - organisation_id
      type: object
      x-access:
      - Public
    BeneficiaryDebtorOrganisationIdentification:
      properties:
        identification:
          description: Another ID of the organisation
          example: H7FNTJ4851HG0EXQ1Z70
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: Another ID of the organisation
          x-length: 35
          x-omitempty: true
        identification_code:
          description: Code for the type of other ID of organisation
          example: LEI
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: Code for the type of other ID of organisation
          x-length: 5
          x-omitempty: true
        identification_issuer:
          description: Issuer of the other ID of organisation
          example: London Stock Exchange
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: Issuer of the other ID of organisation
          x-length: 35
          x-omitempty: true
        identification_scheme:
          description: Custom internal code for the type of other ID of organisation
          example: Custom code
          type: string
          x-availability:
            get:
              sepa: sometimes
            post:
              sepa: optional
          x-description:
            sepa: Custom internal code for the type of other ID of organisation
          x-length: 35
          x-omitempty: true
      type: object
      x-access:
      - Public
    DirectDebitSubmissionStatus:
      enum:
      - accepted
      - released_to_gateway
      - delivery_confirmed
      - delivery_failed
      - submitted
      - pending
      - validation_pending
      - validation_passed
      - queued_for_delivery
      type: string
      x-access:
      - Public
      x-parent: data.attributes
    DirectDebitReversalSubmission:
      properties:
        attributes:
          properties:
            destination_gateway:
              type: string
              x-parent: data.attributes
            scheme_status_code:
              type: string
              x-parent: data.attributes
            scheme_status_code_description:
              type: string
              x-parent: data.attributes
            status:
              $ref: '#/components/schemas/DirectDebitReversalSubmissionStatus'
            status_reason:
              type: string
              x-parent: data.attributes
            submission_datetime:
              format: date-time
              readOnly: true
              type: string
              x-parent: data.attributes
            transaction_start_datetime:
              format: date-time
              readOnly: true
              type: string
              x-parent: data.attributes
          type: object
          x-parent: data
        created_on:
          format: date-time
          type:
          - string
          - 'null'
        id:
          format: uuid
          type: string
        modified_on:
          format: date-time
          type:
          - string
          - 'null'
        organisation_id:
          format: uuid
          type: string
        relationships:
          properties:
            direct_debit:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebit'
                  type: array
              type: object
            direct_debit_reversal:
              properties:
                data:
                  items:
                    $ref: '#/components/schemas/DirectDebitReversal'
                  type: array
              type: object
          type: object
        type:
          pattern: ^[A-Za-z_]*$
          type: string
        version:
          minimum: 0
          type: integer
      required:
      - id
      - organisation_id
      type: object
      x-access:
      - Public
    DirectDebitMandate:
      properties:
        id:
          format: uuid
          type: string
        type:
          pattern: ^[A-Za-z_]*$
          type: string
      type: object
      x-access:
      - Public
    DirectDebitReturn:
      properties:
        attributes:
          properties:
            charges_amount:
              $ref: '#/components/schemas/CurrencyAndAmount'
              x-omitempty: true
              x-parent: data.attributes
            clearing_id:
              description: Unique identifier for organisations collecting payments
              example: '123456'
              type: string
              x-parent: data.attributes
            compensation_amount:
              $ref: '#/components/schemas/CurrencyAndAmount'
              x-omitempty: true
              x-parent: data.attributes
            processing_date:
              description: 'Date on which the operation is to be debited from the debtor account. Formatted according to ISO 8601 format: YYYY-MM-DD.'
              example: '2015-02-12'
              format: date
              type:
              - string
              - 'null'
              x-parent: data.attributes
            return_amount:
              $ref: '#/components/schemas/CurrencyAndAmount'
              x-omitempty: true
              x-parent: data.attributes
            return_code:
              type: string
              x-parent: data.attributes
            return_initiator:
              enum:
              - BANK
              - CUSTOMER
              type: string
              x-parent: data.attributes
            scheme_processing_date:
              description: 'Date on which the operation is processed by the scheme. Formatted according to ISO 8601 format: YYYY-MM-DD. Only used if different from `processing_date`.'
              example: '2015-02-12'
              format: date
              type:
              - string
              - 'null'
              x-parent: data.attributes
            scheme_transaction_id:
              type: string
              x-parent: data.attributes
            settlement:
              $ref: '#/components/schemas/Settlement'
              x-omitempty: true
              x-parent: data.attributes
          type: object
          x-parent: data
        created_on:
          format: date-time
          type:
          - string
          - 'null'
        id:
          format: uuid
          type: string
        modified_on:
          format: date-time
          t

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/form3/refs/heads/main/openapi/form3-directdebitsreads-api-openapi.yml