ledger_spec.yaml

openapi: 3.0.1
info:
  description: Ledger API
  title: Ledger API
  version: v1.0.0
servers:
- url: http://ledger_url
paths:
  /healthcheck:
    get:
      operationId: healthCheck
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
                example:
                  postgresql:
                    healthy: true
                    message: Healthy
                  sqsQueue:
                    healthy: true
                    message: Healthy
                  deadlocks:
                    healthy: true
                    message: Healthy
          description: OK
        "503":
          description: Service Unavailable
      summary: "Healthcheck endpoint the ledger (checks postgresql, sqs queue)"
      tags:
      - Other
  /v1/agreement:
    get:
      operationId: search
      parameters:
      - description: Service id(s)
        example: 1
        in: query
        name: service_id
        schema:
          type: array
          items:
            type: string
      - description: Limit the results to agreement(s) relating to live (not test)
          accounts
        example: true
        in: query
        name: live
        schema:
          type: boolean
      - description: Gateway account id(s)
        example: 1
        in: query
        name: account_id
        schema:
          type: array
          items:
            type: string
      - description: "Unless set to true, either service_id or account_id field must\
          \ be completed"
        example: true
        in: query
        name: override_account_or_service_id_restriction
        schema:
          type: boolean
      - description: Status of agreement
        example: CREATED
        in: query
        name: status
        schema:
          type: string
          enum:
          - CREATED
          - ACTIVE
          - INACTIVE
          - CANCELLED
      - description: Limit the results to exact matches for the given reference
        example: true
        in: query
        name: exact_reference_match
        schema:
          type: boolean
      - description: The reference provided by the service when creating the agreement(s)
        example: 12345
        in: query
        name: reference
        schema:
          type: string
      - description: Page number of results
        example: 1
        in: query
        name: page
        schema:
          type: integer
          format: int64
      - description: Number of results to be displayed
        example: 10
        in: query
        name: display_size
        schema:
          type: integer
          format: int64
          default: 20
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgreementSearchResponse'
          description: OK
        "404":
          description: Not found
      summary: Search agreements by query params
      tags:
      - Agreements
  /v1/agreement/{agreementExternalId}:
    get:
      operationId: get
      parameters:
      - description: The unique external id for the agreement
        example: cgc1ocvh0pt9fqs0ma67r42l58
        in: path
        name: agreementExternalId
        required: true
        schema:
          type: string
      - description: "If true, an additional check will be carried out to ensure that\
          \ ledger database is up-to-date with latest events before responding"
        example: true
        in: header
        name: X-Consistent
        schema:
          type: boolean
      - description: The gateway account id linked to the agreement
        example: 1
        in: query
        name: account_id
        schema:
          type: string
      - description: The service id linked to the agreement
        example: 1
        in: query
        name: service_id
        schema:
          type: string
      - description: "If false, the account_id or service_id must be specified"
        example: false
        in: query
        name: override_account_or_service_id_restriction
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agreement'
          description: OK
        "404":
          description: Not found
        "422":
          description: Invalid parameters. One of service_id or account_id fields
            is required unless override_account_or_service_id_restriction=true
      summary: Find agreement by ID
      tags:
      - Agreements
  /v1/agreement/{agreementExternalId}/event:
    get:
      operationId: getEvents
      parameters:
      - description: The unique external id for the agreement
        example: cgc1ocvh0pt9fqs0ma67r42l58
        in: path
        name: agreementExternalId
        required: true
        schema:
          type: string
      - description: The service id linked to the agreement
        example: 1
        in: query
        name: service_id
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgreementEventsResponse'
          description: OK
        "404":
          description: Not found
      summary: Find agreement events by agreement ID
      tags:
      - Agreements
  /v1/event:
    post:
      operationId: writeEvent
      requestBody:
        content:
          '*/*':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EventMessageDto'
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventTicker'
          description: OK
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing query parameters
        "500":
          description: Invalid parameters or Downstream system error
      summary: Write a list of events to the ledger database
      tags:
      - Events
  /v1/event/ticker:
    get:
      operationId: listEvents
      parameters:
      - description: from date of events to be searched (this date is inclusive).
        example: 2015-08-14T12:35:00Z
        in: query
        name: from_date
        required: true
        schema:
          type: string
      - description: to date of events to be searched (this date is exclusive)
        example: 2015-08-14T12:35:00Z
        in: query
        name: to_date
        required: true
        schema:
          type: string
      - description: event types to find
        example: PAYMENT_CREATED
        in: query
        name: event_types
        schema:
          type: array
          items:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventTicker'
          description: OK
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing query parameters
        "500":
          description: Invalid parameters or Downstream system error
      summary: Get list of events between a date/time range and event type
      tags:
      - Events
  /v1/payout:
    get:
      operationId: search_1
      parameters:
      - description: "State of payout. allowed values are intransit, paidout, failed"
        in: query
        name: state
        schema:
          type: string
      - description: "Page number requested for the search, should be a positive integer\
          \ (optional, defaults to 1)"
        in: query
        name: page
        schema:
          type: integer
          format: int64
      - description: "Number of results to be shown per page, should be a positive\
          \ integer (optional, defaults to 500, max 500)"
        in: query
        name: display_size
        schema:
          type: integer
          format: int64
      - description: Set to true to list all payouts.
        in: query
        name: override_account_id_restriction
        schema:
          type: boolean
      - description: Comma delimited gateway account IDs. Required except when override_account_id_restriction=true
        example: "1,2"
        in: query
        name: gateway_account_id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutSearchResponse'
          description: OK
        "404":
          description: Not found
      summary: Search payouts by gateway_account_id and state
      tags:
      - Payouts
  /v1/report/gateway-performance-report:
    get:
      operationId: getGatewayMonthlyPerformanceReport
      parameters:
      - description: From date of transaction summary to be searched (this date is
          inclusive).
        example: 2022-03-29
        in: query
        name: from_date
        required: true
        schema:
          type: string
      - description: To date of transaction summary to be searched (this date is inclusive).
        example: 2022-03-29
        in: query
        name: to_date
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GatewayAccountMonthlyPerformanceReportEntity'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameters (from_date or to_date)
        "500":
          description: Internal Server Error for invalid query parameter values
      summary: Get monthly performance report by gateway account. Queries transaction_summary
        table
      tags:
      - Reports
  /v1/report/payments_by_state:
    get:
      operationId: getPaymentCountsByState
      parameters:
      - description: Gateway account ID. Required when override_account_id_restriction
          is 'false'
        example: 1
        in: query
        name: account_id
        schema:
          type: string
      - description: Set to true to return statistics for moto transactions
        example: false
        in: query
        name: include_moto_statistics
        schema:
          type: boolean
      - description: From date of transactions to be searched (this date is exclusive).
        example: 2022-03-29T00:00:00Z
        in: query
        name: from_date
        schema:
          type: string
      - description: To date of transactions to be searched (this date is exclusive).
        example: 2022-03-29T00:00:00Z
        in: query
        name: to_date
        schema:
          type: string
      - description: Set to true to get counts for all gateway accounts.
        in: query
        name: override_account_id_restriction
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                example:
                  timedout: 0
                  submitted: 0
                  declined: 0
                  created: 0
                  success: 1
                  cancelled: 0
                  started: 0
                  error: 0
                  undefined: 0
                  capturable: 0
          description: OK
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required or invalid query parameters (from_date or
            to_date)
      summary: Get number of payments by transaction (payment) state
      tags:
      - Reports
  /v1/report/performance-report:
    get:
      operationId: getPerformanceReport
      parameters:
      - description: From date of the transaction summary to be searched (this date
          is inclusive). Required when to_date is provided
        example: 2022-03-29
        in: query
        name: from_date
        schema:
          type: string
      - description: To date of the transaction summary to be searched (this date
          is inclusive). Required when from_date is provided
        example: 2022-03-29
        in: query
        name: to_date
        schema:
          type: string
      - description: Transaction state
        in: query
        name: state
        schema:
          type: string
          enum:
          - UNDEFINED
          - STARTED
          - CAPTURABLE
          - FAILED_REJECTED
          - FAILED_EXPIRED
          - FAILED_CANCELLED
          - CANCELLED
          - CREATED
          - SUBMITTED
          - SUCCESS
          - ERROR
          - ERROR_GATEWAY
          - NEEDS_RESPONSE
          - UNDER_REVIEW
          - LOST
          - WON
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceReportEntity'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: For missing query params or invalid state).
        "500":
          description: Internal Server Error for invalid query params (from_date/to_date)
            values
      summary: Get platform performance report (total volume and total_amount) for
        the date range and transaction state. Queries transaction_summary table for
        stats
      tags:
      - Reports
  /v1/report/performance-report-legacy:
    get:
      operationId: getLegacyPerformanceReport
      parameters:
      - description: From date of transactions to be searched (this date is inclusive).
        example: 2022-03-29T01:00:00Z
        in: query
        name: from_date
        schema:
          type: string
      - description: To date of transactions to be searched (this date is exclusive).
        example: 2022-03-29T01:00:00Z
        in: query
        name: to_date
        schema:
          type: string
      - description: Transaction state
        in: query
        name: state
        schema:
          type: string
          enum:
          - UNDEFINED
          - STARTED
          - CAPTURABLE
          - FAILED_REJECTED
          - FAILED_EXPIRED
          - FAILED_CANCELLED
          - CANCELLED
          - CREATED
          - SUBMITTED
          - SUCCESS
          - ERROR
          - ERROR_GATEWAY
          - NEEDS_RESPONSE
          - UNDER_REVIEW
          - LOST
          - WON
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceReportEntity'
          description: OK
        "500":
          description: Internal Server Error for invalid query parameter values
      summary: "Get platform performance report (total volume and total_amount) for\
        \ the date range and transaction state. Queries transaction table for stats,\
        \ so could be slow for large date ranges"
      tags:
      - Reports
  /v1/report/transactions-by-hour:
    get:
      operationId: getTransactionsByHour
      parameters:
      - description: From date of transaction summary to be searched (this date is
          inclusive).
        example: 2022-03-29T00:00:00Z
        in: query
        name: from_date
        required: true
        schema:
          type: string
      - description: To date of transaction summary to be searched (this date is inclusive).
        example: 2022-03-29T00:00:00Z
        in: query
        name: to_date
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeseriesReportSlice'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameters
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid query parameters (from_date or to_date)
      summary: Get transaction summary by hour
      tags:
      - Reports
  /v1/report/transactions-summary:
    get:
      operationId: getTransactionSummaryResult
      parameters:
      - description: Gateway account ID. Required when override_account_id_restriction
          is 'false'
        example: 1
        in: query
        name: account_id
        schema:
          type: string
      - description: Set to true to return statistics for moto transactions
        example: false
        in: query
        name: include_moto_statistics
        schema:
          type: boolean
      - description: From date of transactions to be searched (this date is exclusive).
        example: 2022-03-29T00:00:00Z
        in: query
        name: from_date
        schema:
          type: string
      - description: To date of transactions to be searched (this date is exclusive).
        example: 2022-03-29T00:00:00Z
        in: query
        name: to_date
        schema:
          type: string
      - description: Set to true to return summary for all accounts.
        in: query
        name: override_account_id_restriction
        schema:
          type: boolean
      - description: Set to true to make from_date non-mandatory.
        in: query
        name: override_from_date_validation
        schema:
          type: boolean
          default: false
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionSummaryResult'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameter (from_date)
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required or invalid query parameters (from_date or
            to_date)
      summary: Get transaction summary for query params
      tags:
      - Reports
  /v1/tasks/expunge-or-redact-historical-data:
    post:
      operationId: expungeOrRedactData
      responses:
        "200":
          description: OK
      summary: Redacts/Removes historical data based on `expungeOrRedactHistoricalDataConfig`.
        Currently redacts PII from transactions and deletes related transaction events
      tags:
      - Tasks
  /v1/transaction:
    get:
      operationId: search transactions
      parameters:
      - description: Set to '2' to return failed transaction states FAILED_REJECTED/FAILED_EXPIRED/FAILED_CANCELLED
          mapped to declined/timedout/cancelled external status respectively.Otherwise
          these transaction states will all be mapped to `failed` status
        in: query
        name: status_version
        schema:
          type: integer
          format: int32
          default: 2
      - description: Set to 'true' to search for transactions by exact reference.
          Otherwise reference is partially matched
        in: query
        name: exact_reference_match
        schema:
          type: boolean
          default: false
      - example: test@example.org
        in: query
        name: email
        schema:
          type: string
      - example: my-payment-reference
        in: query
        name: reference
        schema:
          type: string
      - example: J Doe
        in: query
        name: cardholder_name
        schema:
          type: string
      - example: 7890
        in: query
        name: last_digits_card_number
        schema:
          type: string
      - example: 123456
        in: query
        name: first_digits_card_number
        schema:
          type: string
      - description: Comma delimited payment states.
        example: "success,error"
        in: query
        name: payment_states
        schema:
          $ref: '#/components/schemas/CommaDelimitedSetParameter'
      - example: success
        in: query
        name: state
        schema:
          type: string
      - description: Comma delimited refund states.
        example: "success,error"
        in: query
        name: refund_states
        schema:
          $ref: '#/components/schemas/CommaDelimitedSetParameter'
      - description: Comma delimited card brands.
        example: "visa,mastercard"
        in: query
        name: card_brands
        schema:
          $ref: '#/components/schemas/CommaDelimitedSetParameter'
      - description: From date of transactions to be searched (this date is inclusive).
        example: 2015-08-14T12:35:00Z
        in: query
        name: from_date
        schema:
          type: string
      - description: To date of transactions to be searched (this date is inclusive).
        example: 2015-08-14T12:35:00Z
        in: query
        name: to_date
        schema:
          type: string
      - example: PAYMENT
        in: query
        name: transaction_type
        schema:
          type: string
          enum:
          - PAYMENT
          - REFUND
          - DISPUTE
      - example: po_fj893joishj12lndk
        in: query
        name: gateway_payout_id
        schema:
          type: string
      - description: From date of transactions settled date to be searched (this date
          is inclusive).
        example: 2015-08-14
        in: query
        name: from_settled_date
        schema:
          type: string
      - description: To date of transactions settled date to be searched (this date
          is inclusive).
        example: 2015-08-14
        in: query
        name: to_settled_date
        schema:
          type: string
      - example: metadata-value-1
        in: query
        name: metadata_value
        schema:
          type: string
      - example: 17ii98mg7f6si930tcjt48ldlc
        in: query
        name: agreement_id
        schema:
          type: string
      - example: 1
        in: query
        name: page
        schema:
          type: integer
          format: int64
      - example: 100
        in: query
        name: display_size
        schema:
          type: integer
          format: int64
          default: 500
      - description: Set to 'true' to limit the search counting the total number of
          transactions to 'limit_total_size' param
        example: true
        in: query
        name: limit_total
        schema:
          type: boolean
          default: false
      - example: 1000
        in: query
        name: limit_total_size
        schema:
          type: integer
          format: int64
          default: 10000
      - example: a14f0926-b44d-4160-8184-1b1f66e576ab
        in: query
        name: gateway_transaction_id
        schema:
          type: string
      - description: Comma delimited dispute states.
        example: "won,needs_response"
        in: query
        name: dispute_states
        schema:
          $ref: '#/components/schemas/CommaDelimitedSetParameter'
      - description: Set to true to list transactions for all accounts.
        in: query
        name: override_account_id_restriction
        schema:
          type: boolean
      - description: Comma delimited gateway account IDs. Required except when override_account_id_restriction=true
        example: "1,2"
        in: query
        name: account_id
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionSearchResponse'
          description: OK
        "400":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameters
        "504":
          description: Search query cancelled due to query timeout
      summary: Search transactions by query params. Same endpoint can be used to download
        CSV (with  Accept header="text/csv"). Refer to code for details
      tags:
      - Transactions
  /v1/transaction/gateway-transaction/{gatewayTransactionId}:
    get:
      operationId: findByGatewayTransactionId
      parameters:
      - description: Transaction ID from payment provider
        example: a14f0926-b44d-4160-8184-1b1f66e576ab
        in: path
        name: gatewayTransactionId
        required: true
        schema:
          type: string
      - example: sandbox
        in: query
        name: payment_provider
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/TransactionView'
          description: OK
        "404":
          description: Not found
        "422":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: If payment_provider query parameter is missing
      summary: Get transaction for a gateway transaction ID
      tags:
      - Transactions
  /v1/transaction/redact-reference/{transactionExternalId}:
    post:
      operationId: redactReference
      parameters:
      - in: path
        name: transactionExternalId
        required: true
        schema:
          type: string
      responses:
        default:
          content:
            application/json; qs=1: {}
          description: default response
      tags:
      - Transactions
  /v1/transaction/{parentTransactionExternalId}/transaction:
    get:
      operationId: getTransactionsForParentTransaction
      parameters:
      - description: Parent transaction external ID
        example: d0sk01d9amdk3ks0dk2dj03kd
        in: path
        name: parentTransactionExternalId
        required: true
        schema:
          type: string
      - description: Gateway account ID
        example: 1
        in: query
        name: gateway_account_id
        required: true
        schema:
          type: string
      - description: The type of transactions to return
        example: REFUND
        in: query
        name: transaction_type
        schema:
          type: string
          enum:
          - PAYMENT
          - REFUND
          - DISPUTE
      responses:
        "200":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/TransactionsForTransactionResponse'
          description: OK
        "404":
          description: Not found
        "422":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameter (gateway_account_id)
      summary: "Get transactions (ex: refunds) related to parent transaction (payment)"
      tags:
      - Transactions
  /v1/transaction/{transactionExternalId}:
    get:
      operationId: getById
      parameters:
      - in: path
        name: transactionExternalId
        required: true
        schema:
          type: string
      - in: query
        name: account_id
        schema:
          type: string
      - in: query
        name: override_account_id_restriction
        schema:
          type: boolean
      - in: query
        name: transaction_type
        schema:
          type: string
          enum:
          - PAYMENT
          - REFUND
          - DISPUTE
      - in: query
        name: parent_external_id
        schema:
          type: string
      - in: query
        name: status_version
        schema:
          type: integer
          format: int32
          default: 2
      responses:
        "200":
          content:
            application/json; qs=1:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionView'
          description: OK
        "400":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameters
        "500":
          description: Internal Server Error for invalid query parameter values
      summary: Get transaction by external ID
      tags:
      - Transactions
  /v1/transaction/{transactionExternalId}/event:
    get:
      operationId: events
      parameters:
      - description: Transaction external ID
        example: 9np5pocnotgkpp029d5kdfau5f
        in: path
        name: transactionExternalId
        required: true
        schema:
          type: string
      - example: 1
        in: query
        name: gateway_account_id
        required: true
        schema:
          type: string
      - description: Set to 'true' to return all events. By default events that do
          not map to an external state are removed and duplicate events mapping to
          same external state are reduced to one event.
        in: query
        name: include_all_events
        schema:
          type: boolean
          default: false
      - description: Set to '2' to return failed transaction states FAILED_REJECTED/FAILED_EXPIRED/FAILED_CANCELLED
          mapped to declined/timedout/cancelled status respectively.Otherwise these
          transaction states will all be mapped to `failed` status
        in: query
        name: status_version
        schema:
          type: integer
          format: int32
          default: 2
      responses:
        "200":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/TransactionEventResponse'
          description: OK
        "404":
          description: Not found
        "422":
          content:
            application/json; qs=1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing required query parameters
      summary: Get events for transaction external ID
      tags:
      - Transactions
components:
  schemas:
    Address:
      type: object
      properties:
        city:
          type: string
          example: London
        country:
          type: string
          example: GB
        county:
          type: string
          example: county
        line1:
          type: string
          example: address line 1
        line2:
          type: string
          example: address line 2
        postcode:
          type: string
          example: Ex 8RR
    Agreement:
      type: object
      properties:
        cancelled_by_user_email:
          type: string
        cancelled_date:
          type: string
          format: date-time
        created_date:
          type: string
          format: date-time
        description:
          type: string
        external_id:
          type: string
        live:
          type: boolean
        payment_instrument:
          $ref: '#/components/schemas/PaymentInstrument'
        reference:
          type: string
        service_id:
          type: string
        status:
          type: string
          enum:
          - CREATED
          - ACTIVE
          - INACTIVE
          - CANCELLED
        user_identifier:
          type: string
    AgreementEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    AgreementSearchResponse:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/PaginationBuilder'
        count:
          type: integer
          format: int64
        page:
          type: integer
          format: int64
        results:
          type: array
          items:
            $ref: '#/components/schemas/Agreement'
        total:
          type: integer
          format: int64
    AuthorisationSummary:
      type: object
      properties:
        three_d_secure:
          $ref: '#/components/schemas/ThreeDSecure'
    CardDetails:
      type: object
      properties:
        billing_address:
          $ref: '#/components/schemas/Address'
        card_brand:
          type: string
          example: Visa
        card_type:
          type: string
          enum:
          - CREDIT
          - DEBIT
          example: credit
        cardholder_name:
          type: string
          example: J Doe
        expiry_date:
          type: string
          example: 11/43
        first_digits_card_number:
          type: string
          example: "424242"
        last_digits_card_number:
          type: string
          example: "4242"
    CommaDelimitedSetParameter:
      type: object
      properties:
        notEmpty:
          type: boolean
        parameters:
          type: array
          items:
            type: string
        rawString:
          type: string
    ErrorResponse:
      type: object
      properties:
        error_identifier:
          type: string
          enum:
          - GENERIC
          - REFUND_NOT_AVAILABLE
          - REFUND_AMOUNT_AVAILABLE_MISMATCH
          - REFUND_NOT_AVAILABLE_DUE_TO_DISPUTE
          - ZERO_AMOUNT_NOT_ALLOWED
          - MOTO_NOT_ALLOWED
          - CANCEL_CHARGE_FAILURE_DUE_TO_CONFLICTING_TERMINAL_STATE_AT_GATEWAY_CHARGE_STATE_FORCIBLY_TRANSITIONED
          - CANCEL_CHARGE_FAILURE_DUE_TO_CONFLICTING_TERMINAL_STATE_AT_GATEWAY_INVALID_STATE_TRANSITION
          - AUTH_TOKEN_INVALID
          - AUTH_TOKEN_REVOKED
          - ACCOUNT_NOT_LINKED_WITH_PSP
          - TELEPHONE_PAYMENT_NOTIFICATIONS_NOT_ALLOWED
          - AGREEMENT_NOT_FOUND
          - ONE_TIME_TOKEN_INVALID
          - ONE_TIME_TOKEN_ALREADY_USED
          - INVALID_ATTRIBUTE_VALUE
          - CARD_NUMBER_REJECTED
          - AUTHORISATION_API_NOT_ALLOWED
          - AUTHORISATION_REJECTED
          - AUTHORISATION_ERROR
          - AUTHORISATION_TIMEOUT
          - AGREEMENT_NOT_ACTIVE
          - INCORRECT_AUTHORISATION_MODE_FOR_SAVE_PAYMENT_INSTRUMENT_TO_AGREEMENT
          - MISSING_MANDATORY_ATTRIBUTE
          - UNEXPECTED_ATTRIBUTE
          - ACCOUNT_DISABLED
          - RECURRING_CARD_PAYMENTS_NOT_ALLOWED
          - IDEMPOTENCY_KEY_USED
          - CARD_NUMBER_IN_PAYMENT_LINK_REFERENCE_REJECTED
          example: GENERIC
        message:
          type: array
          items:
            type: string
            example: example error message
    Event:
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            type: object
            example: "{\"live\": false, \"moto\": false, \"amount\": 1000, \"source\"\
              : \"CARD_API\", \"language\": \"en\", \"reference\": \"my payment reference\"\
              , \"return_url\": \"https://www.payments.service.gov.uk\", \"description\"\
              : \"my payment\", \"delayed_capture\": false, \"payment_provider\":\
              \ \"sandbox\", \"gateway_account_id\": \"3\", \"credential_external_id\"\
              : \"ddb294481de146c09598c8cce0461af9\", \"save_payment_instrument_to_agreement\"\
              : false}\""
          example: "{\"live\": false, \"moto\": false, \"amount\": 1000, \"source\"\
            : \"CARD_API\", \"language\": \"en\", \"reference\": \"my payment reference\"\
            , \"return_url\": \"https://www.payments.service.gov.uk\", \"description\"\
            : \"my payment\", \"delayed_capture\": false, \"payment_provider\": \"\
            sandbox\", \"gateway_account_id\": \"3\", \"credential_external_id\":\
            \ \"ddb294481de146c09598c8cce0461af9\", \"save_payment_instrument_to_agreement\"\
            : false}\""
        event_type:
          type: string
          example: CREATED
        live:
          type: boolean
          example: true
        resource_external_id:
          type: string
          example: 58na2dr7rv7h6h53bef1l0soep
        resource_type:
          type: string
          example: AGREEMENT
        service_id:
          type: string
          example: ea2d6673b23d4ff7ad88a1fd3c7ab0f6
        timestamp:
          type: string
          format: date-time
    EventMessageDto:
      type: object
      properties:
        event_details:
          type: string
        event_type:
          type: string
        live:
          type: boolean
        parent_resource_external_id:
          type: string
        reproject_domain_object:
          type: boolean
        resource_external_id:
          type: string
        resource_type:
          type: string
          enum:
          - agreement
          - payment
          - refund
          - service
          - card_payment
          - payout
          - dispute
          - payment_instrument
        service_id:
          type: string
        timestamp:
          type: string
          format: date-time
      required:
      - event_type
      - resource_external_id
      - resource_type
      - timestamp
    EventTicker:
      type: object
      properties:
        amount:
          type: integer
          format: int64
          example: 100
        card_brand:
          type: string
          example: visa
        event_date:
          type: string
          format: date-time
        event_type:
          type: string
          example: PAYMENT_CREATED
        gateway_account_id:
          type: string
          example: "1"
        is_moto:
          type: boolean
          example: true
        is_recurring:
          type: boolean
          example: true
        payment_provider:
          type: string
          example: sandbox
        resource_external_id:
          type: string
          example: 9np5pocnotgkpp029d5kdfau5f
        resource_type:
          type: string
          enum:
          - agreement
          - payment
          - refund
          - service
          - card_payment
          - payout
          - dispute
          - payment_instrument
          example: payment
        service_external_id:
          type: string
          example: HrMU7UgY7OUM8fgT2bZCTKzvKu
        source:
          type: string
          example: CARD_API
        transaction_type:
          type: string
          example: PAYMENT
        wallet_type:
          type: string
          example: APPLE_PAY
    ExternalTransactionState:
      type: object
      properties:
        can_retry:
          type: boolean
          description: Only applicable for failed recurring payments. Default value
            is null
          example: true
          nullable: true
        code:
          type: string
          example: P0030
        finished:
          type: boolean
          example: true
        message:
          type: string
          example: Payment was cancelled by the user
        status:
          type: string
          example: cancelled
    GatewayAccountMonthlyPerformanceReportEntity:
      type: object
      properties:
        average_amount:
          type: number
          example: 1000.0
        gateway_account_id:
          type: integer
          format: int64
          example: 1
        month:
          type: integer
          format: int64
          example: 3
        total_amount:
          type: number
          example: 1000
        total_volume:
          type: integer
          format: int64
          example: 1
        year:
          type: integer
          format: int64
          example: 2022
    PaginationBuilder:
      type: object
      properties:
        first_page:
          $ref: '#/components/schemas/PaginationLink'
        last_page:
          $ref: '#/components/schemas/PaginationLink'
        next_page:
          $ref: '#/components/schemas/PaginationLink'
        prev_page:
          $ref: '#/components/schemas/PaginationLink'
        self:
          $ref: '#/components/schemas/PaginationLink'
    PaginationLink:
      type: object
      properties:
        href:
          type: string
          example: https://an.example.link
    PaymentInstrument:
      type: object
      properties:
        agreement_external_id:
          type: string
        card_details:
          $ref: '#/components/schemas/CardDetails'
        created_date:
          type: string
          format: date-time
        external_id:
          type: string
        type:
          type: string
          enum:
          - CARD
    PayoutSearchResponse:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/PaginationBuilder'
        count:
          type: integer
          format: int64
          example: 100
        page:
          type: integer
          format: int64
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/PayoutView'
        total:
          type: integer
          format: int64
          example: 1000
    PayoutView:
      type: object
      properties:
        amount:
          type: integer
          format: int64
          description: amount in pence
          example: 1000
        created_date:
          type: string
          format: date-time
        gateway_account_id:
          type: string
          example: "1"
        gateway_payout_id:
          type: string
          example: po_sd0fkpam0dlwe10dmlsl3mf
        live:
          type: boolean
          example: true
        paid_out_date:
          type: string
          format: date-time
        service_id:
          type: string
          example: dlsd0dkad20sk0adne9fjd
        state:
          type: string
          enum:
          - UNDEFINED
          - IN_TRANSIT
          - PAID_OUT
          - FAILED
          example: "{\"status\":\"paidout\",\"finished\":true}"
    PerformanceReportEntity:
      type: object
      properties:
        average_amount:
          type: number
          example: 1000.0
        total_amount:
          type: number
          example: 1000
        total_volume:
          type: integer
          format: int64
          example: 1
    RefundSummary:
      type: object
      properties:
        amount_available:
          type: integer
          format: int64
        amount_refunded:
          type: integer
          format: int64
        amount_submitted:
          type: integer
          format: int64
        status:
          type: string
          example: unavailable
        user_external_id:
          type: string
    SettlementSummary:
      type: object
      properties:
        settled_date:
          type: string
          example: 2022-01-26
    ThreeDSecure:
      type: object
      properties:
        required:
          type: boolean
          description: '`true` if payment requires 3D Secure authentication. '
          example: true
        version:
          type: string
          example: 2.1.0
    TimeseriesReportSlice:
      type: object
      properties:
        all_payments:
          type: integer
          format: int32
          example: 10
        amount:
          type: integer
          format: int32
          example: 70
        completed_payments:
          type: integer
          format: int32
          example: 7
        errored_payments:
          type: integer
          format: int32
          example: 3
        fee:
          type: integer
          format: int32
        net_amount:
          type: integer
          format: int32
        timestamp:
          type: string
          format: date-time
        total_amount:
          type: integer
          format: int32
    TransactionEvent:
      type: object
      properties:
        amount:
          type: integer
          format: int64
          example: 1000
        data:
          type: object
          additionalProperties:
            type: object
        event_type:
          type: string
          example: CANCELLED_BY_USER
        resource_type:
          type: string
          example: PAYMENT
        state:
          $ref: '#/components/schemas/ExternalTransactionState'
        timestamp:
          type: string
          format: date-time
    TransactionEventResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/TransactionEvent'
        transaction_id:
          type: string
          example: 9np5pocnotgkpp029d5kdfau5f
    TransactionSearchResponse:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/PaginationBuilder'
        count:
          type: integer
          format: int64
        page:
          type: integer
          format: int64
        results:
          type: array
          items:
            $ref: '#/components/schemas/TransactionView'
        total:
          type: integer
          format: int64
    TransactionSummaryResult:
      type: object
      properties:
        moto_payments:
          $ref: '#/components/schemas/TransactionsStatisticsResult'
        net_income:
          type: integer
          format: int64
          example: 6000
        payments:
          $ref: '#/components/schemas/TransactionsStatisticsResult'
        refunds:
          $ref: '#/components/schemas/TransactionsStatisticsResult'
    TransactionView:
      type: object
      properties:
        agreement_id:
          type: string
        amount:
          type: integer
          format: int64
          example: 1000
        authorisation_mode:
          type: string
          enum:
          - web
          - moto_api
          - agreement
          - external
          example: web
        authorisation_summary:
          $ref: '#/components/schemas/AuthorisationSummary'
        card_details:
          $ref: '#/components/schemas/CardDetails'
        corporate_card_surcharge:
          type: integer
          format: int64
          example: 0
        created_date:
          type: string
          format: date-time
        credential_external_id:
          type: string
          example: 7a7a718cb8b0401f8b8f4cdda9804073
        delayed_capture:
          type: boolean
        description:
          type: string
          example: New passport application
        disputed:
          type: boolean
        email:
          type: string
          example: citizen@example.org
        evidence_due_date:
          type: string
          format: date-time
        fee:
          type: integer
          format: int64
          example: 2
        gateway_account_id:
          type: string
          example: "1"
        gateway_payout_id:
          type: string
          example: po_mdoiu23jkdj1kj23sd
        gateway_transaction_id:
          type: string
          example: fd21-1mdknkls1-2121-csdf
        language:
          type: string
          example: en
        live:
          type: boolean
        metadata:
          type: object
          additionalProperties:
            type: object
        moto:
          type: boolean
        net_amount:
          type: integer
          format: int64
          example: -2
        parent_transaction_id:
          type: string
          description: Parent transaction external ID. Available for refunds
          example: 4dfdhapsdgftgkpp029d5kdfau5f
        payment_details:
          $ref: '#/components/schemas/TransactionView'
        payment_provider:
          type: string
          example: sandbox
        reason:
          type: string
          example: fraudulent
        reference:
          type: string
          example: payment reference
        refund_summary:
          $ref: '#/components/schemas/RefundSummary'
        refunded_by:
          type: string
          description: External ID of the service user that refunded payment. Only
            available for refunds
          example: dj8923eihsdih23hkjfe8d
        refunded_by_user_email:
          type: string
          description: Service user email that refunded the payment. Only available
            for refunds
          example: test@example.org
        return_url:
          type: string
          example: https://service-name.gov.uk/transactions/12345
        service_id:
          type: string
          example: baea0585e30d4acbb438524fca82b51e
        settlement_summary:
          $ref: '#/components/schemas/SettlementSummary'
        source:
          type: string
          enum:
          - CARD_API
          - CARD_PAYMENT_LINK
          - CARD_AGENT_INITIATED_MOTO
          - CARD_EXTERNAL_TELEPHONE
          example: CARD_API
        state:
          $ref: '#/components/schemas/ExternalTransactionState'
        total_amount:
          type: integer
          format: int64
          example: 1000
        transaction_id:
          type: string
          example: 9np5pocnotgkpp029d5kdfau5f
        transaction_type:
          type: string
          enum:
          - PAYMENT
          - REFUND
          - DISPUTE
          example: PAYMENT
        wallet_type:
          type: string
          example: APPLE_PAY
    TransactionsForTransactionResponse:
      type: object
      properties:
        parent_transaction_id:
          type: string
          example: 9np5pocnotgkpp029d5kdfau5f
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionView'
    TransactionsStatisticsResult:
      type: object
      properties:
        count:
          type: integer
          format: int64
          example: 1
        gross_amount:
          type: integer
          format: int64
          example: 2000