gobtc payDocs

POS Terminals

Manage POS terminals within a store, including issuing and rotating their API keys.

Create POS terminal

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/store/pos/create

Creates a POS terminal under the given storeId, with optional label and location. Returns the posTerminal, including the freshly issued apiKey.

Authorization: merchantAuth

Body required

application/json
storeIdstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
labelstring

Human-readable label for the POS terminal (optional).

Example:Front desk
locationstring

Physical location of the POS terminal (optional).

Example:Lisbon, PT

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/store/pos/create
cURL
curl -X POST "$BASE_URL/merchant/store/pos/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "Front desk",
  "location": "Lisbon, PT"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "posTerminal": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "label": "Front desk",
        "location": "Lisbon, PT",
        "status": "active",
        "apiKey": "possk_live_3fa85f6457174562b3fc2c963f66afa6"
      }
    }
  }
}

Get POS terminal

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/store/pos/get

Fetches a single POS terminal by posTerminalId. Returns the posTerminal with its storeId, label, location, status, and its apiKey.

Authorization: merchantAuth

Body required

application/json
posTerminalIdstringrequired

Identifier of the POS terminal (UUID).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/store/pos/get
cURL
curl -X POST "$BASE_URL/merchant/store/pos/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "posTerminal": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "label": "Front desk",
        "location": "Lisbon, PT",
        "status": "active",
        "apiKey": "possk_live_3fa85f6457174562b3fc2c963f66afa6"
      }
    }
  }
}

List POS terminals

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/store/pos/list

Lists POS terminals with optional pagination and filters by storeId and status. Returns items and totalCount.

Authorization: merchantAuth

Body required

application/json
paginationobject
filtersobject

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/store/pos/list
cURL
curl -X POST "$BASE_URL/merchant/store/pos/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  },
  "filters": {
    "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active"
  }
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "label": "Front desk",
          "location": "Lisbon, PT",
          "status": "active",
          "apiKey": "possk_live_3fa85f6457174562b3fc2c963f66afa6"
        }
      ],
      "totalCount": 0
    }
  }
}

Update POS terminal

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/store/pos/update

Updates the label, location, and/or status of the POS terminal identified by posTerminalId. Returns the updated posTerminal; the apiKey is not re-issued.

Authorization: merchantAuth

Body required

application/json
posTerminalIdstringrequired

Identifier of the POS terminal (UUID).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
labelstring

Human-readable label for the POS terminal (optional).

Example:Front desk
locationstring

Physical location of the POS terminal (optional).

Example:Lisbon, PT
statusenum

Current status. Payments: initiated / detected / paid / failed / expired / canceled / cleared. Payment transactions: success / failed / pending / cleared.

activedisabled
Example:active

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/store/pos/update
cURL
curl -X POST "$BASE_URL/merchant/store/pos/update" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "Front desk",
  "location": "Lisbon, PT",
  "status": "active"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "posTerminal": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "label": "Front desk",
        "location": "Lisbon, PT",
        "status": "active",
        "apiKey": "possk_live_3fa85f6457174562b3fc2c963f66afa6"
      }
    }
  }
}

Delete POS terminal

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/store/pos/delete

Deletes the POS terminal identified by posTerminalId. Returns { ok }.

Authorization: merchantAuth

Body required

application/json
posTerminalIdstringrequired

Identifier of the POS terminal (UUID).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/store/pos/delete
cURL
curl -X POST "$BASE_URL/merchant/store/pos/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Rotate POS API key

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/store/pos/rotate-api-key

Rotates the API key for the POS terminal identified by posTerminalId, invalidating the previous key and returning a fresh apiKey.

Authorization: merchantAuth

Body required

application/json
posTerminalIdstringrequired

Identifier of the POS terminal (UUID).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/store/pos/rotate-api-key
cURL
curl -X POST "$BASE_URL/merchant/store/pos/rotate-api-key" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "apiKey": "possk_live_3fa85f6457174562b3fc2c963f66afa6"
    }
  }
}