openapi: 3.0.1
info:
  title: Payment Instructions
  description:  "To improve the efficiency of handling the creation of Direct Debit Instructions and Payment Collections, we have made a breaking change to the Direct Debit APIs. Version 2 of the Direct Debit APIs will now be synchronous meaning that you will no longer require to provide a public callback URL to receive the results of the API request."
  version: v2
servers:
  - url: https://payments-sandbox.multipay.tstpaypoint.services/gateway/instructions/directdebit/v2
    description: Sandbox Server
paths:
  /:
    post:
      tags:
        - Payment Instructions
      summary: Create Payment Instruction
      description: |
        To create a payment instruction, you will need to send a Create Payment Instruction API Request containing: payer details including bank account details, and any payment schedule details.
      operationId: createPaymentInstructionRequest"
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: uniqueRequestIdentifier
          in: header
          required: false
          description: Unique value has to be provided in order to create 2 otherwise identical payment instructions. Only used for DDRef autogenerate is enabled and DDRef is not provided on the request body.
          schema:
            type: string
      requestBody:
        description: The request body must contain the amount and  payer details including bank account details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentInstructionRequest'
        required: true
      responses:
        201:
          description: "The Instruction Id is returned when the operation is successful and an instruction has been created"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInstructionCreatedResponse'
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        200:
          description: "The Instruction Id is returned again when the operation is idempotent"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInstructionCreatedResponse'
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        409:
          description: "Returned when the instruction already exists. Unique DDRef has to be provided. When DDRef is auto generated, please use uniqueRequestIdentifier header if you want to create 2 instructions with the same properties but different autogenerated DDRefs."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}:
    put:
      tags:
        - Instruction Management
      summary: Update Payment Instruction
      description: To update a payment instruction, you will need to send an Update Payment Instruction Request containing the instructionId and the full instruction details including the changes that you wish to update.
      operationId: updatePaymentInstructionRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentInstructionRequest'
        required: true
      responses:
        200:
          description: "The Instruction Id is returned when the operation is successful and an instruction has been updated"
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when current instruction status is not currently one that allows this operation or etag provided within If-match request header does not match the currently stored version of the instruction."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
    get:
      tags:
        - Payment Instructions
      summary: Payment Instruction Details
      description: "To receive details on a payment instruction, send a Payment Instruction GET Request that contains the instructionId. A synchronous response is returned containing the instruction's details including amount, payer details and schedule details."
      operationId: getPaymentInstructionRequest
      parameters:
        - name: instructionId
          description: The instructionId obtained from the Create Payment instruction API
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      responses:
        200:
          description: "Returned when the operation is successful. The response body contains payment instruction details including payer and payee details, schedules details and status of the intruction:"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentInstructionResponse'
        404:
            description: Returned when trying to get details of payment instruction that does not exists.
            headers:
              traceid:
                schema:
                  $ref: '#/components/schemas/TraceIdHeader'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}/cancel:
    put:
      tags:
        - Instruction Management
      summary: Cancel Payment Instruction
      description: 'Cancel Payment Instruction'
      operationId: cancelPaymentInstructionRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelPaymentInstructionRequest'
        required: true
      responses:
        200:
          description: "The Instruction Id is returned when the operation is successful and an instruction has been cancelled"
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when current instruction status is not currently one that allows this operation or etag provided within If-match request header does not match the currently stored version of the instruction."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}/suspend:
    put:
      tags:
        - Instruction Management
      summary: Suspend Payment Instruction
      description: 'Suspend Payment Instruction'
      operationId: suspendPaymentInstructionRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuspendPaymentInstructionRequest'
        required: true
      responses:
        200:
          description: "The Instruction Id is returned when the operation is successful and an instruction has been suspended"
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when current instruction status is not currently one that allows this operation or etag provided within If-match request header does not match the currently stored version of the instruction."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}/resume:
    put:
      tags:
        - Instruction Management
      summary: Resume Payment Instruction
      description: To resume a suspended payment instruction, you will need to send a Resume Payment Instruction Request containing the instructionId that you wish to resume.
      operationId: resumePaymentInstructionRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumePaymentInstructionRequest'
        required: true
      responses:
        200:
          description: "The Instruction Id is returned when the operation is successful and an instruction has been resumed"
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when current instruction status is not currently one that allows this operation or etag provided within If-match request header does not match the currently stored version of the instruction."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              description: The trace id of the request
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}/schedules/{scheduleId}/cancel:
    put:
      tags:
        - Payment Schedules
      summary: Cancel Payment Schedule
      description: To cancel a payment schedule, you will need to send a Cancel Schedule Request containing the scheduleId that you wish to cancel.
      operationId: cancelScheduleRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: scheduleId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ScheduleId'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelScheduleRequest'
        required: true
      responses:
        200:
          description: "The schedule Id is returned when the operation is successful and a schedule has been cancelled."
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction or schedule does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when current schedule status is not currently one that allows this operation or etag provided within If-match request header does not match the currently stored version of the schedule."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}/schedules/{scheduleId}:
    put:
      tags:
        - Payment Schedules
      summary: Update Payment Schedule
      description: To update the payment schedules associated to a payment instruction, you will need to send an Update Payment Schedule Request containing the instructionId and the details of the schedule that you wish to update.
      operationId: updateScheduleRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: scheduleId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ScheduleId'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'
        required: true
      responses:
        200:
          description: "The schedule Id is returned when the operation is successful and a schedule has been updated."
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction or schedule does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when current schedule status is not currently one that allows this operation or etag provided within If-match request header does not match the currently stored version of the schedule."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
    get:
      tags:
        - Payment Schedules
      summary: Get a Payment Schedule
      description: To receive details on a specific payment instruction schedule, send a Payment Schedule GET Request that contains the instructionId and schedule. A synchronous response is returned containing the schedule's details including amount, interval and start date.
      operationId: getScheduleRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: scheduleId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ScheduleId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      responses:
        200:
          description: "Returned when the operation is successful. The response body contains payment schedule details including amount, interval and start date."
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScheduleResponse'
        404:
          description: "Returned when the payment instruction or schedule does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /{instructionId}/schedules:
    post:
      tags:
        - Payment Schedules
      summary: Add Payment Schedule
      description: To add a payment schedule to a payment instruction, you will need to send an Add Payment Schedule Request containing the instructionId and the details of the additional schedule associated to the payment instruction.
      operationId: addScheduleRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddScheduleRequest'
        required: true
      responses:
        201:
          description: "The Schedule Id is returned when the operation is successful and a schedule has been created"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleAddedResponse'
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        200:
          description: "The Schedule Id is returned again when the operation is idempotent"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleAddedResponse'
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the payment instruction does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when the schedule already exists. Unique scheduleReference has to be provided in order to create 2 otherwise identical schedules."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
    get:
      tags:
        - Payment Schedules
      summary: Get Payment Schedules
      description: To receive details of all payment instruction schedule for and instruction, send a Payment Schedules GET Request that contains the instructionId. A synchronous response is returned containing each of the schedule's details including amount, interval and start date.
      operationId: getSchedulesRequest
      parameters:
        - name: instructionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/InstructionId'
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      responses:
        200:
          description: "Returned when the operation is successful. The response body contains all the instruction's payment schedules details including amount, interval and start date."
          headers: 
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSchedulesResponse'
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
components:
  schemas:
    Account:
      description: "The bank account details of the Payer"
      type: object
      required:
          - name
          - sortCode
          - accountNumber
      properties:
        name:
          type: string
          description: AccountName is required, AccountName must be upto 50 chars.
          nullable: false
        sortCode:
          type: string
          description: SortCode is required, SortCode must be 6 characters, SortCode can only be digits
          nullable: false
        accountNumber:
          type: string
          description: AccountNumber is required, AccountNumber must be 8 characters, AccountNumber can only be digits
          nullable: false
      additionalProperties: false
    AddScheduleRequest:
      type: object
      required:
        - schedule
      properties:
        schedule:
          $ref: '#/components/schemas/Schedule'
          nullable: false
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    Address:
      description: "The address of the Payer required if a paper mandate is sent by Post"
      type: object
      properties:
        address1:
          type: string
          description: Address1 is required, Address1 must be between 1 and 50 characters
          nullable: true
        address2:
          type: string
          description: Address2 must be between 1 and 50 characters
          nullable: true
        address3:
          type: string
          description: Address3 must be between 1 and 50 characters
          nullable: true
        town:
          type: string
          description: Town must be between 1 and 50 characters
          nullable: true
        postCode:
          type: string
          description: PostCode must be between 1 and 16 characters
          nullable: true
        telephone:
          type: string
          description: Telephone must be between 1 and 20 characters long, Telephone is not a valid phone number
          nullable: true
        countryCode:
          type: string
          nullable: true
          description: Default UK
      additionalProperties: false
    Audit:
      type: object
      description: "Internal Audit parameters used within the merchant portal to record user activity."
      properties:
        username:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        userId:
          type: string
          nullable: true
        applicationId:
          type: string
          nullable: true
        applicationName:
          type: string
          nullable: true
        operation:
          type: string
          nullable: true
        dateRequested:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    CancelPaymentInstructionRequest:
      description: "Cancel Instruction request details"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    CancelScheduleRequest:
      description: "Cancel Schedule request details"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    CreatePaymentInstructionRequest:
      description: "Create Instruction request details"
      type: object
      required:
        - paymentMethod
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
        paymentMethod:
          $ref: '#/components/schemas/InstructionPaymentMethod'
          nullable: false
        clientsInstructionReference:
          type: string
          description: "Unique reference provided by the client to help them identity an instruction."
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerAccount'
          nullable: true
        giftAid:
          $ref: '#/components/schemas/GiftAid'
          nullable: true
      additionalProperties: false
    CustomerAccount:
      type: object
      description: Customer does not have to be supplied with the request
      required:
        - customerId
        - customerAccountId
        - accountType
      properties:
        customerId:
          type: string
          description: GUID created when a customer record is created
          nullable: false
        customerAccountId:
          type: string
          description: 'Customer ID/PRN/PAN, for Vend clients 19 digits, else Alphanumeric, max 50'
          nullable: false
        accountType:
          type: string
          description: "For Example: Electricity, Gas, Heat, BillPay, Energy, Commercial Electricity, Commercial Gas or what either the client has stated as the Account Type in the CQ."
          nullable: false
      additionalProperties: false
    GetScheduleResponse:
      description: "Details of the Get Schedule Response"
      type: object
      properties:
        schedule:
          $ref: '#/components/schemas/Schedule'
          nullable: false
      additionalProperties: false
    GetSchedulesResponse:
      description: "Details of the Get Schedules Response"
      type: object
      required:
        - schedules
      properties:
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleWithEtag'
          nullable: false
      additionalProperties: false
    GetPaymentInstructionResponse:
      description: "Details of the response payload for a payment instruction"
      type: object
      required:
        - paymentInstruction
      properties:
        paymentInstruction:
          $ref: '#/components/schemas/PaymentInstruction'
          nullable: false
      additionalProperties: false
    GiftAid:
      type: object
      description: "GiftAidConsent if true then FirstName, LastName, Address1 and PostCode are required."
      items:
        type: object
        properties:
          giftAidConsent:
            type: boolean
            description: ''
          firstName:
            type: string
            description: ''
          lastName:
            type: string
            description: ''
          address1:
            type: string
            description: ''
          postCode:
            type: string
            description: ''
      additionalProperties: false
    DDInstructionType:
      description: "The type of Direct Debit Instruction DDI or PDDI (paperless)"
      type: string
      enum:
        - DDI
        - PDDI
    InstructionPayer:
      description: "Payer Details of the Instruction"
      type: object
      required:
        - account
        - name
      properties:
        address:
          $ref: '#/components/schemas/Address'
          nullable: true
        account:
          $ref: '#/components/schemas/Account'
          nullable: false
        notification:
          $ref: '#/components/schemas/Notification'
          nullable: true
        name:
          type: string
          description: Payer Name is required
          nullable: false
        tradingName:
          type: string
          description: If the payer is a Business then a trading name can be provided if different to the payer name
          nullable: true
      additionalProperties: false
    InstructionPaymentMethod:
      description: "Payee Details of the Instruction"
      type: object
      required:
        - sun
        - payer
      properties:
        sun:
          type: string
          description: Service User Number from BACS, Numeric. Must be 6 characters in length
          nullable: false
        payerReference:
          type: string
          description: Reference provided by the customer/payer. Alphanumeric, max 150 characters
          nullable: true
        ddRef:
          type: string
          description: Reference the client set for Direct Debit Instruction Alphanumeric, minimum 6 characters, max 18 characters. Must not have all repeated characters
          nullable: true
        payer:
          $ref: '#/components/schemas/InstructionPayer'
          nullable: false
        instructionType:
          $ref: '#/components/schemas/DDInstructionType'
          nullable: true
          default: DDI
      additionalProperties: false
    Notification:
      description: "Details of the payer's notification email or mobile"
      type: object
      properties:
        email:
          type: string
          description: Notification Email is required, Email address must be in a valid email address format
          nullable: true
        mobile:
          type: string
          description: Mobile must start with either '+447' or '07', Mobile should be 13 or 11 characters long respectively and contain only valid characters.
          nullable: true
      additionalProperties: false
    PaymentInstruction:
      description: "Payment Instruction API model"
      type: object
      required:
        - paymentInstructionId
        - instructionStatus
        - instructionStatusLastChanged
        - clientsInstructionReference
        - paymentMethod
        - submissionDate
      properties:
        paymentInstructionId:
          type: string
          description: GUID generated when a payment instruction is created under.
          nullable: false
        instructionStatus:
          type: string
          description: The status of the instruction, either pending, live, failed, invalid, suspended or cancelled
          nullable: false
        instructionStatusLastChanged:
          type: string
          description: Last instruction state transition time
          format: date-time
          nullable: false
        clientsInstructionReference:
          type: string
          description: Client instruction reference.
          nullable: false
        customer:
          $ref: '#/components/schemas/CustomerAccount'
          nullable: true
        giftAid:
          $ref: '#/components/schemas/GiftAid'
          nullable: true
        paymentMethod:
          $ref: '#/components/schemas/InstructionPaymentMethod'
          nullable: false
        submissionDate:
          type: string
          description: Instruction submission date
          format: date-time
          nullable: false
        createdDate:
          type: string
          description: Instruction creation date
          format: date-time
          nullable: false
      additionalProperties: false
    PaymentInstructionCreatedResponse:
      description: "Response details when an instruction is created"
      type: object
      required:
        - instructionId
      properties:
        instructionId:
          type: string
          description: "GUID generated when a instuction record is created and is used as the main key for the Direct Debit Instruction."
          nullable: false
      additionalProperties: false
    ProblemDetails:
      description: "Response details when there is error with the request payload"
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    ResumePaymentInstructionRequest:
      description: "Response details when an instruction is resumed"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    Schedule:
      description: "Details of a schedule record"
      type: object
      required:
        - scheduleType
        - amount
        - startDate
      properties:
        scheduleType:
          $ref: '#/components/schemas/ScheduleType'
          nullable: false
        amount:
          type: number
          description: 'Must be greater than 0, Authorised Item Limit exceeded'
          format: double
          nullable: false
        interval:
          type: integer
          description: Interval must be 1 or more
          format: int32
          nullable: true
        intervalUnit:
          $ref: '#/components/schemas/ScheduleIntervalUnit'
          nullable: true
        startDate:
          type: string
          description: StartDate is required and must be in the future and must be in yyyy-MM-dd format
          nullable: false
        endDate:
          type: string
          description: Enddate must be in the future and must be in yyyy-MM-dd format. End date can not be before start date
          nullable: true
        scheduleReference:
          type: string
          description: Reference providd to identity the different schedules on a single instruction
          nullable: true
      additionalProperties: false
    ScheduleAddedResponse:
      description: "Response details when a schedule is created"
      type: object
      required:
        - instructionId
        - scheduleId
      properties:
        instructionId:
          type: string
          description: "GUID generated when a instuction record is created and is used as the main key for the Direct Debit Instruction."
          nullable: false
        scheduleId:
          type: string
          description: "GUID generated when a schedule is created under a specific instrucion record."
          nullable: false
      additionalProperties: false
    ScheduleIntervalUnit:
      enum:
        - Week
        - Month
      type: string
    ScheduleStatus:
      enum:
        - Active
        - Cancelled
      type: string
    ScheduleType:
      enum:
        - Single
        - Recurring
      type: string
    ScheduleWithEtag:
      type: object
      required:
        - schedule
      properties:
        schedule:
          $ref: '#/components/schemas/Schedule'
          nullable: false
        etag:
          type: string
          nullable: true
      additionalProperties: false
    SuspendPaymentInstructionRequest:
      description: "Response details when an instruction is suspended"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    UpdatePaymentInstructionRequest:
      description: "Details of an Update Instruction request"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
        paymentMethod:
          $ref: '#/components/schemas/InstructionPaymentMethod'
          nullable: true
        clientsInstructionReference:
          type: string
          description: "Unique reference provided by the client to help them identity an instruction."
          nullable: true
        customer:
          $ref: '#/components/schemas/CustomerAccount'
          nullable: true
        giftAid:
          $ref: '#/components/schemas/GiftAid'
          nullable: true
      additionalProperties: false
    UpdateScheduleRequest:
      description: "Details of an Update Schedule request"
      type: object
      required:
        - endDate
      properties:
        endDate:
          type: string
          description: EndDate must be in the future and must be in yyyy-MM-dd format. End date can not be before start date
          nullable: false
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    TraceIdHeader:
      type: string
      description: The trace id of the request
    TraceParentHeader:
      type: string
      description: Identifies the incoming request in a tracing system. See https://www.w3.org/TR/trace-context
    LocationHeader:
      type: string
      description: The url of the created resource
    IfMatchHeader:
      type: string
      description: Used for update operations, to prevent lost update problem 
    ETagHeader:
      type: string
      description: The identifier for a specific version of a resource
    InstructionId:
      type: string
      description: "GUID generated when a instuction record is created and is used as the main key for the Direct Debit Instruction."
    ScheduleId:
      type: string
      description: "GUID generated when a schedule record is created."
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: subscription-key
      in: query
security:
  - apiKeyHeader: [ ]
  - apiKeyQuery: [ ]