Dojo Transaction API

{
  "openapi": "3.0.0",
  "info": {
    "title": "Transaction 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`.\nToday's date will always give you the latest version. "
          }
        ],
        "summary": "List all transactions",
        "description": "Retrieves a list of transactions.\nResults are paginated. By default, the method returns up to 50 transactions."
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "in": "header",
        "type": "apiKey",
        "name": "Authorization"
      }
    },
    "schemas": {
      "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"
        ]
      },
      "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.\n",
            "nullable": false
          },
          "legacyId": {
            "type": "string",
            "description": "Unique identifier for the transaction (legacy form).\n",
            "nullable": false
          },
          "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",
            "description": "If the transaction was made using a payment intent, its ID will be included here.",
            "nullable": true
          },
          "merchantId": {
            "type": "string",
            "description": "The merchant's unique identifier (MID).\n",
            "nullable": true
          },
          "type": {
            "$ref": "#/components/schemas/TransactionType",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/TransactionStatus",
            "nullable": true
          },
          "amount": {
            "nullable": false,
            "oneOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "description": "The transaction's sale amount."
          },
          "cashbackAmount": {
            "nullable": false,
            "oneOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "description": "The cashback amount of the transaction."
          },
          "tipsAmount": {
            "nullable": false,
            "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",
            "description": "The reference (or merchant provided order ID) of the transaction.",
            "nullable": true
          },
          "paymentDetails": {
            "nullable": false,
            "oneOf": [
              {
                "$ref": "#/components/schemas/PaymentDetails"
              }
            ],
            "description": "The details of the payment associated with the transaction including payment product, card information, etc."
          }
        }
      },
      "Card": {
        "title": "Card",
        "type": "object",
        "example": {
          "number": "**********0027",
          "fundingType": "Debit",
          "type": "Mastercard"
        },
        "properties": {
          "number": {
            "type": "string",
            "description": "The card number. Masked for security.",
            "nullable": true
          },
          "fundingType": {
            "type": "string",
            "description": "Card funding type for example: `Credit`, `Debit`, etc...",
            "nullable": true
          },
          "type": {
            "type": "string",
            "description": "Card scheme for example: `Visa`, `Mastercard`, etc.",
            "nullable": true
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "title": "ProblemDetails",
        "description": "",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true,
            "description": "Card scheme for example: `Visa`, `Mastercard`, etc."
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "A short, human-readable summary of the error.\n"
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "The [HTTP status code](#section/Introduction/HTTP-Responses)."
          },
          "detail": {
            "type": "string",
            "nullable": true,
            "description": "A human-readable message giving more details about the error. This field is optional, so it's not always present. "
          },
          "traceId": {
            "type": "string",
            "nullable": true,
            "description": "The unique identifier of the failing request. This should be used to track the source of the error.\n"
          },
          "errors": {
            "type": "object",
            "nullable": true,
            "description": "A human-readable explanation of errors.",
            "additionalProperties": {}
          }
        }
      },
      "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",
            "description": "A cursor for use in pagination. Returns you to the previous page. `before` and `after`\nare mutually exclusive—only one of these may be used.",
            "nullable": true
          },
          "after": {
            "type": "string",
            "description": "A cursor for use in pagination. Sends you to the next page. `before` and `after` are\nmutually exclusive—only one of these may be used.",
            "nullable": true
          }
        }
      },
      "SearchTransactionsRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "",
        "required": [
          "startDate",
          "endDate"
        ],
        "properties": {
          "startDate": {
            "type": "string",
            "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.\n",
            "nullable": true
          },
          "endDate": {
            "type": "string",
            "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.\n",
            "nullable": true
          },
          "cursor": {
            "nullable": true,
            "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
          }
        }
      },
      "PagedResultOfTransaction": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "array",
            "nullable": true,
            "description": "An array of transactions.\n",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          },
          "before": {
            "type": "string",
            "description": "A cursor for use in pagination. Returns you to the previous page. `before` and `after`\nare mutually exclusive—only one of these may be used.",
            "nullable": true
          },
          "after": {
            "type": "string",
            "description": "A cursor for use in pagination. Sends you to the next page. `before` and `after` are\nmutually exclusive—only one of these may be used.",
            "nullable": true
          }
        }
      },
      "PagedTransaction": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PagedResultOfTransaction"
          },
          {
            "type": "object",
            "additionalProperties": false
          }
        ]
      },
      "PaymentProduct": {
        "type": "string",
        "description": "The Dojo payment product associated with this transaction.",
        "title": "PaymentProduct",
        "enum": [
          "TapToPayOnIPhone",
          "DojoPocket",
          "Terminal",
          "OnlineCheckout",
          "VirtualTerminal",
          "PaymentLinks",
          "DojoBookings",
          "PayByQr",
          "Other"
        ]
      },
      "TerminalEntryModeType": {
        "type": "string",
        "description": "Indicates the entry mode used on a payment made using a terminal.",
        "title": "TerminalEntryModeType",
        "enum": [
          "Chip",
          "ContactLess",
          "Swipe",
          "Keyed",
          "Unknown"
        ]
      },
      "PaymentDetails": {
        "title": "PaymentDetails",
        "type": "object",
        "properties": {
          "card": {
            "$ref": "#/components/schemas/Card"
          },
          "authCode": {
            "type": "string",
            "description": "Authorization code for the transaction.",
            "nullable": true
          },
          "isRemote": {
            "type": "boolean",
            "description": "Indiciates if a transaction was made using remote or terminal gateway."
          },
          "paymentProduct": {
            "$ref": "#/components/schemas/PaymentProduct",
            "nullable": true
          },
          "terminalEntryModeType": {
            "$ref": "#/components/schemas/TerminalEntryModeType",
            "nullable": true
          },
          "terminalId": {
            "type": "string",
            "description": "The ID of the terminal used for payment.",
            "nullable": true
          }
        }
      }
    }
  },
  "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"
      ]
    }
  ]
}