API preview · Developer Docs

This section will guide you through the process of setup the SoftPOS (sometimes also refer to the PCI-CPoC, Tap to Phone etc) sandbox account, and how the POS integration works with the SoéPay SoftPOS. From that you can start integrate your App that supports contactless card/ device, and digital wallet payment acceptance.

Before you start

Getting the sandbox app

Before you start, you can request a SoéPay SoftPOS sandbox app by contacting us.

SoePay DEMO app

The DEMO app is also distributed via the Google Play Store.

However it is running in our sandbox environment, all transactions are default approved and will not charge to your account.

Creating the account (login credential)

As the app is running on merchant's device, it uses standard email/ password authentication.

After getting the DEMO app, you can follow the instruction to create the app account, OR you can create an account here

Call flow

To call the SoftPOS for accepting card/ QR payment, the flow is rather straight forward and simple, as the following

Request type

Currently, there are 2 intent types we support:

Transaction Request - com.spectratech.soepay.action.payment
- Support for sale, void, refund, auth & auth complete
Enquiry Request - com.spectratech.soepay.action.enquiry

Intent Extra

The intent extra as below:

(mandatory) API_KEY & API_TOKEN
(transaction)ECR_TRANSACTION_REQUEST - the transaction details, including the amount, preferred payment instrument
(enquiry) ECR_ENQUIRY_REQUEST - the enquiry details, including the unique messageId from the POS
(optional) ENFORCE_FETCH_CONFIG - to force the SoftPOS app to fetch the latest config from the backend, might incur a few seconds depending on the network condition

Sample credential (Public)

The below credential is publicly open for all dev to try out the API & SoftPOS app. We recommend you to create your own for security's sake.

data class Credential(
    val name: String? = null,
    val env: String? = null,
    val shop: String? = null,
    val apiKey: String? = null,
    val apiToken: String? = null,
)

val dummyCredential = Credential(
    env = "DEMO",
    name = "Sample credential",
    shop = "POS Integration Test",
    apiKey = "b6cac1ed6a06a7f85c331e09022b3c14118005790644376c31f3f7f3738685ef",
    apiToken = "13a4088da4f10d2d88863afa624a803b63fcf470c1fef44098b0b79dda1f4764"
)

Activity result

Before call the SoftPOS app, you might also want to register a callback for the activity result.

private val paymentLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->

    val ecrResult = result.data?.extras?.getString("ECR_TRANSACTION_RESULT")
    val gson = GsonBuilder().setPrettyPrinting().create()
    val jsonObject: JsonObject = JsonParser.parseString(ecrResult).asJsonObject
    val resultText = "code:${result.resultCode}\nResult: ${gson.toJson(jsonObject)}"

    val lastTranResult = gson.fromJson(ecrResult, TransactionModel::class.java)

    Log.d(tag, "$resultText")

}

Eg. to start a new sale, the intent would be like:

Intent("com.spectratech.soepay.action.payment")
  .apply {
      putExtra("ECR_TRANSACTION_REQUEST", transactionRequest)
      putExtra("API_KEY", dummyCredential.apiKey)
      putExtra("API_TOKEN", dummyCredential.apiToken)

      if (binding.switchEnforceFetch.isChecked)
          putExtra("ENFORCE_FETCH_CONFIG", true)
  }
  .also {
      try {
          paymentLauncher.launch(it)
      } catch (ex: Exception) {
          Toast.makeText(this@MainActivity, "Cannot start activity", Toast.LENGTH_SHORT).show()
      }
  }