Dojo Transactions API

openapi: 3.2.0
info:
  title: Transactions API
  version: '2023-11-12'
  description: '# Introduction

    The Dojo Transaction API is RESTful.'
  termsOfService: https://dojo.tech/legal/
  contact:
    name: Dojo Developer Experience Team
servers:
- url: https://api.dojo.tech
security:
- ApiKeyAuth: []
tags:
- name: Transactions
  description: Allows you to take and manage payments.
paths:
  /transactions/search:
    post:
      tags:
      - Transactions
      operationId: Transactions_Search
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTransactionsRequest'
        required: true
        x-position: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedTransaction'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      parameters:
      - name: version
        in: header
        required: true
        schema:
          type: string
          format: date
        example: '2022-04-07'
        description: 'The API version with format `yyyy-mm-dd`. The Current version is `2022-04-07`.

          Today''s date will always give you the latest version. '
      summary: List all transactions
      description: 'Retrieves a list of transactions.

        Results are paginated. By default, the method returns up to 50 transactions.'
components:
  schemas:
    Card:
      title: Card
      type: object
      example:
        number: '**********0027'
        fundingType: Debit
        type: Mastercard
      properties:
        number:
          type:
          - string
          - 'null'
          description: The card number. Masked for security.
        fundingType:
          type:
          - string
          - 'null'
          description: 'Card funding type for example: `Credit`, `Debit`, etc...'
        type:
          type:
          - string
          - 'null'
          description: 'Card scheme for example: `Visa`, `Mastercard`, etc.'
    TransactionStatus:
      type: string
      description: Current status of the transaction.
      title: TransactionStatus
      enum:
      - Authorized
      - Declined
      - Held
      - UnderReview
      - Reversed
      - AwaitingCollection
      - Released
      - Expired
    ProblemDetails:
      type: object
      title: ProblemDetails
      description: ''
      properties:
        type:
          type:
          - string
          - 'null'
          description: 'Card scheme for example: `Visa`, `Mastercard`, etc.'
        title:
          type:
          - string
          - 'null'
          description: 'A short, human-readable summary of the error.

            '
        status:
          type:
          - integer
          - 'null'
          format: int32
          description: The [HTTP status code](#section/Introduction/HTTP-Responses).
        detail:
          type:
          - string
          - 'null'
          description: 'A human-readable message giving more details about the error. This field is optional, so it''s not always present. '
        traceId:
          type:
          - string
          - 'null'
          description: 'The unique identifier of the failing request. This should be used to track the source of the error.

            '
        errors:
          type:
          - object
          - 'null'
          description: A human-readable explanation of errors.
          additionalProperties: {}
    PaymentDetails:
      title: PaymentDetails
      type: object
      properties:
        card:
          $ref: '#/components/schemas/Card'
        authCode:
          type:
          - string
          - 'null'
          description: Authorization code for the transaction.
        isRemote:
          type: boolean
          description: Indiciates if a transaction was made using remote or terminal gateway.
        paymentProduct:
          $ref: '#/components/schemas/PaymentProduct'
        terminalEntryModeType:
          $ref: '#/components/schemas/TerminalEntryModeType'
        terminalId:
          type:
          - string
          - 'null'
          description: The ID of the terminal used for payment.
    TransactionType:
      type: string
      description: Types of transaction.
      title: TransactionType
      enum:
      - Sale
      - Refund
      - PreAuth
      - Collection
    Transaction:
      type: object
      additionalProperties: false
      description: The Transaction object.
      title: Transaction
      properties:
        id:
          type: string
          description: 'Unique identifier for the transaction.

            '
        legacyId:
          type: string
          description: 'Unique identifier for the transaction (legacy form).

            '
        dateTime:
          type: string
          format: date-time
          description: The timestamp of the transaction, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format.
        paymentIntentId:
          type:
          - string
          - 'null'
          description: If the transaction was made using a payment intent, its ID will be included here.
        merchantId:
          type:
          - string
          - 'null'
          description: 'The merchant''s unique identifier (MID).

            '
        type:
          $ref: '#/components/schemas/TransactionType'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        amount:
          oneOf:
          - $ref: '#/components/schemas/Money'
          description: The transaction's sale amount.
        cashbackAmount:
          oneOf:
          - $ref: '#/components/schemas/Money'
          description: The cashback amount of the transaction.
        tipsAmount:
          oneOf:
          - $ref: '#/components/schemas/Money'
          description: Expressed as a positive integer, this is the amount of tip (gratuity) attached to a transaction.
        reference:
          type:
          - string
          - 'null'
          description: The reference (or merchant provided order ID) of the transaction.
        paymentDetails:
          oneOf:
          - $ref: '#/components/schemas/PaymentDetails'
          description: The details of the payment associated with the transaction including payment product, card information, etc.
    Cursor:
      type: object
      additionalProperties: false
      description: A cursor for use in pagination.
      properties:
        limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          example: 20
          default: 50
          description: The maximum number of results that can be returned in a single page.
        before:
          type:
          - string
          - 'null'
          description: 'A cursor for use in pagination. Returns you to the previous page. `before` and `after`

            are mutually exclusive—only one of these may be used.'
        after:
          type:
          - string
          - 'null'
          description: 'A cursor for use in pagination. Sends you to the next page. `before` and `after` are

            mutually exclusive—only one of these may be used.'
    SearchTransactionsRequest:
      type: object
      additionalProperties: false
      description: ''
      required:
      - startDate
      - endDate
      properties:
        startDate:
          type:
          - string
          - 'null'
          format: date-time
          description: 'A date and time to display transaction results from, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. The span between the start and end dates cannot exceed 7 days.

            '
        endDate:
          type:
          - string
          - 'null'
          format: date-time
          description: 'A date and time to display transaction results until, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. The span between the start and end dates cannot exceed 7 days.

            '
        cursor:
          oneOf:
          - $ref: '#/components/schemas/Cursor'
          description: A cursor for use in pagination.
      example:
        statuses:
        - Authorized
        startDate: '2019-08-24T14:15:22Z'
        endDate: '2023-08-24T14:15:22Z'
        cursor:
          limit: 20
    TerminalEntryModeType:
      type: string
      description: Indicates the entry mode used on a payment made using a terminal.
      title: TerminalEntryModeType
      enum:
      - Chip
      - ContactLess
      - Swipe
      - Keyed
      - Unknown
    PagedTransaction:
      allOf:
      - $ref: '#/components/schemas/PagedResultOfTransaction'
      - type: object
        additionalProperties: false
    Money:
      title: Money
      type: object
      example:
        value: 1000
        currencyCode: GBP
      properties:
        value:
          type: integer
          description: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example "100" for 1.00 GBP.
          format: int64
        currencyCode:
          type: string
          description: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`.
          minLength: 1
          maxLength: 10
      required:
      - value
      - currencyCode
    PaymentProduct:
      type: string
      description: The Dojo payment product associated with this transaction.
      title: PaymentProduct
      enum:
      - TapToPayOnIPhone
      - DojoPocket
      - Terminal
      - OnlineCheckout
      - VirtualTerminal
      - PaymentLinks
      - DojoBookings
      - PayByQr
      - Other
    PagedResultOfTransaction:
      type: object
      additionalProperties: false
      properties:
        data:
          type:
          - array
          - 'null'
          description: 'An array of transactions.

            '
          items:
            $ref: '#/components/schemas/Transaction'
        before:
          type:
          - string
          - 'null'
          description: 'A cursor for use in pagination. Returns you to the previous page. `before` and `after`

            are mutually exclusive—only one of these may be used.'
        after:
          type:
          - string
          - 'null'
          description: 'A cursor for use in pagination. Sends you to the next page. `before` and `after` are

            mutually exclusive—only one of these may be used.'
  securitySchemes:
    ApiKeyAuth:
      in: header
      type: apiKey
      name: Authorization
x-generator: NSwag v13.12.1.0 (NJsonSchema v10.4.6.0 (Newtonsoft.Json v12.0.0.0))
x-tagGroup:
- name: Payments
  tags:
  - transactions
  - Refunds
  - Captures