openapi: 3.2.0
info:
  title: Modulr Direct Debit Outbound Mandate Operations 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 Debit Outbound Mandate Operations
paths:
  /directdebits/reject:
    post:
      tags:
      - Direct Debit Outbound Mandate Operations
      summary: Reject Collection
      description: Reject Collection
      operationId: rejectCollection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebitoutbound.CollectionRejectRequest'
        required: true
      responses:
        '200':
          description: Collection has been rejected
        '400':
          description: Collection has not been rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebitoutbound.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /directdebits/cancel:
    post:
      tags:
      - Direct Debit Outbound Mandate Operations
      summary: Cancel a specific Mandate
      description: Used to request the cancellation of a Mandate.
      operationId: cancelDdosMandate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/directdebitoutbound.MandateCancelRequest'
        required: true
      responses:
        '200':
          description: Mandate was successfully cancelled
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebitoutbound.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /directdebits/enquire/{accountId}:
    get:
      tags:
      - Direct Debit Outbound Mandate Operations
      summary: Retrieve all Mandates for an account
      description: Used to get all the Mandates for a specific account.
      operationId: retrieveMandates
      parameters:
      - name: accountId
        in: path
        description: Account Id
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: All Mandates were successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directdebitoutbound.EnquiryMandatesResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/directdebitoutbound.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    directdebitoutbound.MandateCancelRequest:
      type: object
      description: Details of the Mandate Cancel Request
      properties:
        mandateId:
          type: string
          description: Mandate Id
          minLength: 1
        accountId:
          type: string
          description: Account Id
          minLength: 1
        cancellationCode:
          type: string
          description: Cancellation Code
          enum:
          - REFER_TO_PAYER
          - INSTRUCTION_CANCELLED_BY_PAYER
          - PAYER_DECEASED
          - ACCOUNT_TRANSFERRED
          - ACCOUNT_CLOSED
          - ACCOUNT_OR_INSTRUCTION_TRANSFERRED
          - ADVANCE_NOTICE_DISPUTED
          - INSTRUCTION_AMENDED
          - INSTRUCTION_REINSTATED
        merchantNumber:
          type: string
          description: Merchant Number
          minLength: 1
      required:
      - accountId
      - cancellationCode
      - mandateId
      - merchantNumber
    directdebitoutbound.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
    directdebitoutbound.EnquiryMandatesResponse:
      type: object
      properties:
        accountId:
          type: string
          description: Account Id
        mandatesList:
          type: array
          description: List of Mandates
          items:
            $ref: '#/components/schemas/directdebitoutbound.EnquiryMandateResponse'
      required:
      - accountId
      - mandatesList
    directdebitoutbound.EnquiryMandateResponse:
      type: object
      properties:
        mandateId:
          type: string
          description: Mandate Id
        merchantNumber:
          type: string
          description: Merchant Number
        merchantName:
          type: string
          description: Merchant Name
        merchantAccountNumber:
          type: string
          description: Merchant Account Number
        merchantSortCode:
          type: string
          description: Merchant Sort Code
        mandateStatus:
          type: string
          description: Status
        auddisIndicator:
          type: string
          description: AUDDIS Flag (AUDDIS / Non-AUDDIS)
          enum:
          - A
          - N
          - T
        setupDate:
          type: string
          description: Setup date
        mandateReference:
          type: string
          description: Mandate Reference
      required:
      - auddisIndicator
      - mandateId
      - mandateReference
      - mandateStatus
      - merchantAccountNumber
      - merchantName
      - merchantNumber
      - merchantSortCode
      - setupDate
    directdebitoutbound.CollectionRejectRequest:
      type: object
      description: Collection reject request
      properties:
        claimBId:
          type: string
          description: Collection Claim Business ID
          example: A123456B
          pattern: '[A-Za-z]{1}[0-9]{2}([A-Za-z0-9]){5}'
        rejectCode:
          type: string
          enum:
          - ADVANCE_NOTICE_DISPUTED
          - AMOUNT_DIFFERS
          - AMOUNT_NOT_YET_DUE
          - PRESENTATION_OVERDUE
          - SKIP_DEBIT_ATTEMPT
      required:
      - claimBId
      - rejectCode
  securitySchemes:
    modulo_security:
      type: apiKey
      name: Authorization
      in: header
    TOKEN:
      type: apiKey
      name: Authorization
      in: header
x-readme:
  proxy-enabled: false