# 

## Transaction

Returned by `POST /v1/transactions`, `GET /v1/transactions/{id}`, and list endpoints.

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique transaction identifier (for example, `TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC`) |
| `object` | string | Always `transaction` |
| `type` | string | Transaction type — see [Enumerated values](/docs/reference/enums#transaction-type) |
| `amount` | integer | Amount in minor units (cents). Minimum `50`, maximum `99999999` |
| `tip` | integer | Tip in minor units. Minimum `0`, maximum `10000` |
| `amount_requested` | integer | Original amount requested (read-only) |
| `amount_authorized` | integer | Amount authorized by the issuer (read-only) |
| `transaction_state` | string | Current state — see [Enumerated values](/docs/reference/enums#transaction-state) |
| `response_status` | string | `approved`, `declined`, or `error` |
| `response_code` | string | `00` (approved), `05` (declined), `06` (error) |
| `response_message` | string | Human-readable description of the response code |
| `batch_id` | string | Batch identifier (assigned at capture/settlement) |
| `transaction_date` | date-time | Timestamp when the transaction was created |
| `authorization_code` | string | Authorization code from the issuer |
| `mid` | string | Merchant ID at the processor |
| `terminal_transaction_id` | string | POS terminal transaction identifier |
| `processor_transaction_id` | string | Processor-assigned transaction identifier |
| `processor_response` | object | Raw processor response (varies by processor) |
| `avs_result_code` | string | Address verification result — see [Enumerated values](/docs/reference/enums#avs-result-codes) |
| `cvv_result` | string | Card verification result |
| `payment_method` | object | Payment method details (masked in responses) |
| `billing_descriptors` | object | Statement descriptor shown to the cardholder |
| `recurring` | boolean | Whether this is a recurring transaction |
| `purchase_description` | string | Transaction description (max 30 characters) |
| `metadata` | object | Up to 50 custom key-value pairs |
| `created_at` | date-time | ISO 8601 creation timestamp |
| `correlation_id` | string | Request correlation ID for tracing |


## Client

Returned by `POST /v1/clients`, `GET /v1/clients/{id}`, and list endpoints.

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique client identifier (for example, `CLIENT-3MtwBwLkdIwHu7ix28a3tqPa`) |
| `object` | string | Always `client` |
| `dba` | string | Doing-business-as name (1–100 characters) |
| `parent_id` | string | Parent account identifier |
| `type` | string | `merchant` or `reseller` |
| `admin_contact_details` | object | Primary admin contact (see below) |
| `api_key` | string | API key (returned only on creation) |
| `encryption_keys` | object | Encryption keys (returned only on creation) |
| `correlation_id` | string | Request correlation ID |


### admin_contact_details

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `first_name` | string | Yes | Admin first name (1–100 chars) |
| `last_name` | string | Yes | Admin last name (1–100 chars) |
| `email` | string | Yes | Admin email address |
| `phone` | string | Yes | Admin phone number |
| `time_zone` | string | Yes | IANA time zone — see [Enumerated values](/docs/reference/enums#time-zones) |


## User

Returned by `POST /v1/users`, `GET /v1/users/{id}`, and list endpoints.

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique user identifier (for example, `USER-3MtwBwLkdIwHu7ix28a3tqPa`) |
| `object` | string | Always `user` |
| `first_name` | string | First name |
| `last_name` | string | Last name |
| `email` | string | Email address (also the login username) |
| `phone` | string | Phone number |
| `time_zone` | string | IANA time zone |
| `is_mfa_active` | boolean | Whether MFA is enabled |
| `is_active` | boolean | Whether the user can log in |
| `is_locked` | boolean | Whether the account is locked |
| `correlation_id` | string | Request correlation ID |


## Integration

Returned by `POST /v1/integrations`, `GET /v1/integrations/{id}`, and list endpoints. The shape varies by processor type.

### TSYS integration

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique integration identifier (for example, `proc_3MtwBwLkdIwHu7ix28a3tqPa`) |
| `object` | string | Always `processor_account` |
| `general_details.is_active` | boolean | Whether the integration is active |
| `general_details.mid` | string | TSYS merchant ID |
| `general_details.card_brand` | string | Primary card brand — see [Enumerated values](/docs/reference/enums#card-brands) |
| `general_details.industry_type` | string | Industry type (`p`, `e`, `m`) |
| `general_details.bin` | string | BIN number |
| `general_details.url` | string | TSYS host URL |
| `general_details.settlement_time` | date-time | Daily settlement time |
| `agent_details` | object | Agent/ISO details |
| `metadata` | object | Custom key-value pairs |
| `correlation_id` | string | Request correlation ID |


### Vericheck integration

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique integration identifier (for example, `INTEGRATION-01KFDKXMQ637EKEAY410MSQSXB`) |
| `object` | string | Always `vericheck` |
| `business_name` | string | Legal business name |
| `doing_business_as` | string | DBA / trade name |
| `website_url` | string | Business website URL |
| `addresses` | object | Business address |
| `correlation_id` | string | Request correlation ID |


## Payment Token

Returned by `POST /v1/payment_tokens`, `GET /v1/payment_tokens/{token}`, and list endpoints.

| Field | Type | Description |
|  --- | --- | --- |
| `payment_token` | string | Unique token identifier (for example, `PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB`) |
| `object` | string | Always `payment_token` |
| `type` | string | `card` or `bank_account` |
| `status` | string | `active`, `expired`, `inactive`, `verification_pending`, `verification_failed` |
| `customer_id` | string | Associated customer identifier |
| `is_default` | boolean | Whether this is the customer's default payment method |
| `nickname` | string | Friendly label |
| `card` | object | Masked card details (present when `type: card`) |
| `bank_account` | object | Masked bank details (present when `type: bank_account`) |
| `correlation_id` | string | Request correlation ID |


## Batch

Returned by `GET /v1/batches`.

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique batch identifier |
| `batch_id` | string | Batch identifier |
| `batch_number` | string | Sequential batch number |
| `batch_type` | string | Batch type (for example, `card`) |
| `processor` | string | Processor name |
| `status` | string | Batch status (for example, `open`, `closed`, `settled`) |
| `client_id` | string | Owning client identifier |
| `client_name` | string | Client DBA name |
| `approved_amount` | integer | Total approved amount (minor units) |
| `captured_amount` | integer | Total captured amount |
| `refund_amount` | integer | Total refunds |
| `void_amount` | integer | Total voids |
| `net_amount` | integer | Net amount |
| `batch_net_amount` | integer | Batch net settlement amount |
| `created_at` | date-time | Batch creation timestamp |
| `closed_at_date_time` | date-time | When the batch was closed |
| `settled_at_date_time` | date-time | When funds were settled |
| `correlation_id` | string | Request correlation ID |


## Error response

Returned when a request fails.

| Field | Type | Description |
|  --- | --- | --- |
| `response_status` | string | `declined` or `error` |
| `response_code` | string | `05` (declined) or `06` (error) |
| `response_message` | string | Human-readable error description |
| `correlation_id` | string | Use this value when contacting support |


## Metadata

Metadata is an optional `object` field available on transactions and integrations.

| Constraint | Value |
|  --- | --- |
| Maximum keys | 50 |
| Key format | Letters, digits, hyphens, underscores (max 40 chars) |
| Value format | String (max 500 chars) |
| Clear all | Send `null` |


```json
{
  "metadata": {
    "order_id": "ORD-20260226-001",
    "customer_tier": "gold"
  }
}
```