`PoiRequest`

Overview

The PoiRequest sealed class represents various operations that an app using the Embedded Payment SDK 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 Embedded Payment 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).

Property	Type	Condition	Default	Description
`tranType`	`TranType`	Required		Requested transaction type.
`amount`	`Amount`	Required		Requested amount.
`profileId`	`String`	Required		The Access Gateway profile ID (provisioned before runtime). In the backend the profile contains the MID/ TID/ message format for corresponding gateway.
`primaryTid`	`String?`	Optional	`null`	Optionally specify the terminal ID to use.
`description`	`String?`	Optional	`null`	Optionally provide the transaction description.
`posReference`	`String?`	Optional	`null`	Optionally provide the point of sale reference, usually this is the invoice number or a ID/ trackable from the caller system.
`preferredAcceptanceTag`	`String?`	Conditional	`null`	If multiple `acceptance` entries are bound to the `profileId`, the backend service requires this preferred tag to select from the acceptance list.
`cvmSignatureMode`	`CvmSignatureMode`	Optional	`SIGN_ON_PAPER`	If transaction requires a signature CVM, whether to display the digital signature screen.
`forcePaymentMethod`	`List<PaymentMethod>?`	Optional	`null`	Optionally filter the supported payment method for this request.
`forceFetchProfile`	`Boolean`	Optional	`false`	Optionally instruct the SDK should fetch the profile from remote before card tapping. Otherwise the SDK would try to use the locally cache profile.
`tapToOwnDevice`	`Boolean?`	Optional	`false`	For 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.
`installmentPlan`	`String?`	Optional	`null`	Optional indicator for installment plan.
`extra`	`Map<String, String>?`	Optional	`null`	Optional 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 bound to multiple acceptances, 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 bound 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.

Property	Type	Condition	Default	Description
`tranId`	`String`	Required		The 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.

Property	Type	Condition	Default	Description
`tranId`	`String`	Required		The identifier of the original transaction.
`amount`	`Amount?`	Optional	`null`	The 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 or refund adjustment).

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

Property	Type	Condition	Default	Description
`tranId`	`String`	Required		The identifier of the original transaction.
`amount`	`Amount`	Required		The 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.ActionIncrementalAuth`

To raise the authorized amount of an open pre-authorization (AUTH), for example when a hotel stay or a rental runs longer than first estimated. Capture the final amount afterward with PoiRequest.ActionAuthComp.

Please note not all gateways support incremental authorization, please check with our technical support for more details.

Property	Type	Condition	Default	Description
`tranId`	`String`	Required		The identifier of the open pre-authorization transaction.
`amount`	`Amount`	Required		The new total authorized amount, not the increment. It must be in the currency of the original pre-authorization and be greater than the amount currently authorized.

Usage

// the pre-auth was for 100.00, raise the total authorized amount to 150.00
val actionIncremental = PoiRequest.ActionIncrementalAuth(
  tranId = "tran_01G65Z755AFWAKHE12NY0CQ9FH",
  amount = Amount(
    value = BigDecimal("150.00"),
    currency = Currency.getInstance("USD")
  )
)

`PoiRequest.ActionAuthComp`

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

Property	Type	Condition	Default	Description
`tranId`	`String`	Required		The identifier of the original transaction.
`amount`	`Amount`	Required		The 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 by Access Gateway, 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.

Property	Type	Description
`reference`	`Referencable`	The 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"))

HeadlessService WrappedResult