# Credentials

The `MerchantData` object holds the credentials used to initialize the SDK. Pass it to the `MPOSFinix` constructor.

```kotlin
class MerchantData(
    val merchantId: String,
    val mid: String,
    val deviceId: String,
    val currency: Currency = Currency.USD,
    val env: Environment = Environment.SB,
    val userId: String,
    val password: String
)
```

| Field | Type | Description |
|  --- | --- | --- |
| `merchantId` | `String` | Your Finix Merchant ID (`MU...`). |
| `mid` | `String` | Merchant identifier number. Pass an empty string if not required. |
| `deviceId` | `String` | The Finix Device ID (`DV...`) created during [device setup](/android/card-present/device-setup). |
| `currency` | `Currency` | Transaction currency. Defaults to `Currency.USD`. |
| `env` | `Environment` | `Environment.SB` for sandbox, `Environment.PROD` for production. |
| `userId` | `String` | Your Finix user ID (`US...`). |
| `password` | `String` | Your Finix API password. |


## Creating API Credentials

Use `ROLE_MERCHANT` credentials to scope a device to a single merchant. Use `ROLE_PARTNER` credentials if the device will process payments across multiple merchants. Note that split transactions require `ROLE_PARTNER` credentials.

Once created, you can use `ROLE_MERCHANT` credentials across multiple devices as long as the devices are associated to the same Merchant.

```shell cURL
curl -i -X POST \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "additional_underwriting_data": {
      "annual_ach_volume": 200000,
      "average_ach_transfer_amount": 200000,
      "average_card_transfer_amount": 200000,
      "business_description": "SB3 vegan cafe",
      "card_volume_distribution": {
        "card_present_percentage": 30,
        "ecommerce_percentage": 60,
        "mail_order_telephone_order_percentage": 10
      },
      "credit_check_allowed": true,
      "credit_check_ip_address": "42.1.1.112",
      "credit_check_timestamp": "2021-04-28T16:42:55Z",
      "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10_14_6)",
      "merchant_agreement_accepted": true,
      "merchant_agreement_ip_address": "42.1.1.113",
      "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
      "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
      "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
      "volume_distribution_by_business_type": {
        "business_to_business_volume_percentage": 100,
        "business_to_consumer_volume_percentage": 0,
        "consumer_to_consumer_volume_percentage": 0,
        "other_volume_percentage": 0,
        "person_to_person_volume_percentage": 0
      }
    },
    "entity": {
      "ach_max_transaction_amount": 1000000,
      "annual_card_volume": 12000000,
      "business_address": {
        "city": "San Mateo",
        "country": "USA",
        "line1": "741 Douglass St",
        "line2": "Apartment 8",
        "postal_code": "94114",
        "region": "CA"
      },
      "business_name": "Finix Flowers",
      "business_phone": "+1 (408) 756-4497",
      "business_tax_id": "123456789",
      "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
      "default_statement_descriptor": "Finix Flowers",
      "dob": {
        "day": 27,
        "month": 6,
        "year": 1978
      },
      "doing_business_as": "Finix Flowers",
      "email": "user@example.org",
      "first_name": "John",
      "has_accepted_credit_cards_previously": true,
      "incorporation_date": {
        "day": 27,
        "month": 6,
        "year": 1978
      },
      "last_name": "Smith",
      "max_transaction_amount": 1000000,
      "mcc": "4900",
      "ownership_type": "PRIVATE",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "line1": "741 Douglass St",
        "line2": "Apartment 7",
        "postal_code": "94114",
        "region": "CA"
      },
      "phone": "14158885080",
      "principal_percentage_ownership": 50,
      "tax_id": "123456789",
      "title": "CEO",
      "url": "https://www.finix.com"
    },
    "identity_roles": [
      "SELLER"
    ],
    "tags": {
      "Studio Rating": "4.7"
    },
    "type": "BUSINESS"
  }'
```

Example
User - ROLE_MERCHANT
```json User - ROLE_MERCHANT
{
  "id": "USoR21bF52KLZpbQCptrexpH",
  "created_at": "2025-12-08T18:35:51.41Z",
  "updated_at": "2025-12-08T18:35:51.41Z",
  "created_by": "USfdccsr1Z5iVbXDyYt7hjZZ",
  "email": null,
  "enabled": true,
  "first_name": null,
  "identity": "IDjvxGeXBLKH1V9YnWm1CS4n",
  "last_name": null,
  "last_used_date": null,
  "password": "f2fd7118-66c3-495c-8942-8178e0ea9d0c",
  "role": "ROLE_MERCHANT", // [!code highlight]
  "tags": {},
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/users/USoR21bF52KLZpbQCptrexpH"
    },
    "applications": {
      "href": "https://finix.sandbox-payments-api.com/applications"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/user",
  "components": {
    "schemas": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "The ID of the resource."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "user": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "created_by": {
            "type": "string",
            "description": "The ID of the application user that created _this_ user."
          },
          "email": {
            "type": "string",
            "minLength": 1,
            "nullable": true,
            "description": "The email address of the application user (max 100 characters)."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the `User` is enabled and active. Set to `false` to disable the `User`."
          },
          "first_name": {
            "type": "string",
            "description": "The first name of the User ID (Max 50 characters).",
            "nullable": true,
            "maxLength": 50
          },
          "identity": {
            "type": "string",
            "example": "IDxxxxxxxxxxxxxxxxxx",
            "description": "ID of the `Identity` that the `User` object was created under.",
            "nullable": true
          },
          "last_name": {
            "type": "string",
            "description": "The last name of the User ID (Max 50 characters).",
            "nullable": true,
            "maxLength": 50
          },
          "last_used_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Date when the user credentials were last used to make an API call."
          },
          "password": {
            "type": "string",
            "description": "The `password` you'll use to authetnicate requests.",
            "nullable": true
          },
          "role": {
            "enum": [
              "ROLE_PLATFORM",
              "ROLE_PARTNER",
              "ROLE_MERCHANT"
            ],
            "type": "string",
            "description": "Details the level of access the [`User`](#Users) has available."
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "_links": {
            "type": "object",
            "description": "For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.",
            "properties": {
              "application": {
                "type": "object",
                "description": "Link to the `Application` the resource was created under.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "applications": {
                "type": "object",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              },
              "self": {
                "type": "object",
                "description": "Link to the resource that was used in the request.",
                "properties": {
                  "href": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

1. Log in to the Finix dashboard.
2. Select the environment for which you would like to create API credentials (Sandbox or Live).
3. In the bottom left corner, select the **Developer** section.
4. In the API Keys section, select **Create API Key**.


## Sandbox and Production

Set `env` to match the environment your device is designated for. Devices cannot switch environments after designation.