White-label App SDK
API Reference
Poi Request

PoiRequest

Overview

The PoiRequest sealed class represents various operations that the Headless SDK consumer can request, such as initiating a new transaction, performing a void, querying transaction status, or completing an authorization.

Designed to be serializable between processes (e.g., Android intents), the PoiRequest class offers flexibility for managing diverse transaction-related actions. Each subclass provides a strongly typed structure, making it easy for SDK users to consume and request specific operations, ensuring clear and structured communication between the application and the headless SDK.


Sub class

PoiRequest.ActionNew

Request a new transaction, applicable for transaction type SALE, AUTH, REFUND (card present, this is different from a linked-refund).

PropertyTypeConditionDefaultDescription
tranTypeTranTypeRequiredRequested transaction type.
amountAmountRequiredRequested amount.
profileIdStringRequiredThe enabler profile ID (provisioned before runtime). In the backend the profile contains the MID/ TID/ message format for corresponding gateway.
primaryTidString?OptionalnullOptionally specify the terminal ID to use.
descriptionString?OptionalnullOptionally provide the transaction description.
posReferenceString?OptionalnullOptionally provide the point of sale reference, usually this is the invoice number or a ID/ trackable from the caller system.
preferredAcceptanceTagString?ConditionalnullIf multiple acceptance is binded to the profileId, the backend service requires this preferred tag to select from the acceptance list.
cvmSignatureModeCvmSignatureModeOptionalSIGN_ON_PAPERIf transaction requires a signature CVM, whether to display the digital signature screen.
forcePaymentMethodList<PaymentMethod>?OptionalnullOptionally filter the supported payment method for this request.
forceFetchProfileBooleanOptionalfalseOptionally instruct the SDK should fetch the profile from remote before card tapping. Otherwise the SDK would try to use the locally cache profile.
tapToOwnDeviceBoolean?OptionalfalseFor tap to own device use case, setting up this flag is required for the payment kernel and backend to populate and handle required fields in the payment message to gateway.
installmentPlanString?OptionalnullOptional indicator for installment plan.
extraMap<String, String>?OptionalnullOptional extra parameters for backend payment message handling.

Usage

val actionNewSale = PoiRequest.ActionNew(
  tranType = TranType.SALE,
  amount = Amount(
    value = BigDecimal("10.00"),
    currency = Currency.getInstance("HKD"),
  ),
  // the pre-configured profile id via backend. Contains information like the MID/ TID/ routing/ message format and etc.
  profileId = "prof_01HWPEMPHW95AWD8YY0Q0VX8Y3",
  // if the profile is binded with multiple acceptance, this tag will be used in the backend to match for the acceptance selection.
  preferredAcceptanceTag = "SME",
  // if the profile support Visa, Mastercard & Amex,
  // passing in this field would result in **this request** only accepting VISA.
  forcePaymentMethod = listOf(PaymentMethod.VISA),
  description = "description 123",
  // your app/ system identifier
  posReference = "pos_${ULID.randomULID()}",
  // forcing the SDK to fetch profile from remote, otherwise the SDK would try to use local cached profile.
  forceFetchProfile = true,
  // indicate a specific TID to be used, this will be used for matching the binded MID/ TID from profile.
  primaryTid = "30157001",
  // If the transaction requires a signature CVM, `ELECTRONIC_SIGNATURE` would prompt the signature on screen
  cvmSignatureMode = CvmSignatureMode.ELECTRONIC_SIGNATURE
)

PoiRequest.ActionVoid

Target an original transaction, conducting a VOID action.

Usually a void is only available before the settlement (day end process). Once the transaction & batch is settled, the caller should instead request a refund for fund return.

PropertyTypeConditionDefaultDescription
tranIdStringRequiredThe identifier of the original transaction.

Usage

val actionVoid = PoiRequest.ActionVoid("tran_01G65Z755AFWAKHE12NY0CQ9FH")

PoiRequest.ActionLinkedRefund

For some gateway, like the MPGS, a linked refund is available.

Different from a ActionNew refund, a LinkedRefund doesn't require a card tapping again. The gateway can do a lookup for the original card transaction for processing.

Please note not all gateway support for linked refund, please check with our technical support for more details.

PropertyTypeConditionDefaultDescription
tranIdStringRequiredThe identifier of the original transaction.
amountAmount?OptionalnullThe amount to be refunded. If null, a full amount (same as the original transaction) refund will be performed.

Usage

val actionLinkedRefund = PoiRequest.ActionLinkedRefund(
  tranId = "tran_01G65Z755AFWAKHE12NY0CQ9FH",
  amount = Amount(
    value = BigDecimal("12.00"),
    currency = Currency.getInstance("USD")
  )
)

PoiRequest.ActionAdjust

To request a amount adjustment (like a tip adjustment, incremental auth, or refund adjustment).

Please note not all gateway support for adjustment, please check with our technical support for more details.

PropertyTypeConditionDefaultDescription
tranIdStringRequiredThe identifier of the original transaction.
amountAmountRequiredThe adjusted total amount of the transaction.

Usage

val actionAdjust = PoiRequest.ActionAdjust(
  tranId = "tran_01G65Z755AFWAKHE12NY0CQ9FH",
  amount = Amount(
    value = BigDecimal("20.00"),
    currency = Currency.getInstance("SDG")
  )
)

PoiRequest.ActionAuthComp

To capture (also referring to an Auth Complete) a pre-authorized transaction.

PropertyTypeConditionDefaultDescription
tranIdStringRequiredThe identifier of the original transaction.
amountAmountRequiredThe capture amount of the pre-authed transaction.

Usage

val actionComplete = PoiRequest.ActionAuthComp(
  tranId = "tran_01G65Z755AFWAKHE12NY0CQ9FH",
  amount = Amount(
    value = BigDecimal("300.00"),
    currency = Currency.getInstance("USD")
  )
)

PoiRequest.Query

To query the transaction by a Referencable.

The referencable can be constructed from:

  • tranId: auto generated from MineSec's backend, this is an ULID (opens in a new tab), prefixed with tran_
  • requestId: auto generated ULID (opens in a new tab) locally, prefixed with req_
  • posReference: passed in from the ActionNew request, dedicated for the POS system's identifier, like a invoice no or something like an UUID.
PropertyTypeDescription
referenceReferencableThe reference for requesting the remote data.

Usage

val queryByTranId = PoiRequest.Query(Referencable.TranId("tran_01G65Z755AFWAKHE12NY0CQ9FH"))
val queryByPosRef = PoiRequest.Query(Referencable.PosReference("your-pos-reference-identifier"))
val queryByRequestId = PoiRequest.Query(Referencable.RequestId("req_01G65Z755AFWAKHE12NY0CQ9FH"))