Stores

Manage the merchant's stores: create, read, update, and delete.

Create store

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

Creates a new store for the authenticated merchant. Accepts a required name and optional address, country, and timezone. Returns the created store, including its id, merchantId, status, and posCount.

Authorization: merchantAuth

Body required

application/json

namestringrequired

Example:Satoshi Coffee

addressstring

Example:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

countrystring

Example:string

latnumber

Example:1718012345

lngnumber

Example:0

timezonestring

Example:string

Responses

idstringrequired

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

resultobjectrequired

POST /merchant/store/create

cURL

curl -X POST "$BASE_URL/merchant/store/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "name": "Satoshi Coffee",
  "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
  "country": "string",
  "lat": 1718012345,
  "lng": 0,
  "timezone": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "store": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Satoshi Coffee",
        "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "country": "string",
        "lat": 1718012345,
        "lng": 0,
        "timezone": "string",
        "status": "active",
        "posCount": 0,
        "createdAt": 1718012345,
        "updatedAt": 1718012345
      }
    }
  }
}

Get store

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

Fetches a single store by storeId. Returns the store object with name, address, country, timezone, status, posCount, and timestamps.

Authorization: merchantAuth

Body required

application/json

storeIdstringrequired

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

Responses

idstringrequired

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

resultobjectrequired

POST /merchant/store/get

cURL

curl -X POST "$BASE_URL/merchant/store/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "store": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Satoshi Coffee",
        "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "country": "string",
        "lat": 1718012345,
        "lng": 0,
        "timezone": "string",
        "status": "active",
        "posCount": 0,
        "createdAt": 1718012345,
        "updatedAt": 1718012345
      }
    }
  }
}

List stores

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

Lists the merchant's stores with optional pagination (limit, skip) and filters (status, free-text query). Returns items (array of stores) and totalCount.

Authorization: merchantAuth

Body required

application/json

paginationobject

filtersobject

Responses

idstringrequired

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

resultobjectrequired

POST /merchant/store/list

cURL

curl -X POST "$BASE_URL/merchant/store/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  },
  "filters": {
    "status": "active",
    "query": "string"
  }
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Satoshi Coffee",
          "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
          "country": "string",
          "lat": 1718012345,
          "lng": 0,
          "timezone": "string",
          "status": "active",
          "posCount": 0,
          "createdAt": 1718012345,
          "updatedAt": 1718012345
        }
      ],
      "totalCount": 0
    }
  }
}

Update store

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

Updates the store identified by storeId. Optionally changes name, address, country, timezone, and status (active or disabled; deleted is reserved for the delete endpoint). Returns the updated store.

Authorization: merchantAuth

Body required

application/json

storeIdstringrequired

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

namestring

Example:Satoshi Coffee

addressstring

Example:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

countrystring

Example:string

latnumber

Example:1718012345

lngnumber

Example:0

timezonestring

Example:string

statusenum

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

activedisableddeleted

Example:active

Responses

idstringrequired

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

resultobjectrequired

POST /merchant/store/update

cURL

curl -X POST "$BASE_URL/merchant/store/update" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Satoshi Coffee",
  "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
  "country": "string",
  "lat": 1718012345,
  "lng": 0,
  "timezone": "string",
  "status": "active"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "store": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Satoshi Coffee",
        "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "country": "string",
        "lat": 1718012345,
        "lng": 0,
        "timezone": "string",
        "status": "active",
        "posCount": 0,
        "createdAt": 1718012345,
        "updatedAt": 1718012345
      }
    }
  }
}

Delete store

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

Soft-deletes the store identified by storeId, setting its status to deleted. Returns { ok }.

Authorization: merchantAuth

Body required

application/json

storeIdstringrequired

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

Responses

idstringrequired

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

resultobjectrequired

POST /merchant/store/delete

cURL

curl -X POST "$BASE_URL/merchant/store/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}