Installation and configuration

Installation

Add this to your buildScript repositories declaration

    repositories {
        maven { url 'https://nexus.devops.geopagos.com/repository/android-geopagos_public/' }
        google()
        mavenCentral()
        jcenter()
        maven { url 'https://jitpack.io' }
    }

And this to your module dependencies

    dependencies {
        implementation "com.geopagos.payments.sdk:payments-core:$paymentVersion"
    }

And for each type of reader you want to support (you may choose to support one or more)

QPOS

  dependencies {
    implementation "com.geopagos.payments.sdk:sdk-reader-qpos:$paymentVersion"
  }

MagicPOS

  dependencies {
    implementation "com.geopagos.payments.sdk:sdk-reader-magicpos:$paymentVersion"
  }

Urovo SmartPOS

  dependencies {
    implementation "com.geopagos.payments.sdk:sdk-reader-urovo:$paymentVersion"
  }

MoreFun SmartPOS

  dependencies {
    implementation "com.geopagos.payments.sdk:sdk-reader-morefun:$paymentVersion"
  }

Configure the SDK

This consists of initializing the Readers SDK, provide data acording to code documentation.

First of all, SDK initialization is required, there is a Builder SDKPaymentsConfiguration.Builder to configure the required data:

val sdkPaymentsConfiguration = SDKPaymentsConfiguration.Builder()
    .setLogger(<LOGGER>)
    .setSwipePinDecider(<SWIPE_PIN_DECIDER>)
    .build(
        <CONTEXT>,
        <ENDPOINT>,
        setOf(<READER_INSTALLER_SET>),
        setOf(<PLUGIN_INSTALLER_SET>),
        <FLOW>
    )

val flowHandle = SDKPayments.init(sdkPaymentsConfiguration)

Where:

• CONTEXT is the ApplicationContext
• ENDPOINT is a String with the URL path of the processor URL. Geopagos will provide this URL
• READER_INSTALLER_SET is a set of reader installers. According to the dependencies you added
• PLUGIN_INSTALLER_SET is a set of optional plugins. According to the dependencies you added. Geopagos will provide the corresponding documentation according to the contracted plugins
• FLOW is the transaction processing flow to use (SDKPaymentsFlow). Integrators must pass an instance of the flow variant described below (currently V1).
• LOGGER is a custom logger you can provide to get additional information about what the sdk is doing (is useful for debugging purposes)
• SWIPE_PIN_DECIDER is an interface that allows you to decide if the SDK should ask pin on swipe transactions. This is optional. By default the SDK is loaded with an implementation that decides if a Swipe Card requires PIN based on the last ServiceCode Digit
• SDKPayments.init returns a SDKPaymentsFlowHandle that you must keep to create transaction intents for the selected flow.

Transaction flow

The transaction flow is the high-level variant of how the SDK carries a transaction from start to finish on the inside. It shapes internal transaction processing so newer behaviour can be introduced without breaking apps that still select an older flow.

V1 is the transaction pipeline that matches what the SDK has shipped and supported in integrations until today—the behaviour integrators already rely on in production. Newer flows may be added later; V1 is expected to become the legacy flow once those alternatives are generally available, while remaining supported for existing apps.

Use SDKPaymentsFlow.V1 to run the V1 pipeline. It is a class with one optional constructor parameter:

Parameter	Default	Meaning
mustConfirmOnline	true	When true, after an approved online result the SDK performs the online confirmation step against the host. When false, confirmation is handled locally without that online confirm path.

Example:

val flow = SDKPaymentsFlow.V1(mustConfirmOnline = true)
// or simply: SDKPaymentsFlow.V1()  // same as mustConfirmOnline = true

At initialization, the SDK checks that every configured plugin is compatible with the resolved internal flow type. If a plugin does not support the selected flow, init throws IllegalArgumentException naming the incompatible installers.

Plugin Compatibility	V1
SDKForcePinDeciderDeciderPlugin	Yes
SDKBinCvmContactlessDeciderPlugin	Yes

About installers

Each reader has its own installer.

QPOS

SDKQposReader.getInstaller()

MagicPOS

SDKMagicPosReader.getInstaller()

Urovo SmartPOS

SDKUrovoReader.getInstaller(
    <SDK_FILE_WRAPPER>,
    <PIN_KEYBOARD_CONFIGURATION>
)

Where:

• SDK_FILE_WRAPPER allows you to provide a configuration file to the getInstaller

sealed class SDKFileWrapper(val context: Context) {

    /**
     * You should use this class if the file that you want to provide is stored as an asset on your application
     *
     *  @param context the application context
     *  @param name the file name of the asset
     * **/
    class Asset(context: Context, val name: String) : SDKFileWrapper(context)

    /**
     * You should use this class if the file that you want to provide is stored as a file on your device
     *
     *  @param context the application context
     *  @param path the path of the file
     * **/
    class File(context: Context,  val path: String) : SDKFileWrapper(context)
}

//Example
    SDKFileWrapper.Asset(applicationContext, "urovo_configuration.json")

• PIN_KEYBOARD_CONFIGURATION allows you to customize the buttons of the PIN keyboard. You can customize the texts and its sizes, the margins and the background colors as illustrated in the example below (see also customize PIN keyboard).

data class SDKUrovoPinTexts(
  val title : String,
  val message : String,
  val pinRetriesText: String,
  val okText : String,
  val cancelText : String,
  val deleteText : String
)

//Example
val pinKeyboardConfiguration = SDKPinKeyboardConfiguration.Builder().build(
  SDKBasicPinKeyboardConfiguration(
    SDKUrovoPinTexts(
      "Enter pin",
      "Enter pin",
      "Retries left",
      "OK",
      "Cancel",
      "Delete"
    ),
    backgroundColor = listOf(
      0xff37394f.toInt(),
      0xffff00ff.toInt(),
      0xffffff00.toInt(),
      0xffff0000.toInt(),
      0xffef464d.toInt(),
      0xffcead03.toInt(),
      0xff38ae93.toInt(),
    )
  )
)

MoreFun SmartPOS

SDKMoreFunReader.getInstaller(
    <PIN_KEYBOARD_CONFIGURATION>,
    <SDK_FILE_WRAPPER>
)

Where:

• SDK_FILE_WRAPPER allows you to provide a configuration file to the getInstaller.

sealed class SDKFileWrapper(val context: Context) {

  /**
   * You should use this class if the file that you want to provide is stored as an asset on your application
   *
   *  @param context the application context
   *  @param name the file name of the asset
   * **/
  class Asset(context: Context, val name: String) : SDKFileWrapper(context)

  /**
   * You should use this class if the file that you want to provide is stored as a file on your device
   *
   *  @param context the application context
   *  @param path the path of the file
   * **/
  class File(context: Context,  val path: String) : SDKFileWrapper(context)
}

// example
    SDKFileWrapper.Asset(applicationContext, "morefun_smartpos_reader_config.json")

• PIN_KEYBOARD_CONFIGURATION enables you to personalize the buttons on the PIN keyboard according to your preferences. You have the flexibility to customize the displayed text as illustrated in the example below (see also customize PIN keyboard ):

data class SDKMoreFunKeyboardTexts(
  val title: String,
  val okText: String,
  val cancelText: String,
  val deleteText: String,
  val pinOfflineLastTryMessage: String,
  val layoutId: Int = 0
)

// example
SDKMoreFunKeyboardTexts(
  title = "enter PIN",
  okText = "ok",
  cancelText = "cancel",
  deleteText = "delete",
  pinOfflineLastTryMessage = "delete"
)

Initialization Example

val swipePinDecider = object : SDKSwipePinDecider{
    override fun decide(card: SDKTransactionCard.Magnetic, decision: (pinRequire: Boolean) -> Unit) {
        decision(true)
    }
}
        
val sdkPaymentsConfiguration = SDKPaymentsConfiguration.Builder()
    .setLogger(myCustomLogger)
    .setSwipePinDecider(swipePinDecider)
    .build(
        applicationContext,
        "https://example.net/",
        setOf(readerInstallers),
        setOf(pluginInstallers),
        SDKPaymentsFlow.V1(mustConfirmOnline = true)
    )

val flowHandle: SDKPaymentsFlowHandle = SDKPayments.init(sdkPaymentsConfiguration)
flowHandle.createTransactionIntent(sdkV1TransactionData, sdkV1TransactionListener)