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.

Boarding creates the location and terminals for you. When a merchant application is boarded through Onboarding, Bead creates the merchant, its location, and its terminals as part of boarding. Do not create your own terminal for a merchant that is still in onboarding, or before the application reaches boarded. Use this endpoint to add further terminals, for example one per acceptance environment, to a merchant that has already been boarded. Use Get Status to confirm the application status and to retrieve onboardedMerchantId.

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. One of virtual or physical — see below. Set at creation and cannot be changed afterward.
useSandboxSharedWallet	boolean	Yes	Must be true in Sandbox for USDC and crypto tenders to function. Set at creation time only — cannot be changed via the edit endpoint.
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.

type values

Value	Description
virtual	An online or remote acceptance environment — hosted checkout, eCommerce, invoicing, or any flow where the customer is not physically present at a counter.
physical	An in-person acceptance environment, such as a point-of-sale or service counter, where a customer is physically present and typically waiting on the transaction.

type is not cosmetic. It is the primary signal Bead uses for the standing tender-type recommendation applied to the terminal: virtual terminals default to all approved tenders enabled, while physical terminals default to BTC (on-chain) disabled, because on-chain confirmation is long-running and unsuitable for a customer waiting at a counter. See Terminal Lifecycle (Concepts) for the full explanation, and Choosing Tender Types by Payment Environment for how to select tenders per environment.

type is set once at creation and cannot be changed later — Update Terminal does not accept it. If a terminal needs a different type, create a new terminal rather than attempting to convert an existing one.

A merchant accepting payments in more than one environment needs a separate terminal per environment. A merchant with both a physical point-of-sale and an online checkout needs at minimum one physical terminal and one virtual terminal — a single terminal cannot represent both. It is common for one merchant to have several terminals across locations and channels; see Managing Tender Types for how the approved tender set flows down to each one.

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

The create response is where Bead returns the terminal payments API key for a terminal you create. Store these values securely right away:

• id — the terminal ID

• apiKey.secret — the terminal payments API key

Send the terminal payments API key in the X-Api-Key header on payment requests for that terminal. Terminal payments authenticate with the API key header only.

Getting the terminal payments API key again

Bead does not return the usable key again after the terminal is created. Get Terminal and List Terminals return only the masked value.

If you did not capture the key when you created the terminal, or you need the key for a terminal Bead created at boarding, issue a new key with POST /Terminals/{id}/api-keys. The reset response is the only place the new key is returned, and resetting replaces the previous key immediately. Read Reset Terminal API Key before you call it.

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

• Reset Terminal API Key

• Terminal Lifecycle (Concepts)

• Managing Tender Types

• Choosing Tender Types by Payment Environment