openapi: 3.0.1
info:
  title: Credit
  description: The Multipay Credit API enables clients to create, manage, and query direct credit transactions securely and efficiently. It supports operations such as creating credits for payment instructions, searching credit history, and managing the lifecycle of credit requests. This API is designed for integration with payment platforms requiring automated credit processing, audit tracking, and robust error handling. All endpoints are secured and require appropriate authentication.
  version: v1
servers:
  - url: https://payments-dev.multipay.tstpaypoint.services/gateway/credits/directcredit/v1
    description: Dev Server
paths:
  /:
    post:
      tags:
        - Credits
      summary: Create Credit
      description: "Create credit for instruction"
      operationId: createCreditRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
      requestBody:
        description: The request body must contain the amount, collection date, sun and instructionId.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCreditRequest'
            example:
              instructionId: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
              sun: "123456"
              amount: 150.0
              collectionDate: "2025-09-01T00:00:00Z"
              creditReference: "CREDIT-REF-001"
              audit:
                username: "jdoe"
                operation: "CreateCredit"
        required: true
      responses:
        201:
          description: "The Credit Id is returned when the operation is successful and a Credit has been created"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCreditResponse'
              example:
                creditId: "c1d2e3f4-5678-90ab-cdef-1234567890ab"
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            location:
              schema:
                $ref: '#/components/schemas/LocationHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        200:
          description: "The Credit Id is returned again when the operation is idempotent"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCreditResponse'
              example:
                creditId: "c1d2e3f4-5678-90ab-cdef-1234567890ab"
          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 credit already exists. Unique creditReference has to be provided in order to create 2 otherwise identical credits."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: "https://example.com/conflict"
                title: "Credit already exists"
                status: 409
                detail: "A credit with the same details already exists."
                instance: "/credits/c1d2e3f4-5678-90ab-cdef-1234567890ab"
        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'
              example:
                type: "https://example.com/validation-error"
                title: "Validation Failed"
                status: 422
                detail: "The amount must be greater than 0."
                instance: "/credits"
        429:
          description: "Returned when there has been Too Many Requests with in a given time period"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
  /search:
    get:
      tags:
        - Credits
      summary: Search Credits
      description: Search for credits based on various criteria such as SUN, DCRef, status, client reference, payee reference, account holder name, amount, and date range.
      operationId: searchCreditsRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: selectedSuns
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            description: Array of Service User Numbers to filter by
        - name: dcRef
          in: query
          required: false
          schema:
            type: string
            description: Direct Credit reference to filter by
        - name: status
          in: query
          required: false
          schema:
            type: integer
            description: Status code to filter by
        - name: clientReference
          in: query
          required: false
          schema:
            type: string
            description: Client reference to filter by
        - name: creditReference
          in: query
          required: false
          schema:
            type: string
            description: Credit reference to filter by
        - name: payeeReference
          in: query
          required: false
          schema:
            type: string
            description: Payee reference to filter by
        - name: accountHolderName
          in: query
          required: false
          schema:
            type: string
            description: Account holder name to filter by
        - name: amount
          in: query
          required: false
          schema:
            type: number
            format: decimal
            description: Amount to filter by
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: Start date for date range filter (yyyy-MM-dd)
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: End date for date range filter (yyyy-MM-dd)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            description: Page number for pagination
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
            description: Number of items per page
      responses:
        200:
          description: "Returned when the search operation is successful. The response body contains paginated credit search results."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditSearchPagedResponse'
              example:
                items:
                  - creditId: "c1d2e3f4-5678-90ab-cdef-1234567890ab"
                    instructionId: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
                    sun: "123456"
                    dcRef: "DCREF-001"
                    status: 1
                    clientReference: "CLIENT-REF-001"
                    payeeReference: "PAYEE-REF-001"
                    accountHolderName: "Jane Smith"
                    amount: 150.0
                    collectionDate: "2025-09-01"
                pageSize: 10
                page: 1
                totalRecords: 1
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
        400:
          description: "Returned when the request parameters are invalid."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: "https://example.com/invalid-params"
                title: "Invalid Parameters"
                status: 400
                detail: "The provided query parameters are invalid."
                instance: "/credits/search"
  /history/search:
    get:
      tags:
        - Credits
      summary: Search Credit History
      description: Search for credit history records using various criteria.
      operationId: searchCreditHistoryRequest
      parameters:
        - name: creditId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Credit Id to filter by
        - name: instructionId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Instruction Id to filter by
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Number of items per page
      responses:
        200:
          description: Returned when the search operation is successful. The response body contains paginated credit history search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditHistorySearchPagedResponse'
              example:
                items:
                  - creditId: "c1d2e3f4-5678-90ab-cdef-1234567890ab"
                    instructionId: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
                    eventId: "evt-001"
                    eventName: "CreditCreated"
                    amount: 150.0
                    eventDateTime: "2025-08-27T10:00:00Z"
                    userName: "jdoe"
                    userFullName: "John Doe"
                    userId: "user-123"
                    applicationId: "app-456"
                    applicationName: "MerchantPortal"
                    operation: "Create"
                    creditReference: "CREDIT-REF-001"
                pageSize: 10
                page: 1
                totalRecords: 1
          headers:
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
        400:
          description: Returned when the request parameters are invalid.
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: "https://example.com/invalid-params"
                title: "Invalid Parameters"
                status: 400
                detail: "The provided query parameters are invalid."
                instance: "/credits/history/search"
  /{creditId}:
    get:
      tags:
        - Credits
      summary: Credit Details
      description: To receive details on a credit, send a Credit Details GET Request that contains the CreditId. A synchronous response is returned containing the credit details including amount and collection date.
      operationId: getCreditRequest
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/TraceParentHeader'
        - name: creditId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/CreditId'
      responses:
        200:
          description: "Returned when the operation is successful. The response body contains credit details amount, status, collection date, and payer details:"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCreditResponse'
              example:
                payment:
                  creditId: "c1d2e3f4-5678-90ab-cdef-1234567890ab"
                  instructionId: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
                  creditReference: "CREDIT-REF-001"
                  status: "scheduled"
                  amount: 150.0
                  desiredCollectionDate: "2025-09-01T00:00:00Z"
                  completionDate: "2025-09-01T00:00:00Z"
                  submissionDate: "2025-08-27T10:00:00Z"
                  paymentMethod:
                    sun: "123456"
                    dcRef: "DCREF-001"
                    payeeReference: "PAYEE-REF-001"
                    payee:
                      name: "Acme Corp"
                      account:
                        name: "Acme Corp"
                        sortCode: "654321"
                        accountNumber: "87654321"
                    payer:
                      account:
                        name: "Jane Smith"
                        sortCode: "123456"
                        accountNumber: "12345678"
          headers: 
            traceId:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
            etag:
              schema:
                $ref: '#/components/schemas/ETagHeader'
        404:
          description: Returned when trying to get details of credit 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'
  /{creditId}/cancel:
    put:
      tags:
        - Credits
      summary: Cancel Credit
      description: "To cancel a credit request upto 3 days before collection date, you will need to send a Cancel Request containing the creditId returned in the original create credit request."
      operationId: cancelCreditRequest
      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: creditId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/CreditId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelCreditRequest'
            example:
              audit:
                username: "jdoe"
                operation: "CancelCredit"
        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 credit that does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: "https://example.com/not-found"
                title: "Credit Not Found"
                status: 404
                detail: "No credit found with the provided creditId."
                instance: "/credits/invalid-id/cancel"
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
        409:
          description: "Returned when current credit 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 credit."
          headers:
            traceid:
              schema:
                $ref: '#/components/schemas/TraceIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: "https://example.com/conflict"
                title: "Invalid Credit State or ETag Mismatch"
                status: 409
                detail: "The credit cannot be cancelled in its current state or the ETag does not match."
                instance: "/credits/c1d2e3f4-5678-90ab-cdef-1234567890ab/cancel"
        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'
              example:
                type: "https://example.com/validation-error"
                title: "Validation Failed"
                status: 422
                detail: "The audit field is required."
                instance: "/credits/c1d2e3f4-5678-90ab-cdef-1234567890ab/cancel"
          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
    CancelCreditRequest:
      description: "Details of the request payload needed to cancel a credit"
      type: object
      properties:
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    CreateCreditRequest:
      description: "Details of the request payload needed to create a credit"
      type: object
      required:
        - instructionId
        - sun
        - 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 Credit Payment."
          nullable: false
        sun:
          type: string
          description: Service User Number from BACS, Numeric. Must be 6 characters in length
          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
        creditReference:
          type: string
          description: "Unique reference provided by the client to help them identity a credit. Allows creating multiple credits with same values."
          nullable: true
        audit:
          $ref: '#/components/schemas/Audit'
          nullable: true
      additionalProperties: false
    GetCreditResponse:
      description: "Details of the response payload for a credit"
      type: object
      required:
        - credit
      properties:
        payment:
          $ref: '#/components/schemas/Credit'
          nullable: false
      additionalProperties: false
    Credit:
      description: "Payment API model"
      type: object
      required:
        - creditId
        - instructionId
        - amount
        - status
        - desiredCollectionDate
        - completionDate
        - submissionDate
        - paymentMethod
      properties:
        creditId:
          type: string
          description: "GUID generated when a credit 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 Credit Payment."
          nullable: false
        creditReference:
          type: string
          description: "Unique reference provided by the client to help them identity a credit."
          nullable: true
        status:
          type: string
          description: "The status of the credit, either scheduled,sumbitted or cancelled"
          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
        submissionDate:
          type: string
          description: Credit submission date
          format: date-time
          nullable: false
        paymentMethod:
          $ref: '#/components/schemas/CreditPaymentMethod'
          description: Credit payment details
          nullable: false
      additionalProperties: false
    CreateCreditResponse:
      description: "Details of the response payload for creating a credit"
      type: object
      required:
        - creditId
      properties:
        creditId:
          type: string
          description: "GUID generated when a credit is created under a specific instruction record."
          nullable: false
      additionalProperties: false
    CreditPaymentMethod:
      description: "Payment Details of the Credit"
      type: object
      required:
        - sun
        - dcRef
        - payee
        - payer
      properties:
        sun:
          type: string
          description: Service User Number from BACS, Numeric. Must be 6 characters in length
          nullable: false
        dcRef:
          type: string
          description: Reference the client set for Direct Credit Payment
          nullable: true
        payeeReference:
          type: string
          description: Reference provided by the customer/payee. Alphanumeric, max 150 characters
          nullable: true
        payee:
          $ref: '#/components/schemas/CreditPayee'
          nullable: false
        payer:
          $ref: '#/components/schemas/CreditPayer'
          nullable: false
      additionalProperties: false
    CreditPayee:
      description: "Payee Details of the Credit"
      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: Payee Name is required
          nullable: false
        tradingName:
          type: string
          description: If the payee is a Business then a trading name can be provided if different to the payee name
          nullable: true
      additionalProperties: false
    CreditPayer:
      description: "Payee Details of the Credit"
      type: object
      required:
        - account
      properties:
        account:
          $ref: '#/components/schemas/Account'
          nullable: false
      additionalProperties: false
    Account:
      description: "The bank account details of the Payee/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
    Address:
      description: "The address of the Payee"
      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
    Notification:
      description: "Details of the payee'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
    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: {}
    CreditId:
      type: string
      description: "GUID generated when a credit record is created and is used as the main key for the Direct Credit 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
    CreditSearchPagedResponse:
      description: "Paginated response containing credit search results"
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreditSearchResponse'
          nullable: true
          description: List of credit search results
        pageSize:
          type: integer
          description: Number of items per page
        page:
          type: integer
          description: Current page number
        totalRecords:
          type: integer
          description: Total number of records matching the search criteria
      additionalProperties: false
    CreditSearchResponse:
      description: "Individual credit search result"
      type: object
      required:
        - creditId
        - sun
        - dcRef
        - accountHolderName
        - collectionDate
      properties:
        creditId:
          type: string
          format: uuid
          description: Unique identifier for the credit
        instructionId:
          type: string
          format: uuid
          nullable: true
          description: Associated instruction identifier
        sun:
          type: string
          description: Service User Number
        dcRef:
          type: string
          description: Direct Credit reference
        status:
          type: integer
          description: Current status of the credit
        clientReference:
          type: string
          nullable: true
          description: Client-provided reference
        creditReference:
          type: string
          nullable: true
          description: Credit reference
        payeeReference:
          type: string
          nullable: true
          description: Payee-provided reference
        accountHolderName:
          type: string
          description: Name of the account holder
        amount:
          type: number
          format: decimal
          description: Credit amount
        collectionDate:
          type: string
          format: date
          description: Date when the credit will be collected
      additionalProperties: false
    CreditHistorySearchPagedResponse:
      description: "Paginated response containing credit history search results"
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreditHistorySearchResponse'
          nullable: true
          description: List of credit history search results
        pageSize:
          type: integer
          description: Number of items per page
        page:
          type: integer
          description: Current page number
        totalRecords:
          type: integer
          description: Total number of records matching the search criteria
      additionalProperties: false
    CreditHistorySearchResponse:
      description: "Individual credit history search result"
      type: object
      required:
        - creditId
        - eventId
        - eventName
        - amount
        - eventDateTime
        - userName
        - userFullName
        - userId
        - applicationId
        - applicationName
        - operation
      properties:
        creditId:
          type: string
          format: uuid
          description: Unique identifier for the credit
        instructionId:
          type: string
          format: uuid
          nullable: true
          description: Associated instruction identifier
        eventId:
          type: string
          description: Unique identifier for the event
        eventName:
          type: string
          description: Name of the event
        amount:
          type: number
          format: decimal
          description: Amount for the event
        eventDateTime:
          type: string
          format: date-time
          description: Date and time of the event
        userName:
          type: string
          description: Username of the user who performed the event
        userFullName:
          type: string
          description: Full name of the user who performed the event
        userId:
          type: string
          description: User ID of the user who performed the event
        applicationId:
          type: string
          description: Application ID where the event was performed
        applicationName:
          type: string
          description: Application name where the event was performed
        operation:
          type: string
          description: Operation performed
        creditReference:
          type: string
          nullable: true
          description: Credit reference if available
      additionalProperties: false
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: subscription-key
      in: query
security:
  - apiKeyHeader: [ ]
  - apiKeyQuery: [ ]