# Data Models

This document provides a comprehensive overview of the data structures used throughout the Mesh Connect Android SDK. These models define the structure for all communication between the web-based financial flows and the native Android application, including authentication tokens, account information, transfer results, and error handling.

For detailed information about transfer-specific data structures, see [Transfer Payloads](/content/FrontFin/mesh-android-sdk/4.1-transfer-payloads/index.html). For authentication-related models, see [Authentication Payloads](/content/FrontFin/mesh-android-sdk/4.2-authentication-payloads/index.html). For JSON conversion mechanisms, see [JSON Serialization and Deserialization](/content/FrontFin/mesh-android-sdk/4.3-json-serialization-and-deserialization/index.html).

## Payload Hierarchy

The SDK uses a sealed interface hierarchy to ensure type safety and exhaustive handling of all possible payload types. All payload classes implement Android's `Parcelable` interface for efficient inter-process communication.

```
«sealed interface»
LinkPayload
+Parcelable
«sealed interface»
TransferFinishedPayload
AccessTokenPayload
+List<AccountToken> accountTokens
+String brokerType
+String brokerName
+BrandInfo brokerBrandInfo
+Int? expiresInSeconds
+Int? refreshTokenExpiresInSeconds
DelayedAuthPayload
+Int? refreshTokenExpiresInSeconds
+String brokerType
+String refreshToken
+String brokerName
+BrandInfo brokerBrandInfo
TransferFinishedSuccessPayload
+String txId
+String fromAddress
+String toAddress
+String symbol
+Double amount
+String networkId
+Double? amountInFiat
+Double? totalAmountInFiat
+String? networkName
+String? txHash
+String? transferId
+String? refundAddress
TransferFinishedErrorPayload
+String errorMessage
```

**Sources:** [link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt6-84](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt#L6-L84)

## Account and Token Models

The SDK defines several interconnected models for handling account information and access tokens from financial brokers.

### AccountToken Structure

```
AccountToken
+Account account
+String accessToken
+String? refreshToken
Account
+String accountId
+String accountName
+String frontAccountId
+Double? fund
+Double? cash
+Boolean? isReconnected
BrandInfo
+String? brokerLogo
+String? brokerPrimaryColor
+String? logoLightUrl
+String? logoDarkUrl
+String? iconLightUrl
+String? iconDarkUrl
AccessTokenPayload
+List<AccountToken> accountTokens
+BrandInfo brokerBrandInfo
```

The `AccountToken` class [link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt24-28](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt#L24-L28) encapsulates both account metadata and authentication credentials. Each token contains:

- **account**: Complete account information including balances and identifiers
- **accessToken**: Bearer token for API authentication
- **refreshToken**: Optional token for refreshing expired access tokens

**Sources:** [link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt24-48](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt#L24-L48)

## Response Wrapper Models

The SDK uses internal response wrapper classes to handle the JSON structure received from the web layer:

| Response Class            | Wrapped Payload         | Purpose                                |
|---------------------------|-------------------------|----------------------------------------|
| `AccessTokenResponse`     | `AccessTokenPayload`    | Account linking completion              |
| `DelayedAuthResponse`     | `DelayedAuthPayload`    | Deferred authentication flows           |
| `TransferFinishedResponse`| `TransferFinishedPayload`| Transfer operation results              |

These wrapper classes [link/src/main/java/com/meshconnect/link/entity/Response.kt3-13](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/Response.kt#L3-L13) provide a consistent JSON deserialization structure where the actual payload data is nested under a `payload` field.

**Sources:** [link/src/main/java/com/meshconnect/link/entity/Response.kt3-13](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/Response.kt#L3-L13)

## Transfer Result Models

Transfer operations can result in either success or error outcomes, both implementing the `TransferFinishedPayload` sealed interface.

### Transfer Success Data

```
Optional Fields
amountInFiat: Double?   // USD equivalent amount

amount: Double           // Transfer amount
```

The success payload [link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt66-79](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt#L66-L79) contains comprehensive transfer details, with several optional fields that may not be present depending on the transfer type and blockchain network.

**Sources:** [link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt66-84](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt#L66-L84)

## JSON Mapping and Serialization

The SDK handles JSON-to-object conversion automatically using custom deserializers. The test files demonstrate the expected JSON structure:

### Transfer Success JSON Structure

```
{
    "status": "success",
    "txId": "234sdf-xxx3902",
    "fromAddress": "0923xxx",
    "toAddress": "92811yyyy",
    "symbol": "UST",
    "amount": 1.0024,
    "networkId": "79823981e",
    "amountInFiat": 10.55,
    "totalAmountInFiat": 11.2,
    "networkName": "Polygon",
    "txHash": "1-9340-194350432-21123232",
    "transferId": "0x093547892-24234-2342",
    "refundAddress": "test-refund-address"
}
```

The SDK supports flexible JSON parsing where optional fields can be omitted [link/src/test/resources/transfer-success-empty-fields.json1-7](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/test/resources/transfer-success-empty-fields.json#L1-L7) and the deserializer will properly handle null values and empty strings.

**Sources:** [link/src/test/kotlin/com/meshconnect/link/converter/TransferFinishedPayloadDeserializerTest.kt14-67](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/test/kotlin/com/meshconnect/link/converter/TransferFinishedPayloadDeserializerTest.kt#L14-L67) [link/src/test/resources/transfer-success.json1-15](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/test/resources/transfer-success.json#L1-L15) [link/src/test/resources/transfer-success-empty-fields.json1-7](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/test/resources/transfer-success-empty-fields.json#L1-L7)

## Data Model Usage Patterns

All payload classes are designed as immutable data classes with the following characteristics:

- **Parcelable Implementation**: All models can be passed between Android components efficiently
- **Null Safety**: Optional fields use Kotlin's nullable types (`?`) for explicit null handling
- **Sealed Interfaces**: Exhaustive when expressions ensure all payload types are handled
- **JSON Compatibility**: Direct mapping between JSON properties and Kotlin properties

The models support Android's configuration changes and process recreation through the `@Parcelize` annotation, ensuring data persistence across the application lifecycle.

**Sources:** [link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt3-4](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkPayload.kt#L3-L4) [link/src/test/kotlin/com/meshconnect/link/entity/TransferFinishedSuccessPayloadTest.kt8-36](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/test/kotlin/com/meshconnect/link/entity/TransferFinishedSuccessPayloadTest.kt#L8-L36)