Device Reader SDK Quickstart

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4/devices \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Cashier Three",
    "model": "PAX_A800",
    "name": "PAX_A800 Finix Device Reader SDK",
    "integration_mode": "SDK",
    "serial_number": "19046260947"
    }
  }'

{
  "id": "DVxcL2fiBdt9frYCKAbZikZK",
  "created_at": "2025-05-21T19:01:32.000581Z",
  "updated_at": "2025-05-21T19:01:32.000581Z",
  "configuration_details": null,
  "description": "Cashier Three",
  "enabled": false,
  "idle_message": null,
  "integration_mode": "SDK",
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "model": "PAX_A800",
  "name": "PAX_A800 Finix Device Reader SDK",
  "serial_number": "19046260947",
  "tags": {},
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/devices/DVxcL2fiBdt9frYCKAbZikZK"
    },
    "merchant": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

implementation("com.finix:pax-device-reader-sdk:0.1.0")

<!-- For network communication -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

class mposFinix(private val context: Context, private val merchantData: MerchantData)

context: Android application context
merchantData: Specific values which help identify the merchant

class MerchantData(
    // Merchant Id from Finix starting with MUxxxx
    val merchantId: String,

    // Finix mid (GUID representation)
    val mid: String,

    // Device ID - device registers with Finix, starting with DVxxxx
    val deviceId: String,

    val currency: Currency = Currency.USD,

    // Sandbox or Production
    val env: EnvEnum = EnvEnum.SB,

    // ROLE_MERCHANT or ROLE_PARTNER UserId
    val userId: String,

    //  ROLE_MERCHANT or ROLE_PARTNER password
    val password: String
)

Example : val mpos = mposFinix(
context,
MerchantData(
    merchantId = "MUxxxxxx",
    mid = "",
    deviceId = "DVxxxxx",
    env = EnvEnum.SB,
    userId = "USxxxxxxxxx",
    password = ""
)
)

VendorBindings.register(driver: VendorTerminalDriver)
FinixTerminalSDK.createDevice(
    activity: Activity,
    merchantData: MerchantData,
    options: TerminalOptions,
)

driver: The type of device (ie. PaxTerminalDriver)
activity: Android activity
merchantData: Merchant data class containing data specific to your merchant
options: Optional data that can affect the transaction processing (no need to set this value for now)


class MerchantData(
    // Merchant Id from Finix starting with MUxxxx
    val merchantId: String,

    // Finix mid (GUID representation)
    val mid: String,

    // Device ID - device registers with Finix, starting with DVxxxx
    val deviceId: String,

    // Application Id from Finix starting with APxxxx
    val applicationId: String,

    // Sandbox or Production
    val env: Environment = Environment.SB,

    // ROLE_MERCHANT or ROLE_PARTNER UserId
    val userId: String,

    //  ROLE_MERCHANT or ROLE_PARTNER password
    val password: String

    // Operating country of merchant
    val country: Country = Country.USA
)

Example : val mpos = mposFinix(
    context,
    MerchantData(
        merchantId = "MUxxxxxx",
        mid = "",
        deviceId = "DVxxxxx",
        env = EnvEnum.SB,
        userId = "USxxxxxxxxx",
        password = ""
    )
)

fun startTransaction(
    request: TransactionRequest
): TransactionHandle

data class TransactionRequest(
    val amount: Long,
    val transactionType: TransactionType,
    val splitTransfers: List<SplitTransfer>? = null,
    val tags: Map<String, String>? = null,
    val buyerIdentityId: String? = null,
    val tipAmount: Long = 0L,
    val surchargeAmount: Long = 0L,
    val idempotencyId: String? = null,
    val disabledCardEntryMethods: Set<CardEntryMethod> = emptySet(),
    val timeoutSeconds: Int = 30
)

interface TransactionHandle(
    val id: String
    val updates: Flow<TransactionUpdate>
    suspend fun cancel(): Result<Unit>
)

sealed class TransactionUpdate(
    data class Processing(val step: TransactionStep) : TransactionUpdate()

    data class Success(val result: TransactionResult) : TransactionUpdate()

    data class Error(val result: TransactionResult, val failureType: CardEntryFailureType) :
        TransactionUpdate()

    data class Retry(
        val disabledCardEntryMethods: Set<CardEntryMethod>,
        val failureType: CardEntryFailureType,
        val cardReadMethod: CardReadMethod
    ) : TransactionUpdate()
)

enum class TransactionStep {
    INITIALIZING,
    AWAITING_CARD,
    READING_CARD,
    CARD_READ_COMPLETE,
    AUTHORIZE_CARD,
    PROCESSING,
    SENT_TO_SERVER
}

fun uploadSignature(
    // Base64 encoded png of the signature
    pngEncodedBase64: String,
    // traceId of the successful transaction, found in TransactionResult
    traceId: String,
)