Create Terminal

Creates a new terminal under an existing location. This endpoint is used for terminal setup and returns the terminal record along with the terminal payments API key that should be stored securely for future payment requests.

Endpoint

POST /Terminals

Authentication

Use your admin API key in the request header for terminal management operations.

In the example below, X-Api-Key is used as the header name. Replace that with your standard admin API key header name if your docs use a different label.

Request headers

Header	Value
X-Api-Key	{adminApiKey}
Content-Type	application/json
Accept	application/json

Request body

Field	Type	Required	Description
name	string	Yes	Friendly name for the terminal.
locationId	string	Yes	ID of the location that owns the terminal.
type	enum	Yes	Terminal type.
useSandboxSharedWallet	boolean	Yes	Required Sandbox wallet behavior setting.
tenderTypes	array	No	Tender types enabled for this terminal.
description	string	No	Optional terminal description.
displayLogo	boolean	No	Controls whether the logo is displayed where supported.
extendRedirectUrl	boolean	No	Adds paymentPageId as a query parameter to the redirect URL.
maxTransactionAmount	number	No	Optional maximum transaction amount for this terminal.

Example request

curl --request POST "https://api.test.devs.beadpay.io/Terminals" \
  --header "X-Api-Key: {adminApiKey}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "name": "Front Counter 1",
    "locationId": "67f00123456789abcdef0123",
    "type": "virtual",
    "tenderTypes": ["ethereum", "usdcBase"],
    "description": "Primary checkout terminal",
    "displayLogo": true,
    "extendRedirectUrl": false,
    "maxTransactionAmount": 5000,
    "useSandboxSharedWallet": true
  }'

Example response

{
  "id": "67f10123456789abcdef0456",
  "name": "Front Counter 1",
  "description": "Primary checkout terminal",
  "merchantId": "67e90123456789abcdef0001",
  "merchantStatus": "active",
  "type": "virtual",
  "merchantLocationId": "67f00123456789abcdef0123",
  "merchantLocation": {
    "id": "67f00123456789abcdef0123",
    "name": "Main Store",
    "address": {
      "address1": "123 Main St",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "isEnabled": true
  },
  "displayLogo": true,
  "webhookUrl": null,
  "isEnabled": true,
  "extendRedirectUrl": false,
  "tenderTypes": ["ethereum", "usdcBase"],
  "created": "2026-04-02T15:00:00Z",
  "updated": "2026-04-02T15:00:00Z",
  "maxTransactionAmount": 5000,
  "apiKey": {
    "secret": "pk_test_terminal_secret_value",
    "maskedSecret": "pk_****_value"
  },
  "useSandboxSharedWallet": true
}

What to store

After creating a terminal, store these values securely:

• id — the terminal ID

• apiKey.secret — the terminal payments API key

Use the terminal payments API key for payment requests associated with that terminal. Do not rely on login/password credentials for new integrations.

Notes

• Use your admin API key for terminal management operations such as create, update, delete, webhook configuration, and key reset.

• Use the returned terminal payments API key for payment activity performed by that terminal.

• Treat apiKey.secret like any other secret. Do not log it or expose it in client-side code.

• apiKey.maskedSecret is for display purposes only and cannot be used to authenticate.

Error responses

Code	Meaning
400	The request body is invalid or missing required fields.
401	The admin API key is missing or invalid.
403	The caller is authenticated but not allowed to create a terminal for the target location.
409	A conflicting terminal state or duplicate condition prevented creation.

Related operations

• List terminals

• Get terminal

• Update terminal

• Delete terminal