Tribe Payments Point of Sale Device Directory API (v3) for registering, managing, and querying the estate of physical and SoftPOS payment terminals (devices) connected to Tribe's acquiring platform. Harvested verbatim from the Tribe developer portal.
{
"openapi": "3.0.0",
"info": {
"title": "Device Directory API",
"version": "3.0.0"
},
"tags": [
{
"name": "Processor"
},
{
"name": "App"
},
{
"name": "Host"
}
],
"paths": {
"/processors/{processorId}/hosts": {
"get": {
"tags": [
"Processor"
],
"summary": "Get a list of hosts assigned to processor",
"description": "Endpoint to fetch hosts list with page-based pagination.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "created[from]",
"in": "query",
"description": "Filter transactions from this date (inclusive). Format: ISO 8601 (YYYY-MM-DDThh:mm:ss.sss±hh:mm).",
"example": "2024-09-26T14:45:30.123+02:00",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "created[to]",
"in": "query",
"description": "Filter transactions up to this date (inclusive). Format: ISO 8601 (YYYY-MM-DDThh:mm:ss.sss±hh:mm).",
"example": "2024-09-26T14:45:30.123+02:00",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "externalReferenceId",
"in": "query",
"description": "Filter by the host external reference id.",
"required": false,
"schema": {
"type": "string",
"example": "SP000000004"
}
},
{
"name": "url",
"in": "query",
"description": "Filter by the host url.",
"required": false,
"schema": {
"type": "string",
"example": "test-v1-all-all"
}
},
{
"name": "page",
"in": "query",
"description": "The page number to retrieve.",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "limit",
"in": "query",
"description": "The number of hosts per page.",
"required": false,
"schema": {
"type": "integer",
"example": 50
}
}
],
"responses": {
"200": {
"description": "Devices fetched successfully.",
"headers": {
"X-Total-Count": {
"description": "The total number of hosts available.",
"schema": {
"type": "integer",
"example": 1000
}
},
"X-Total-Pages": {
"description": "The total number of pages available.",
"schema": {
"type": "integer",
"example": 20
}
},
"X-Current-Page": {
"description": "The current page number.",
"schema": {
"type": "integer",
"example": 1
}
},
"X-Next-Page": {
"description": "The next page number, if available.",
"schema": {
"type": "integer",
"example": 2
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Host"
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"Processor"
],
"summary": "Create a host.",
"description": "Endpoint to create a host.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "idempotency-key",
"in": "header",
"description": "A unique key to ensure idempotent requests. It should be a UUID or unique string to prevent duplicate transactions.",
"required": false,
"schema": {
"type": "string",
"example": "f5033990-1965-4bd6-86d5-cdc274164553"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostCreate"
}
}
}
},
"responses": {
"201": {
"description": "Host created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Host"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/processors/{processorId}/hosts/{hostId}": {
"get": {
"tags": [
"Processor"
],
"summary": "Get a host",
"description": "Endpoint to fetch a host.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device fetched successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Host"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": [
"Processor"
],
"summary": "Update a host.",
"description": "Endpoint to update a host.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "idempotency-key",
"in": "header",
"description": "A unique key to ensure idempotent requests. It should be a UUID or unique string to prevent duplicate transactions.",
"required": false,
"schema": {
"type": "string",
"example": "f5033990-1965-4bd6-86d5-cdc274164553"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostCreate"
}
}
}
},
"responses": {
"200": {
"description": "Host updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostCreate"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"Processor"
],
"summary": "Delete a host",
"description": "Endpoint to delete host.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "idempotency-key",
"in": "header",
"description": "A unique key to ensure idempotent requests. It should be a UUID or unique string to prevent duplicate transactions.",
"required": false,
"schema": {
"type": "string",
"example": "f5033990-1965-4bd6-86d5-cdc274164553"
}
}
],
"responses": {
"204": {
"description": "Host deleted."
},
"404": {
"description": "Host not found."
}
}
}
},
"/processors/{processorId}/devices": {
"get": {
"tags": [
"Processor"
],
"summary": "Get a list of devices assigned to processor",
"description": "Endpoint to fetch device list with page-based pagination.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "created[from]",
"in": "query",
"description": "Filter transactions from this date (inclusive). Format: ISO 8601 (YYYY-MM-DDThh:mm:ss.sss±hh:mm).",
"example": "2024-09-26T14:45:30.123+02:00",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "created[to]",
"in": "query",
"description": "Filter transactions up to this date (inclusive). Format: ISO 8601 (YYYY-MM-DDThh:mm:ss.sss±hh:mm).",
"example": "2024-09-26T14:45:30.123+02:00",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "serialNumber",
"in": "query",
"description": "Filter by the device serial number.",
"required": false,
"schema": {
"type": "string",
"example": "SP000000004"
}
},
{
"name": "configurationTag",
"in": "query",
"description": "Filter by the device configuration tag.",
"required": false,
"schema": {
"type": "string",
"example": "test-v1-all-all"
}
},
{
"name": "page",
"in": "query",
"description": "The page number to retrieve.",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "limit",
"in": "query",
"description": "The number of devices per page.",
"required": false,
"schema": {
"type": "integer",
"example": 50
}
}
],
"responses": {
"200": {
"description": "Devices fetched successfully.",
"headers": {
"X-Total-Count": {
"description": "The total number of devices available.",
"schema": {
"type": "integer",
"example": 1000
}
},
"X-Total-Pages": {
"description": "The total number of pages available.",
"schema": {
"type": "integer",
"example": 20
}
},
"X-Current-Page": {
"description": "The current page number.",
"schema": {
"type": "integer",
"example": 1
}
},
"X-Next-Page": {
"description": "The next page number, if available.",
"schema": {
"type": "integer",
"example": 2
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Device"
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/processors/{processorId}/devices/{deviceId}": {
"get": {
"tags": [
"Processor"
],
"summary": "Get a device",
"description": "Endpoint to fetch device.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "deviceId",
"in": "path",
"description": "Unique identifier for the device.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device fetched successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Device"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Device not found."
}
}
}
},
"/processors/{processorId}/terminals/{terminalId}": {
"get": {
"tags": [
"Processor"
],
"summary": "Get a device",
"description": "Endpoint to fetch device.",
"parameters": [
{
"name": "processorId",
"in": "path",
"description": "Unique identifier for the processor.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "terminalId",
"in": "path",
"description": "Unique identifier for the terminal.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device fetched successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Device"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Device not found."
}
}
}
},
"/apps/{appId}/hosts/{hostId}": {
"get": {
"tags": [
"App"
],
"summary": "Get a host",
"description": "Endpoint to fetch a host.",
"parameters": [
{
"name": "appId",
"in": "path",
"description": "Unique identifier for the app.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device fetched successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Host"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/apps/{appId}/terminals/{terminalId}": {
"get": {
"tags": [
"App"
],
"summary": "Get a terminal",
"description": "Endpoint to get a terminal.",
"parameters": [
{
"name": "appId",
"in": "path",
"description": "Unique identifier for the app.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "terminalId",
"in": "path",
"description": "Unique identifier for the terminal.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Get a terminal.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminalAppResponse"
}
}
}
},
"404": {
"description": "Terminal not found."
}
}
}
},
"/apps/{appId}/devices/{deviceId}": {
"get": {
"tags": [
"App"
],
"summary": "Get a device",
"description": "Endpoint to fetch device.",
"parameters": [
{
"name": "appId",
"in": "path",
"description": "Unique identifier for the app.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "deviceId",
"in": "path",
"description": "Unique identifier for the device.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Devices fetched successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Device"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/hosts/{hostId}/devices": {
"get": {
"tags": [
"Host"
],
"summary": "Get a list of devices assigned to host",
"description": "Endpoint to fetch device list.",
"parameters": [
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "created[from]",
"in": "query",
"description": "Filter transactions from this date (inclusive). Format: ISO 8601 (YYYY-MM-DDThh:mm:ss.sss±hh:mm).",
"example": "2024-09-26T14:45:30.123+02:00",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "created[to]",
"in": "query",
"description": "Filter transactions up to this date (inclusive). Format: ISO 8601 (YYYY-MM-DDThh:mm:ss.sss±hh:mm).",
"example": "2024-09-26T14:45:30.123+02:00",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "serialNumber",
"in": "query",
"description": "Filter by the device serial number.",
"required": false,
"schema": {
"type": "string",
"example": "SP000000004"
}
},
{
"name": "configurationTag",
"in": "query",
"description": "Filter by the device configuration tag.",
"required": false,
"schema": {
"type": "string",
"example": "test-v1-all-all"
}
},
{
"name": "page",
"in": "query",
"description": "The page number to retrieve.",
"required": false,
"schema": {
"type": "integer",
"example": 1
}
},
{
"name": "pageSize",
"in": "query",
"description": "The number of items per page.",
"required": false,
"schema": {
"type": "integer",
"example": 50
}
}
],
"responses": {
"200": {
"description": "Devices fetched successfully.",
"headers": {
"X-Total-Count": {
"description": "The total number of devices available.",
"schema": {
"type": "integer",
"example": 1000
}
},
"X-Total-Pages": {
"description": "The total number of pages available.",
"schema": {
"type": "integer",
"example": 20
}
},
"X-Current-Page": {
"description": "The current page number.",
"schema": {
"type": "integer",
"example": 1
}
},
"X-Next-Page": {
"description": "The next page number, if available.",
"schema": {
"type": "integer",
"example": 2
}
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Device"
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"Host"
],
"summary": "Create a device",
"description": "Endpoint to create for a device.",
"parameters": [
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "apk-version",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Application version."
},
{
"name": "idempotency-key",
"in": "header",
"description": "A unique key to ensure idempotent requests. It should be a UUID or unique string to prevent duplicate transactions.",
"required": false,
"schema": {
"type": "string",
"example": "f5033990-1965-4bd6-86d5-cdc274164553"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDeviceRequest"
}
}
}
},
"responses": {
"201": {
"description": "Device created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Device"
}
}
}
},
"422": {
"description": "Unprocessable Entity, validation errors.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
}
}
}
},
"/hosts/{hostId}/devices/{deviceId}": {
"get": {
"tags": [
"Host"
],
"summary": "Get a device",
"description": "Endpoint to fetch device.",
"parameters": [
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "deviceId",
"in": "path",
"description": "Unique identifier for the device.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device fetched successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Device"
}
}
}
},
"404": {
"description": "Device not found."
}
}
},
"put": {
"tags": [
"Host"
],
"summary": "Update a device",
"description": "Endpoint to update device.",
"parameters": [
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "deviceId",
"in": "path",
"description": "Unique identifier for the device.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "idempotency-key",
"in": "header",
"description": "A unique key to ensure idempotent requests. It should be a UUID or unique string to prevent duplicate transactions.",
"required": false,
"schema": {
"type": "string",
"example": "f5033990-1965-4bd6-86d5-cdc274164553"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceRequest"
}
}
}
},
"responses": {
"200": {
"description": "Device updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Device"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Device not found."
},
"422": {
"description": "Unprocessable Entity, validation errors.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": [
"Host"
],
"summary": "Delete a device",
"description": "Endpoint to delete device.",
"parameters": [
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "deviceId",
"in": "path",
"description": "Unique identifier for the device.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "idempotency-key",
"in": "header",
"description": "A unique key to ensure idempotent requests. It should be a UUID or unique string to prevent duplicate transactions.",
"required": false,
"schema": {
"type": "string",
"example": "f5033990-1965-4bd6-86d5-cdc274164553"
}
}
],
"responses": {
"204": {
"description": "Device deleted."
},
"404": {
"description": "Device not found."
}
}
}
},
"/hosts/{hostId}/terminals": {
"get": {
"tags": [
"Host"
],
"summary": "Get terminals",
"description": "Endpoint to get terminals with page-based pagination.",
"parameters": [
{
"name": "hostId",
"in": "path",
"description": "Unique identifier for the host.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "created[from]",
"in": "query",
"description": "Filter transactions fro
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tribe-payments/refs/heads/main/openapi/tribe-payments-trb-isac-pos-tdd-device-api-openapi-device-directory-api-v3.json