Skip to content

Credentials

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

MerchantData shape

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
)
FieldTypeDescription
merchantIdStringYour Finix Merchant ID (MU...).
midStringMerchant identifier number. Pass an empty string if not required.
deviceIdStringThe Finix Device ID (DV...) created during device setup.
currencyCurrencyTransaction currency. Defaults to Currency.USD.
envEnvironmentEnvironment.SB for sandbox, Environment.PROD for production.
userIdStringYour Finix user ID (US...).
passwordStringYour 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.

Create ROLE_MERCHANT credentials

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

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  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": 0,
      "average_ach_transfer_amount": 0,
      "average_card_transfer_amount": 0,
      "business_description": "string",
      "card_volume_distribution": {
        "card_present_percentage": 0,
        "ecommerce_percentage": 0,
        "mail_order_telephone_order_percentage": 0
      },
      "credit_check_allowed": true,
      "credit_check_ip_address": "string",
      "credit_check_timestamp": "string",
      "credit_check_user_agent": "string",
      "merchant_agreement_accepted": true,
      "merchant_agreement_ip_address": "string",
      "merchant_agreement_timestamp": "string",
      "merchant_agreement_user_agent": "string",
      "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
      "volume_distribution_by_business_type": {
        "business_to_business_volume_percentage": 0,
        "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": 0,
      "amex_mid": 0,
      "annual_card_volume": 0,
      "business_address": {
        "city": "string",
        "country": "string",
        "line1": "string",
        "line2": "string",
        "postal_code": "string",
        "region": "string"
      },
      "business_name": "string",
      "business_phone": "string",
      "business_tax_id": "string",
      "business_type": "ASSOCIATION_ESTATE_TRUST",
      "default_statement_descriptor": "string",
      "discover_mid": 0,
      "dob": {
        "day": 1,
        "month": 1,
        "year": 1900
      },
      "doing_business_as": "string",
      "email": "string",
      "first_name": "string",
      "has_accepted_credit_cards_previously": true,
      "incorporation_date": {
        "day": 0,
        "month": 0,
        "year": 0
      },
      "last_name": "string",
      "max_transaction_amount": 0,
      "mcc": "string",
      "ownership_type": "PRIVATE",
      "personal_address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "ABW"
      },
      "phone": "string",
      "principal_percentage_ownership": 0,
      "short_business_name": "string",
      "tax_authority": "string",
      "tax_id": "string",
      "title": "string",
      "url": "string"
    },
    "identity_roles": [
      "SELLER"
    ],
    "tags": {},
    "type": "BUSINESS"
  }'
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", 
  "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"
    }
  }
}

Create ROLE_PARTNER credentials

  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.
Create API Key

Sandbox and Production

Sandbox and production

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

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
)

// Sandbox
val mpos = MPOSFinix(context, MerchantData(
    merchantId = "MUxxxxxx",
    mid = "",
    deviceId = "DVxxxxx",
    env = Environment.SB,
    userId = "USxxxxxxxxx",
    password = ""
))

// Production
val mpos = MPOSFinix(context, MerchantData(
    merchantId = "MUxxxxxx",
    mid = "",
    deviceId = "DVxxxxx",
    env = Environment.PROD,
    userId = "USxxxxxxxxx",
    password = ""
))