> For the complete documentation index, see [llms.txt](https://docs.gobtcpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gobtcpay.com/api-reference/merchant-api/pos-terminals.md). # POS Terminals Manage POS terminals within a store, including issuing and rotating their API keys. ## Create POS terminal > Creates a POS terminal under the given \`storeId\`, with optional \`label\` and \`location\`. Returns the \`posTerminal\`, including the freshly issued \`apiKey\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"POS Terminals","description":"Manage POS terminals within a store, including issuing and rotating their API keys."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/store/pos/create":{"post":{"summary":"Create POS terminal","description":"Creates a POS terminal under the given `storeId`, with optional `label` and `location`. Returns the `posTerminal`, including the freshly issued `apiKey`.","tags":["POS Terminals"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"storeId":{"type":"string"},"label":{"type":"string","description":"Human-readable label for the POS terminal (optional)."},"location":{"type":"string","description":"Physical location of the POS terminal (optional)."}},"required":["storeId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"posTerminal":{"type":"object","properties":{"id":{"type":"string"},"storeId":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"label":{"type":["string","null"],"description":"Human-readable label for the POS terminal (optional)."},"location":{"type":["string","null"],"description":"Physical location of the POS terminal (optional)."},"status":{"type":"string","enum":["active","disabled"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"apiKey":{"type":"string","description":"Secret API key of the POS terminal. Store it securely — it authenticates the terminal."}},"required":["id","storeId","merchantId","label","location","status"],"additionalProperties":false}},"required":["posTerminal"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Get POS terminal > Fetches a single POS terminal by \`posTerminalId\`. Returns the \`posTerminal\` with its \`storeId\`, \`label\`, \`location\`, \`status\`, and its \`apiKey\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"POS Terminals","description":"Manage POS terminals within a store, including issuing and rotating their API keys."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/store/pos/get":{"post":{"summary":"Get POS terminal","description":"Fetches a single POS terminal by `posTerminalId`. Returns the `posTerminal` with its `storeId`, `label`, `location`, `status`, and its `apiKey`.","tags":["POS Terminals"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."}},"required":["posTerminalId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"posTerminal":{"type":"object","properties":{"id":{"type":"string"},"storeId":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"label":{"type":["string","null"],"description":"Human-readable label for the POS terminal (optional)."},"location":{"type":["string","null"],"description":"Physical location of the POS terminal (optional)."},"status":{"type":"string","enum":["active","disabled"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"apiKey":{"type":"string","description":"Secret API key of the POS terminal. Store it securely — it authenticates the terminal."}},"required":["id","storeId","merchantId","label","location","status","apiKey"],"additionalProperties":false}},"required":["posTerminal"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## List POS terminals > Lists POS terminals with optional \`pagination\` and \`filters\` by \`storeId\` and \`status\`. Returns \`items\` and \`totalCount\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"POS Terminals","description":"Manage POS terminals within a store, including issuing and rotating their API keys."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/store/pos/list":{"post":{"summary":"List POS terminals","description":"Lists POS terminals with optional `pagination` and `filters` by `storeId` and `status`. Returns `items` and `totalCount`.","tags":["POS Terminals"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":100,"default":20},"skip":{"type":"number","minimum":0,"default":0}},"additionalProperties":false},"filters":{"type":"object","properties":{"storeId":{"type":"string"},"status":{"type":"string","enum":["active","disabled"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"additionalProperties":false}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"storeId":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"label":{"type":["string","null"],"description":"Human-readable label for the POS terminal (optional)."},"location":{"type":["string","null"],"description":"Physical location of the POS terminal (optional)."},"status":{"type":"string","enum":["active","disabled"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"apiKey":{"type":"string","description":"Secret API key of the POS terminal. Store it securely — it authenticates the terminal."}},"required":["id","storeId","merchantId","label","location","status"],"additionalProperties":false}},"totalCount":{"type":"number","description":"Total number of records matching the filters."}},"required":["items","totalCount"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Update POS terminal > Updates the \`label\`, \`location\`, and/or \`status\` of the POS terminal identified by \`posTerminalId\`. Returns the updated \`posTerminal\`; the \`apiKey\` is not re-issued. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"POS Terminals","description":"Manage POS terminals within a store, including issuing and rotating their API keys."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/store/pos/update":{"post":{"summary":"Update POS terminal","description":"Updates the `label`, `location`, and/or `status` of the POS terminal identified by `posTerminalId`. Returns the updated `posTerminal`; the `apiKey` is not re-issued.","tags":["POS Terminals"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."},"label":{"type":"string","description":"Human-readable label for the POS terminal (optional)."},"location":{"type":"string","description":"Physical location of the POS terminal (optional)."},"status":{"type":"string","enum":["active","disabled"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["posTerminalId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"posTerminal":{"type":"object","properties":{"id":{"type":"string"},"storeId":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"label":{"type":["string","null"],"description":"Human-readable label for the POS terminal (optional)."},"location":{"type":["string","null"],"description":"Physical location of the POS terminal (optional)."},"status":{"type":"string","enum":["active","disabled"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"apiKey":{"type":"string","description":"Secret API key of the POS terminal. Store it securely — it authenticates the terminal."}},"required":["id","storeId","merchantId","label","location","status"],"additionalProperties":false}},"required":["posTerminal"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Delete POS terminal > Deletes the POS terminal identified by \`posTerminalId\`. Returns \`{ ok }\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"POS Terminals","description":"Manage POS terminals within a store, including issuing and rotating their API keys."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/store/pos/delete":{"post":{"summary":"Delete POS terminal","description":"Deletes the POS terminal identified by `posTerminalId`. Returns `{ ok }`.","tags":["POS Terminals"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."}},"required":["posTerminalId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Rotate POS API key > Rotates the API key for the POS terminal identified by \`posTerminalId\`, invalidating the previous key and returning a fresh \`apiKey\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"POS Terminals","description":"Manage POS terminals within a store, including issuing and rotating their API keys."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/store/pos/rotate-api-key":{"post":{"summary":"Rotate POS API key","description":"Rotates the API key for the POS terminal identified by `posTerminalId`, invalidating the previous key and returning a fresh `apiKey`.","tags":["POS Terminals"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."}},"required":["posTerminalId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"apiKey":{"type":"string","description":"Secret API key of the POS terminal. Store it securely — it authenticates the terminal."}},"required":["apiKey"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.gobtcpay.com/api-reference/merchant-api/pos-terminals.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.