POS Integration
Reference
Data Model

POS Request model

sealed class PosRequest(
  val name: String,
) : Serializable {
 
  /**
   * Warm Up command will warm init the softPOS application to make it ready for payment.
   * You can send a warm-up command when your business application is doing configuration OR it is
   * under preparing for the coming transaction.
   */
  object WarmUp : PosRequest("WARM_UP"), Serializable
 
  /**
   * Activation Command: SoftPOS Application has to be activated before any other API calling.
   * This command triggers application to do activation by using the activation code
   * @param activationCode the activation code get from MineSec backend
   */
  data class Activation(val activationCode: String) : PosRequest("ACTIVATION"), Serializable
 
  /**
   * Enquiry the device status by sending this command.
   */
  object EnquiryDeviceStatus : PosRequest("ENQUIRY_STATUS"), Serializable
 
  /**
   * Force the device to do full reconfiguration by sending this command. The reconfiguration command
   * will force application to reload EMV profiles as well as crypto keys.
   */
  object ReloadConfiguration : PosRequest("RELOAD_CONFIGS"), Serializable
 
  /**
   * This command only works for SoftPOS Application which supports Bluetooth D177 Card Reader.
   * It is used to get the Bluetooth Connection status of D177 Card Reader.
   */
  object EnquiryBTStatus : PosRequest("ENQUIRY_BLUETOOTH_CONNECT_STATUS"), Serializable
 
  // Transaction Command
  sealed class Transaction(name: String) : PosRequest(name) {
 
    // Sale Operation
    data class Sale(
      // transaction amount. it's a BigDecimal way. e.g. BigDecimal("1.0").
      // currency is automatically configured in backend.
      val amount: BigDecimal,
 
      // Description that will be added into payment record / receipt.
      val description: String? = null,
 
      // Unique ID that is generated by business Application. it could be used for payment record query/search.
      val posMessageId: String? = null,
 
      // SoftPOS will be disappeared automatically immediately after payment action done if this item is set to true
      val autoDismissResult: Boolean = false,
    ) : Transaction("SALE"), Serializable
 
    /**
     * Authorization
     */
    data class Auth(
      // transaction amount. it's a BigDecimal way. e.g. BigDecimal("1.0").
      // currency is automatically configured in backend.
      val amount: BigDecimal,
 
      // Description that will be added into payment record / receipt.
      val description: String? = null,
 
      // Unique ID that is generated by business Application. it could be used for payment record query/search.
      val posMessageId: String? = null,
 
      // SoftPOS will be disappeared automatically immediately after payment action done if this item is set to true
      val autoDismissResult: Boolean = false,
    ) : Transaction("AUTH"), Serializable
 
    // Void
    data class Void(
      // original transaction Id
      val orgTranId: String,
 
      // Unique ID that is generated by business Application.
      // it could be used for payment action(or record) query/search.
      val posMessageId: String? = null,
 
      // void password.
      val adminPwd: String,
    ) : Transaction("VOID"), Serializable
 
    // Refund without card-present
    data class Refund(
      // original transaction Id
      val orgTranId: String,
 
      // Unique ID that is generated by business Application.
      // it could be used for payment action(or record) query/search.
      val posMessageId: String? = null,
 
      // void password.
      val adminPwd: String,
    ) : Transaction("REFUND"), Serializable
  }
 
  // transaction status query
  data class EnquiryTranStatus(
    // transaction id
    val orgTranId: String,
  ) : PosRequest("ENQUIRY_TRANSACTION_STATUS"), Serializable
 
 
  // settlement
  data class Settlement(
    // Unique ID that is generated by business Application.
    // it could be used for payment action(or record) query/search.
    val posMessageId: String? = null,
  ) : PosRequest("SETTLEMENT"), Serializable
 
}

POS Response Model

 
// App-to-app call response
sealed class PosResponse<T>(
  // error code when calling fails
  val rspCode: String,
  // error message when calling fails
  val rspMsg: String,
) : Serializable {
  // success object when calling is success. the data element represents a valid object returned by application.
  class Success<T>(val data: T, rspCode: String, rspMsg: String) : PosResponse<T>(rspCode, rspMsg), Serializable
 
  // failed calling. rspCode & rspMsg details the reason of failing
  class Failed<Unit>(rspCode: String, rspMsg: String, val tranId: String? = null) : PosResponse<Unit>(rspCode, rspMsg), Serializable
}
 
// Successful transaction response
data class TransactionResponse(
  // transaction ID unique per transaction. generated by MineSec Backend.
  val tranId: String,
 
  // trace ID. unique per transaction. generated by MineSec Backend.
  val trace: String,
 
  // RRN. unique per transaction. generated by payment host
  val rrn: String,
 
  // transaction type:SALE/VOID/REFUND/AUTH
  val tranType: String,
  // transaction status: Approved/Declined/Processing/Voided/Reversed
  val tranStatus: String,
  // card present approval auth code.
  val approvalCode: String,
  // payment Method: Visa/Mastercard/etc..
  val paymentMethod: String,
  // generic transaction card returned data.
  val cardData: CardData,
 
  // entryMode: NFC
  val entryMode: String,
  // masked Account: e.g. **** **** **** 1234
  val maskedAccount: String,
  // CVM method being used
  val cvmPerformed: String,
  // MID which process this transaction
  val acqMid: String,
  // TID which process this transaction
  val acqTid: String,
  // unique reference ID generated by application.
  val posMessageId: String,
  // merchant address
  val mchAddress: String,
  // merchant name
  val mchName: String,
  // total txn amount
  val totalAmount: BigDecimal,
 
  val createByName: String,
  val createdAt: String,
  val updatedAt: String,
) : Serializable
 
data class CardData(
  // application AID
  val aid: String,
  // emv app NAME
  val appName: String,
  // TC code
  val tc: String,
  // tsi
  val tsi: String,
  // tvr
  val tvr: String,
) : Serializable
 
// settlement response
data class SettlementResponse(
  // batch No.
  val batches: String,
  //
  val createByName: String,
 
  // unique reference id generated by application.
  val posMessageId: String,
  //val tranStatus: String,
  val createdAt: String,
  val updatedAt: String,
) : Serializable