Modulr Direct Debits API

openapi: 3.2.0
info:
  title: Modulr Direct Debits API
  description: Modulr API
  license:
    name: © Modulr Finance
    url: https://www.modulrfinance.com
  version: '1.0'
servers:
- url: https://api-sandbox.modulrfinance.com/api-sandbox-token
security:
- modulo_security: []
tags:
- name: Direct Debits
  description: Direct Debit operations
paths:
  /mandates/{mandateId}/collectionschedules:
    post:
      tags:
      - Direct Debits
      summary: Create the collection schedule for the given mandate-id.
      description: Creates a Direct Debit collection schedule; the agreed to framework for the collections for the given mandate-id. This could be a single collection or multiple and includes the frequency and amounts of the planned payments.
      operationId: createCollectionSchedule
      parameters:
      - name: mandateId
        in: path
        description: Id of mandate to create collection for.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebit.CreateCollectionScheduleRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebit.CollectionScheduleResponse'
        '400':
          description: Validation errors
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /mandates/{mandateId}/cancel:
    post:
      tags:
      - Direct Debits
      summary: Cancel Mandate for given mandate-id.
      description: Cancel Mandate for given mandate-id.
      operationId: cancelMandate
      parameters:
      - name: mandateId
        in: path
        description: Id of Mandate to cancel.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebit.CancelMandateRequest'
        required: true
      responses:
        '200':
          description: Mandate cancelled.
        '400':
          description: Validation errors.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /mandates/bulk-create:
    post:
      tags:
      - Direct Debits
      summary: Bulk request of Direct Debit mandates for the given account-id.
      operationId: createBulkMandate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebit.BulkCreateMandateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebit.BulkCreateResponse'
        '400':
          description: Validation errors.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /mandates/bulk-cancel:
    post:
      tags:
      - Direct Debits
      summary: Bulk mandate cancellation request for the given account-id.
      operationId: cancelBulkMandate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebit.BulkCancelMandateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebit.BulkCancelMandateResponse'
        '400':
          description: Validation errors.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /collectionschedules/{collectionScheduleId}/cancel:
    post:
      tags:
      - Direct Debits
      summary: Cancel a Direct Debit collection schedule for the given collection-id.
      operationId: cancelCollectionSchedule
      parameters:
      - name: collectionScheduleId
        in: path
        description: Id of the collectionSchedule to cancel
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: CollectionSchedule cancelled
        '400':
          description: Validation errors
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /collections/{collectionId}/cancel:
    post:
      tags:
      - Direct Debits
      summary: Cancel a Direct Debit collection for the given collection-id.
      operationId: cancelCollection
      parameters:
      - name: collectionId
        in: path
        description: Id of the collection to cancel
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Collection cancelled
        '400':
          description: Validation errors
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /collection/{collectionId}/represent:
    post:
      tags:
      - Direct Debits
      summary: Represent collection for given collection id
      description: Represent collection for given collection id
      operationId: representCollection
      parameters:
      - name: collectionId
        in: path
        description: Id of collection to represent
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Collection represented
        '400':
          description: Validation errors.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /accounts/{accountId}/mandates:
    post:
      tags:
      - Direct Debits
      summary: Create a Direct Debit mandate for the given account-id.
      description: Setting up a Mandate is the first step in creating a Direct Debit. You can only set up scheduled payments ('collections') after there is a Mandate created with the details of the payee.
      operationId: createMandate
      parameters:
      - name: accountId
        in: path
        description: Id of account to create Direct Debit for.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebit.CreateMandateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebit.Mandate'
        '400':
          description: Validation errors
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /reconciliations:
    get:
      tags:
      - Direct Debits
      summary: Get Reconciliations based on search criteria.
      description: Use this endpoint to get a list of Reconciliations for a given account and date.
      operationId: getReconciliations
      parameters:
      - name: accountId
        in: query
        description: Id(s) of account to fetch Reconciliations for.
        required: true
        style: form
        explode: true
        schema:
          type: string
          description: Id(s) of account to fetch Reconciliations for.
      - name: collectionDate
        in: query
        description: Reconciliation entry for date.
        required: true
        style: form
        explode: true
        schema:
          type: string
          format: date
          description: Reconciliation entry for date.
      - name: sortField
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: (id|createdDate)
      - name: sortOrder
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: (asc|desc)
      - name: size
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          maximum: 500
      - name: page
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/directdebit.ReconciliationPageResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /mandates:
    get:
      tags:
      - Direct Debits
      summary: Get Mandates based on search criteria.
      description: If trying to find one or several particular mandates, then you can narrow down your search by using the filters available here. These include the mandate id, either the submitted or created date range, the account name on the mandate, etc...
      operationId: getMandates
      parameters:
      - name: id
        in: query
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/directdebit.id'
      - name: accountId
        in: query
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/directdebit.accountId'
      - name: q
        in: query
        description: Query parameter. ID, name or reference of mandate to search for
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Query parameter. ID, name or reference of mandate to search for
      - name: fromCreatedDate
        in: query
        description: Mandates created on or after this date.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Mandates created on or after this date.
      - name: toCreatedDate
        in: query
        description: Mandates created on or before this date.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Mandates created on or before this date.
      - name: fromSubmittedDate
        in: query
        description: Mandates submitted on or after this date.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Mandates submitted on or after this date.
      - name: toSubmittedDate
        in: query
        description: Mandates submitted on or before this date.
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Mandates submitted on or before this date.
      - name: status
        in: query
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/directdebit.status'
      - name: name
        in: query
        description: Account Name on the Mandate
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Account Name on the Mandate
      - name: reference
        in: query
        description: reference of the Mandate
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: reference of the Mandate
      - name: externalReference
        in: query
        description: externalReference of the Mandate
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: externalReference of the Mandate
      - name: bulkCreateRequestId
        in: query
        description: Bulk create request ID
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Bulk create request ID
      - name: bulkCancelRequestId
        in: query
        description: Bulk cancel request ID
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Bulk cancel request ID
      - name: sortField
        in: query
        description: Sort by field
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Sort by field
          pattern: id|createdDate|submittedDate|status|name|reference|externalReference
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: Sort order
          enum:
          - ASC
          - DESC
          example: asc
        example: asc
      - name: page
        in: query
        description: Page to fetch (zero-indexed)
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          description: Page to fetch (zero-indexed)
          minimum: 0
      - name: size
        in: query
        description: Size of page to fetch.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          description: Size of page to fetch.
          exclusiveMinimum: 0
          maximum: 500
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/directdebit.MandatePageResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /indemnity-claims:
    get:
      tags:
      - Direct Debits
      summary: Get Indemnity Claims based on search criteria
      description: Returns a list of Indemnity Claim Advice's based on the parameters provided.
      operationId: getIndemnityClaims
      parameters:
      - name: accountId
        in: query
        description: Collection Account Id
        required: true
        style: form
        explode: true
        schema:
          type: string
          description: Collection Account Id
      - name: indemnityClaimIds
        in: query
        description: List of Indemnity Claim Id's
        required: false
        style: form
        explode: true
        schema:
          type: array
          description: List of Indemnity Claim Id's
          example: ICC1234567
          items:
            type: string
            description: List of Indemnity Claim Id's
            example: ICC1234567
        example: ICC1234567
      - name: ddicReferences
        in: query
        description: List of DDIC references, these are references related to the claim itself. Must start with DDIC. This is different to the reference used on the mandate, it is generated by the claim originator
        required: false
        style: form
        explode: true
        schema:
          type: array
          description: List of DDIC references, these are references related to the claim itself. Must start with DDIC. This is different to the reference used on the mandate, it is generated by the claim originator
          example: DDICreference
          items:
            type: string
            description: List of DDIC references, these are references related to the claim itself. Must start with DDIC. This is different to the reference used on the mandate, it is generated by the claim originator
            example: DDICreference
        example: DDICreference
      - name: serviceUserReferences
        in: query
        description: List of mandate/ddi references that claims are related to.
        required: false
        style: form
        explode: true
        schema:
          type: array
          description: List of mandate/ddi references that claims are related to.
          items:
            type: string
            description: List of mandate/ddi references that claims are related to.
      - name: statuses
        in: query
        description: List of statuses that claims are in.
        required: false
        style: form
        explode: true
        schema:
          type: array
          description: List of statuses that claims are in.
          items:
            type: string
            description: List of statuses that claims are in.
            enum:
            - NEW
            - CANCELLED
            - SETTLED
      - name: sortField
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: (id|createdDate)
      - name: sortOrder
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: (asc|desc)
      - name: size
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          maximum: 500
      - name: page
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebit.IndemnityClaimPageResponse'
        '400':
          description: Validation Errors
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /indemnity-claims/{indemnityClaimId}:
    get:
      tags:
      - Direct Debits
      summary: Get an Indemnity Claim for a given id
      description: Returns a singular Indemnity Claim based on the ID supplied in the path.
      operationId: getIndemnityClaim
      parameters:
      - name: indemnityClaimId
        in: path
        description: Id of the indemnityClaim
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebit.IndemnityClaimResponse'
        '400':
          description: Validation Errors
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: No Indemnity Claim found matching that ID
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /collectionschedules:
    get:
      tags:
      - Direct Debits
      summary: Get all collectionschedules for a mandate
      description: By supplying the mandate id you can view all information regarding the collection schedules linked to that mandate.
      operationId: getCollectionSchedules
      parameters:
      - name: mandateId
        in: query
        description: Mandate Id to fetch collections for.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: sortField
        in: query
        description: Sort by field
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: id|createdDate|payment|status|externalReference
      - name: sortOrder
        in: query
        description: Sort order
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: asc|desc
      - name: page
        in: query
        description: Page to fetch (zero-indexed)
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: Size of page to fetch.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 20
          maximum: 500
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/directdebit.DirectDebitPageResponseCollectionScheduleResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /collections:
    get:
      tags:
      - Direct Debits
      summary: Get all collection activities of an account
      description: 'Once a collection schedule is set up, any past collections (whether successful or not) can be retrieved.

        This endpoint supports only paginated responses with the default page size of 20 (min 1, max 500).

        '
      operationId: getCollections
      parameters:
      - name: accountId
        in: query
        description: Account Id to fetch collections items for.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: mandateId
        in: query
        description: Id of mandate whose the collection to fetch.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: type
        in: query
        description: type of collection to fetch
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: startDate
        in: query
        description: Collection activities happened on or after this date
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: endDate
        in: query
        description: Collection item activities happened on or before this date
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sortOrder
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: (asc|desc)
      - name: sortField
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          pattern: (id|createdDate|activityDate)
      - name: page
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: size
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          maximum: 500
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/directdebit.DirectDebitPageResponseCollection'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebit.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    directdebit.IndemnityClaimResponse:
      type: object
      properties:
        id:
          type: string
        accountBid:
          type: string
        serviceUserReference:
          type: string
        ddicReference:
          type: string
        reasonCode:
          type: string
          enum:
          - AMOUNT_OR_DATE_DIFFER
          - NO_ADVANCE_NOTICE
          - DDI_CANCELLED_BY_BANK
          - DDI_CANCELLED_WITH_SERVICE_USER
          - NO_INSTRUCTION
          - INVALID_SIGNATURE
          - SERVICE_USER_REQUEST
          - SERVICE_USER_NAME_DISPUTED
        amount:
          type: number
        payingBankName:
          type: string
        payingBankSortCode:
          type: string
        payingBankAccountNumber:
          type: string
        payingBankServiceUserNumber:
          type: string
        statusHistory:
          type: array
          items:
            $ref: '#/components/schemas/directdebit.IndemnityClaimStatusHistoryResponse'
        status:
          type: string
          enum:
          - NEW
          - CANCELLED
          - SETTLED
        directDebits:
          type: array
          items:
            $ref: '#/components/schemas/directdebit.IndemnityClaimDirectDebitResponse'
    directdebit.MessageResponse:
      type: object
      properties:
        field:
          type: string
        code:
          type: string
          enum:
          - GENERAL
          - BUSINESSRULE
          - MFASTATUS
          - MFAERROR
          - MFATIMEOUT
          - MFADEVICEMM
          - MFAMESSAGEINVALID
          - NOTFOUND
          - DUPLICATE
          - INVALID
          - CONNECTION
          - RETRY
          - RATELIMIT
          - PERMISSION
          - NOTACCEPTABLE
          - MFAVERIFICATION
          - TOKENEXPIRED
        errorCode:
          type: string
        message:
          type: string
        sourceService:
          type: string
    directdebit.Collection:
      type: object
      properties:
        id:
          type: string
          description: Unique id for a direct-debit collection
          example: K000100100
        mandateId:
          type: string
          description: Unique id for direct-debit mandate.
          example: G0000001
        collectionScheduleId:
          type: string
          description: Unique id for direct-debit collection schedule for which triggered the collection
          example: Q9200001
        activityDate:
          type: string
          description: collection or reportRaised date for indemnity???
          example: '2018-01-09'
        amount:
          type: number
          description: Amount of the collection payment
          example: '100.00'
        type:
          type: string
          description: 'Type of the collection activity.  Can be one of '
          example: COLLECTION
        payerName:
          type: string
          description: Name of the payer
          example: Mr John Doe
        status:
          type: string
          description: 'Status of the collection.  Can be one of '
          example: FAILED
        message:
          type: string
          description: Failure description of the payment activity
          example: Instruction Cancelled
        originalActivityDate:
          type: string
          description: The original scheduled date for a payment to be collected
          example: '2018-01-09'
        reconciliationDate:
          type: string
          description: The reconciled date for a payment to be collected
          example: '2018-01-09'
        reconciliationReference:
          type: string
          description: The reconciled reference that links to a payment
          example: '2018-01-09'
        ddiReference:
          type: string
          description: 'collectionReference - if present - is appended to the original DDI reference

            (used during mandate creation - referred to as core reference) for the specified scheduled collection

            without altering the original mandate core reference. This will be visible to the payer on their account.

            The reference and collectionReference combined have 18 

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modulr/refs/heads/main/openapi/modulr-direct-debits-api-openapi.yml