`HeadlessSetup`

Overview

The HeadlessSetup object provides essential methods for initializing and configuring the SoftPOS. This includes setting up EMV parameters, CAPKs, terminal parameters and keys.

Methods

`initSoftPos`

This is a suspended method and should be called within a coroutine.

Initializes the SoftPOS SDK. This method should be called each time the application starts up (for example, in the Application's onCreate).

Parameters

Name	Type	Condition	Description
`app`	`Application`	Required	The application instance.
`licenseFileName`	`String`	Required	The name of the license file.

Returns

Return Type	Description
`WrappedResult<SdkInitResp>`	A wrapped result containing the SDK version and ID.

Usage

val initResult = HeadlessSetup.initSoftPos(application, "license_file_name")
// Success(value=SdkInitResp(sdkVersion=1.10.105.12.17, sdkId=4411be126c0c91b7))

`initialSetup`

This is a suspended method and should be called within a coroutine.

Performs the initial setup for the SoftPOS. This method should be called once per app installation.

Parameters

Name	Type	Description
`context`	`Context`	The application or activity context.
`builderAction`	`(SetupOptionBuilder.() -> Unit)? = null`	Optional configuration for the setup options.

Returns

Return Type	Description
`SetupResp`	The setup response containing the results of the setup process.

Usage

// with default option
val setupResult1 = HeadlessSetup.initialSetup(context)
 
// with test capk
val setupResult2 = HeadlessSetup.initialSetup(context) {
  withTestCapk = true
}
 
// with a custom PIN pad
val setupResult3 = HeadlessSetup.initialSetup(context) {
  pinPadConfig = PinPadConfig(
    size = PinPadSize.LARGE,
    position = PinPadPosition.BOTTOM_CENTER,
    instructionText = "Please enter your PIN",
    timeoutSeconds = 45,
  )
}
 
// show the SDK's transaction result screen
val setupResult4 = HeadlessSetup.initialSetup(context) {
  enableResultScreen = true
}

Setup options

Option	Type	Default	Description
`withTestCapk`	`Boolean`	`false`	Load the test CAPKs instead of the live ones.
`pinPadConfig`	`PinPadConfig`	default	Customize the secure PIN entry UI, see `PinPadConfig`.
`enableResultScreen`	`Boolean`	`false`	Show the SDK's own result screen (approved / declined) once the transaction is decided. The activity only finishes after the cardholder or merchant acknowledges it. On a decline the screen offers a retry without leaving the SDK. Override `ScreenProvider.ResultScreen` to customize it.

`getEmvParams`

Retrieves the list of configured EMV parameters.

Returns

Return Type	Description
`List<EmvParam>`	A list of EMV parameters.

Usage

val emvParams = HeadlessSetup.getEmvParams()

`getCapks`

Retrieves the list of configured CAPKs.

Returns

Return Type	Description
`List<CapkParam>`	A list of CAPKs.

Usage

val capks = HeadlessSetup.getCapks()

`getTermParam`

Retrieves the terminal parameters.

Returns

Return Type	Description
`TerminalParam`	The terminal parameters.

Usage

val termParam = HeadlessSetup.getTermParam()

Data Classes

`SetupResp`

Represents the setup response.

Properties

Property	Type	Description
`sdkRes`	`WrappedResult<SdkInitResp>`	The SDK initialization result.
`emvRes`	`List<WrappedResult<EmvParamResp>>`	The EMV setup results.
`capkRes`	`List<WrappedResult<CapkResp>>`	The CAPK setup results.
`termRes`	`WrappedResult<TermParamResp>`	The terminal setup result.
`keyRes`	`List<WrappedResult<InjectKeyResp>>`	The key setup results.

`SdkInitResp`

Represents the SDK initialization response.

Properties

Property	Type	Description
`sdkVersion`	`String`	The SDK version.
`sdkId`	`String`	The SDK ID.

`EmvParamResp`

Represents the EMV parameter response.

Properties

Property	Type	Description
`aid`	`String`	The AID of the EMV parameter.

`CapkResp`

Represents the CAPK response.

Properties

Property	Type	Description
`rid`	`String`	The RID of the CAPK.
`keyIndex`	`Int`	The key index of the CAPK.

`TermParamResp`

Represents the terminal parameter response.

Properties

Property	Type	Description
`terminalType`	`String`	The terminal type.

`InjectKeyResp`

Represents the injected key response.

Properties

Property	Type	Description
`clientKeyType`	`String`	The client key type.

`PinPadConfig`

Configures the secure PIN entry UI. Passed to initialSetup's builder via pinPadConfig. It is an app-wide setting — persisted across app restarts, not reconfigured per transaction — and applies to both places a PIN can be requested: the on-device PIN (the EMV kernel's own CVM-selected PIN) and the SCA PIN (a standalone PIN-based second authorization requested by the host after the first authorization is declined).

Properties

Property	Type	Default	Applies to	Description
`size`	`PinPadSize`	`DEFAULT`	on-device + SCA	Digit key size preset.
`position`	`PinPadPosition`	`AUTO`	on-device + SCA	Where the PIN pad is anchored on screen, as a 3x3 grid.
`instructionText`	`String?`	`null`	on-device + SCA	Text shown above the keypad. `null` keeps the SDK's built-in copy.
`deleteButtonColor`	`@ColorInt Int?`	`null`	on-device + SCA	Delete/backspace key color. `null` keeps the SDK's default.
`completeButtonColor`	`@ColorInt Int?`	`null`	on-device + SCA	Confirm button and digit-mask dot color. `null` keeps the default.
`enablePinBypass`	`Boolean`	`true`	on-device + SCA	Whether the cardholder can bypass PIN entry when the card/CVM allows it.
`enablePinShuffle`	`Boolean`	`false`	on-device only	Randomizes the digit layout per entry. The SCA standalone PIN pad has no shuffle option at the vendor API level, so this is ignored there.
`timeoutSeconds`	`Int?`	`null`	on-device + SCA	How long the cardholder has to enter the PIN before the pad times out, in seconds. `null` keeps the SDK's built-in timeout.

Usage

val setupResult = HeadlessSetup.initialSetup(context) {
  pinPadConfig = PinPadConfig(
    size = PinPadSize.LARGE,
    position = PinPadPosition.BOTTOM_CENTER,
    instructionText = "Please enter your PIN",
    timeoutSeconds = 45,
  )
}

`PinPadSize`

Digit key size preset for PinPadConfig.size.

Values

Value	Description
`COMPACT`	Smaller digit keys.
`DEFAULT`	Keeps the SDK's built-in sizing.
`LARGE`	Larger digit keys.

`PinPadPosition`

Where the PIN pad is anchored on screen, as a 3x3 grid, for PinPadConfig.position.

Values

Value	Description
`AUTO`	Lets the SDK pick its own default placement.
`TOP_START`, `TOP_CENTER`, `TOP_END`	Top row.
`CENTER_START`, `CENTER`, `CENTER_END`	Middle row.
`BOTTOM_START`, `BOTTOM_CENTER`, `BOTTOM_END`	Bottom row.

Quickstart Guide HeadlessActivity