Dojo Transactions API

openapi: 3.2.0
info:
  title: Transactions API
  version: '2023-11-12'
  description: "# Introduction\nThe Dojo Transaction API is RESTful. It returns HTTP response codes to indicate errors. It also\naccepts and returns JSON in the HTTP body.\n\n## Base URLs\nUse the following base URL when making requests to the API:  https://api.dojo.tech/\n\n## Authentication\nThe Transaction API uses [Basic HTTP auth](https://en.wikipedia.org/wiki/Basic_access_authentication). You can generate API keys in [Developer Portal](https://developer.dojo.tech).\nSecret keys for the test environment have the prefix `sk_sandbox_` and for production have the prefix `sk_prod_`.\nYou must include your secret API key in the header of all requests, for example:\n\n```curl\ncurl\n  --header 'content-type: application/json' \\\n  --header 'Authorization: Basic sk_prod_your_key' \\\n...\n```\n\nAPI requests without authentication will fail.\n\n## HTTP Responses\n\nThe API returns standard HTTP response codes [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6) on each request to indicate the success or otherwise of API requests. HTTP status codes summary are listed below:\n* `200 OK`—The request was successful.\n* `201 Created`—The request was successful, and a new resource was created as a result.\n* `204 No Content`—The request was successful, but there is no content to send.\n* `400 Bad Request`—Bad request, probably due to a syntax error.\n* `401 Unauthorized`—Authentication required.\n* `403 Forbidden`—The API key doesn't have permissions.\n* `404 Not Found`—The resource doesn't exist.\n* `405 Method Not Allowed`—The request method is known by the server but isn't supported by the target resource.\n* `409 Conflict`—The request couldn't be completed because it conflicted with another request or the server's configuration.\n* `500`, `502`, `503`, `504` `Server Errors`—An error occurred with our API.\n\n## Errors\n\nDojo follows the error response format proposed in [RFC 7807](https://tools.ietf.org/html/rfc7807) also known as Problem Details for HTTP APIs. All errors are returned in the form of JSON.\n\n### Error Schema\n\nIn case of an error, the response object contains the following fields:\n* `errors` [object]—A human-readable explanation of errors.\n* `type` [string]—\nA URI reference RFC 3986 that identifies the problem type.\n* `title` [string]—A short, human-readable summary of the error.\n* `status` [integer]—The HTTP status code.\n* `detail` [string]—A human-readable message giving more details about the error. Not always present.\n* `traceId` [string]—The unique identifier of the failing request.\nThe following example shows a possible error response:\n\n```json\n{\n    \"errors\": {\n        \"Reference\": [\n            \"The Reference field is required.\"\n        ]\n    },\n    \"type\": \"https://tools.ietf.org/html/rfc7231#section-6.5.1\",\n    \"title\": \"One or more validation errors occurred.\",\n    \"status\": 400,\n    \"traceId\": \"00-a405f077df056a498323ffbcec05923f-aa63e6f4dbbc734a-01\",\n}\n```\n\n## Versioning\n\nDojo APIs use the yyyy-mm-dd API version-naming scheme. You have to pass the version as the `version` header in all API calls, for example:\n\n``` curl\ncurl\n  --header 'content-type: application/json' \\\n  --header 'Authorization: Basic sk_prod_your_key' \\\n  --header 'version: 2023-11-12' \\\n```"
  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:
    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.'
    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.
    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
    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
    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: {}
    PaymentProduct:
      type: string
      description: The Dojo payment product associated with this transaction.
      title: PaymentProduct
      enum:
      - TapToPayOnIPhone
      - DojoPocket
      - Terminal
      - OnlineCheckout
      - VirtualTerminal
      - PaymentLinks
      - DojoBookings
      - PayByQr
      - Other
    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.'
    TransactionType:
      type: string
      description: Types of transaction.
      title: TransactionType
      enum:
      - Sale
      - Refund
      - PreAuth
      - Collection
    TerminalEntryModeType:
      type: string
      description: Indicates the entry mode used on a payment made using a terminal.
      title: TerminalEntryModeType
      enum:
      - Chip
      - ContactLess
      - Swipe
      - Keyed
      - Unknown
    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.'
  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