Common Field Types

Shared objects and field conventions used across the API. Use these definitions when building requests and interpreting responses.

Address object

Field	Type	Required	Notes
address1	string	Yes	Street line one
address2	string	No	Suite or unit
city	string	Yes	City or locality
region	string	Yes	State or province such as MA
country	string	Yes	ISO alpha two such as US
postalCode	string	Yes	ZIP or postal code

Example

{
  "address1": "123 Main St",
  "address2": "Suite 200",
  "city": "Springfield",
  "region": "MA",
  "country": "US",
  "postalCode": "01109"
}

Contact fields

Field	Type	Required	Notes
contactPhone	string	Yes when documented	Local format or E.164 accepted. Prefer E.164 for production
contactEmail	string	Yes when documented	Valid email address for notifications or support
website	string or null	Conditional	Required when business type is virtual. Must be HTTPS

Identifiers

Treat all identifiers as opaque strings. Preserve case and do not parse by prefix.

Entity	Example format
Partner	par_9f2a1cde
Merchant	mer_4e5a13aa
Location	loc_bfdc6a7f
Terminal	term_12345678
Payment	pay_abcdef12

Monetary amounts and volumes

Numeric values are JSON numbers. Do not quote numeric fields.

Field	Type	Meaning
averageTicketSize	number	Typical transaction amount for the entity
maximumTicketSize	number	Maximum expected transaction amount
highestMonthlyVolume	number or null	Peak expected monthly volume if available
grossAnnualVolume	number	Estimated annual processing volume

Precision is two decimal places unless a field specifies otherwise. Currency is implied by the merchant or settlement rail unless a currency code is explicitly documented on that endpoint.

Merchant category codes

Field	Type	Required	Notes
merchantCategoryCode	string	Yes	Four digit MCC such as 5812
additionalMerchantCategoryCodes	array of string	Yes	Can be an empty array when not applicable

Provide MCC values as strings to preserve leading zeros where used.

Tender types

Use the exact strings shown on the Tender Types pages. Values are case sensitive.

Example values	Notes
usdcBase	USDC on Base network
ethereum	ETH on Ethereum network

When a location or terminal omits tenderTypes, defaults from the parent are applied according to the entity documentation.

Timestamps

Topic	Convention
Format	ISO 8601 in UTC with Z suffix
Examples	2025-09-02T16:22:11Z, 2025-09-02T16:22:11.015Z
Fields	created and updated use UTC consistently

Pagination parameters and envelope

Paginated endpoints accept common parameters and return a standard envelope.

Name	Type	Required	Notes
page	integer	No	One based page number with a default of one
pageSize	integer	No	Items per page with a sensible default per endpoint

Response envelope

Field	Type	Notes
data	array	Results for the requested page
total	integer	Total number of records across all pages
page	integer	Page number that was returned

Some list endpoints return a bare array when the full set is expected to be small. Those endpoints do not use pagination parameters or the envelope.

Error object

All error responses follow a consistent JSON shape. Surface message to users and log traceId for support.

{
  "code": "validation_error",
  "error": "Invalid request",
  "message": "One or more fields are invalid.",
  "traceId": "00-73fffe343fd1d5b150beddb00730bb24-f182c31fd104b782-00",
  "details": [
    { "field": "address.postalCode", "message": "Invalid format" }
  ]
}

Field	Type	Description
code	string	Stable programmatic code such as validation_error, not_found, forbidden
error	string	Short category label used in logs
message	string	Human readable explanation
traceId	string	Correlation identifier for support
details	array	Optional per field errors with field and message

Header conventions

Header	Value
Authorization	Bearer <access_token> on every call
Content Type	application/json for requests with bodies
Accept	application/json

URL and webhook fields

Field	Requirements
url	Used for callback and webhook style fields such as PUT /Terminals/{terminalId}/webhook. Must be a fully qualified https URL that is routable from Bead. Use a stable hostname (no localhost in production) and keep the path stable so you can rotate secrets without changing the URL.
webhookUrls	Array of URL strings used for per payment overrides on POST /payments/crypto. Each entry must meet the same requirements as url. Be prepared to receive the same event at both the terminal level URL and every URL listed in webhookUrls.