# 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**

```json
{
  "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.

```json
{
  "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`.                                              |