openapi: 3.0.1
info:
  title: Payment
  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-dev.multipay.tstpaypoint.services/gateway/payments/directdebit/v2
    description: Dev Server
paths:
  /:
    post:
      tags:
        - Payments
      summary: Create Payment
      description: "To make an adhoc payment, you will need to send a Create a Payment API Request containing: Amount, your SUN, Direct Debit Payment instruction Id, and the future payment collection date."
      operationId: createPaymentRequest"
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      requestBody:
        description: The request body must contain the amount, collection date, the payer details including bank account details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
        required: true
      responses:
        201:
          description: "The Payment Id is returned when the operation is successful and a Payment has been created"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        200:
          description: "The Payment Id is returned again when the operation is idempotent"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: "Returned when the instructionId provided in the request does not exist."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        409:
          description: "Returned when the payment already exists. Unique paymentReference has to be provided in order to create 2 otherwise identical payments."
          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'
  /{paymentId}:
    get:
      tags:
        - Payments
      summary: Payment Details
      description: To receive details on a payment, send a Payment Details GET Request that contains the PaymentId. A synchronous response is returned containing the payments details including amount and collection date.
      operationId: getPaymentRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: paymentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PaymentId'
      responses:
        200:
          description: "Returned when the operation is successful. The response body contains payment details amount, status, collection date, and payer details:"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentResponse'
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: Returned when trying to get details of payment that does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          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'
  /{ddRef}/sun/{sun}:
    get:
      tags:
        - Payments
      summary: Get Payments By SUN and DDRef
      description: To receive details of all matching payments, send a Payments Details GET Request that contains the SUN and DDRef. A synchronous response is returned containing the payments details including amount and collection date.
      operationId: getPaymentsRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: sun
          in: path
          required: true
          schema:
            type: string
        - name: ddRef
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Returned when the operation is successful. The response body contains matching payment details amount, status, collection date, and payer details:"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentsResponse'
          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'
  /{paymentId}/cancel:
    put:
      tags:
        - Payment Management
      summary: Cancel Payment
      description: "To cancel a payment request upto 3 days before collection date, you will need to send a Cancel Request containing the paymentId returned in the original adhoc or scheduled payment request."
      operationId: cancelPaymentRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: if-match
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/IfMatchHeader'
        - name: paymentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PaymentId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCancelledRequest'
        required: true
      responses:
        200:
          description: OK response
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: Returned when trying to cancel a payment that does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
        409:
          description: "Returned when current payment 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 payment."
          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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          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'
  /{paymentId}/represent:
    post:
      tags:
        - Payment Management
      summary: Represent Payment
      description: When a collection of a Direct Debit payment has failed, depending of the failure reason you may wish to represent the payment request by sending a Represent Payment Request containing the original failed paymentId and a new collection date. 
      operationId: representPaymentRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: paymentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PaymentId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepresentPaymentRequest'
        required: true
      responses:
        201:
          description: "The Payment Id is returned when the operation is successful and a Payment has been represented"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RePresentPaymentResponse'
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        200:
          description: "The Payment Id is returned again when the operation is idempotent"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RePresentPaymentResponse'
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: Returned when trying to represent a payment that does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
        422:
          description: "Returned when the request body has one or more of the fields has failed validation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          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'
components:
  schemas:
    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
    PaymentCancelledRequest:
      description: "Details of the request payload needed to cancel a payment"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    CreatePaymentRequest:
      description: "Details of the request payload needed to create a payment"
      type: object
      required:
        - instructionId
        - amount
        - collectionDate
      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
        amount:
          type: number
          description: 'Must be greater than 0, Authorised Item Limit'
          format: double
          nullable: false
        collectionDate:
          type: string
          description: CollectionDate must be in future and must be in yyyy-MM-dd format
          format: date-time
          nullable: false
        paymentReference:
          type: string
          description: "Unique reference provided by the client to help them identity a payment. Allows creating multiple payments with same values."
          nullable: true
        giftAid:
          $ref: '#/components/schemas/GiftAid'
          nullable: true
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    GetPaymentResponse:
      description: "Details of the response payload for a payment"
      type: object
      required:
        - payment
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
          nullable: false
      additionalProperties: false
    GetPaymentsResponse:
      description: "Details of the response payload for a payment"
      type: object
      required:
        - payments
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentWithEtag'
          nullable: false
      additionalProperties: false
    PaymentWithEtag:
      type: object
      required:
        - payment
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
          nullable: false
        etag:
          type: string
          nullable: true
      additionalProperties: false
    Payment:
      description: "Payment API model"
      type: object
      required:
        - paymentId
        - instructionId
        - paymentStatus
        - amount
        - desiredCollectionDate
        - completionDate
      properties:
        paymentId:
          type: string
          description: "GUID generated when a payment is created under a specific instruction record."
          nullable: false
        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
        paymentReference:
          type: string
          description: "Unique reference provided by the client to help them identity an instruction."
          nullable: true
        paymentStatus:
          type: string
          description: "The status of the payment, either scheduled,sumbitted,cancelled, failed or collected"
          nullable: false
        amount:
          type: number
          description: 'Must be greater than 0, Authorised Item Limit'
          format: double
          nullable: false
        desiredCollectionDate:
          type: string
          description: CollectionDate must be in future and must be in yyyy-MM-dd format
          format: date-time
          nullable: false
        completionDate:
          type: string
          description: Actual completion data calculated from desiredCollectionDate
          format: date-time
          nullable: false
        giftAid:
          $ref: '#/components/schemas/GiftAid'
          nullable: true
      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
    CreatePaymentResponse:
      description: "Details of the response payload for creating a payment"
      type: object
      required:
        - paymentId
      properties:
        paymentId:
          type: string
          description: "GUID generated when a payment is created under a specific instruction record."
          nullable: false
      additionalProperties: false
    RePresentPaymentResponse:
      description: "Details of the response payload for representing a payment"
      type: object
      required:
        - paymentId
      properties:
        paymentId:
          type: string
          description: "GUID generated when a payment is created under a specific instruction record."
          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: {}
    RepresentPaymentRequest:
      description: "Details of the request payload for representing a payment"
      type: object
      required:
        - collectionDate
      properties:
        collectionDate:
          type: string
          description: CollectionDate must be in future and must be in yyyy-MM-dd format
          format: date-time
          nullable: false
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    PaymentId:
      type: string
      description: "GUID generated when a payment record is created and is used as the main key for the Direct Debit Payment."
    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
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: subscription-key
      in: query
security:
  - apiKeyHeader: [ ]
  - apiKeyQuery: [ ]