Bank App Protocol - Extended Actions

This protocol enables the PGW (Payment Gateway) application to invoke specific operations in banking applications. Banking applications integrate with the PGW by implementing this protocol.

1. Extended Sale

In sales flows, the PGW sends the Extended_Sale_Action intent instead of the standard Sale_Action intent.

Extended_Sale_Action extends Sale_Action and is used in scenarios where the sale type and execution mode are determined by the PGW.

It includes the same common parameters as Sale_Action, while also supporting additional parameters for defining the sale type and execution behavior.

Extended_Sale_Action uses the existing Sale_Action contract together with the additional parameters described below.

---

1.1 Added Parameters

The following parameters are added on top of the existing Sale_Action parameters for use with Extended_Sale_Action.

Parameter	Type	Requirement	Description
saleType	String	Required	Specifies the type of sale to be performed.
executionType	String	Required	Specifies how the banking application should process the corresponding sale flow.
installmentCount	Int	Conditional	Required when saleType = Installment_Sale.
pointUsageData	String / JSON	Conditional	Required when saleType = Point_Usage.

---

1.1.1 Sale Type

Defines the type of sale to be performed using Extended_Sale_Action.

Value	Description	Additional Required Parameter
Normal_Sale	Standard card sale. Under Extended_Sale_Action, it is primarily used for direct sales.	None
Installment_Sale	Sale where the installment count is provided externally.	installmentCount
Point_Usage	Sale performed using the provided point usage information.	pointUsageData

ExtendedSaleType

enum class ExtendedSaleType(val wireValue: String) {
    @SerializedName("Normal_Sale")
    NORMAL_SALE("Normal_Sale"),

    @SerializedName("Installment_Sale")
    INSTALLMENT_SALE("Installment_Sale"),

    @SerializedName("Point_Usage")
    POINT_USAGE("Point_Usage")
}

---

1.1.2 Execution Type

Defines how the banking application processes the specified sale type.

Value	Description
Interactive	The banking application may display the user screens required for the specified sale type.
Direct	The banking application proceeds directly with the specified sale type without displaying the transaction type selection screen.

ExtendedSaleExecutionType

enum class ExtendedSaleExecutionType(val wireValue: String) {
    @SerializedName("Interactive")
    INTERACTIVE("Interactive"),

    @SerializedName("Direct")
    DIRECT("Direct")
}

---

1.1.3 Point Usage Data

PointUsageData contains the point usage information required when saleType is set to Point_Usage.

pointUsageData is required only when saleType = Point_Usage.

Field	Type	Description
totalUsedPointAmount	Long	Total amount of points used in the transaction.
usedPoolCount	Int	Number of point pools used in the transaction.
usedPools	List<UsedPool>	Contains the details of the point pools used in the transaction.

1.1.3.1 UsedPool

Represents a point pool used as part of the transaction.

Field	Type	Description
poolId	Int	Identifies the point pool used in the transaction.
poolTotalPointAmount	Long	Total amount of points used from the corresponding point pool.

PointUsageData Model

data class PointUsageData(
    @SerializedName("totalUsedPointAmount")
    val totalUsedPointAmount: Long = 0,

    @SerializedName("usedPoolCount")
    val usedPoolCount: Int = 0,

    @SerializedName("usedPools")
    val usedPools: List<UsedPool> = emptyList()
)

data class UsedPool(
    @SerializedName("poolId")
    val poolId: Int = 0,

    @SerializedName("poolTotalPointAmount")
    val poolTotalPointAmount: Long = 0
)

2. Point Inquiry

For point inquiry requests, the Point_Inquiry_Action intent is used. The banking application is expected to return a PointInquiryResponse together with the result.

PointInquiryResponse contains the total available point amount and the details of the available point pools.

---

2.1 Point Inquiry Response

PointInquiryResponse represents the point information returned by the banking application.

Field	Type	Description
totalAvailablePointAmount	Long	Total amount of points available for use.
poolCount	Int	Number of available point pools.
pools	List<PointPool>	Contains the details of the available point pools.

2.1.1 PointPool

Represents an available point pool returned as part of the point inquiry response.

Field	Type	Description
poolId	Int	Identifies the point pool.
poolName	String	Name of the point pool.
poolTotalPointAmount	Long	Total amount of points available in the corresponding point pool.

PointInquiryResponse Model

data class PointInquiryResponse(
    @SerializedName("totalAvailablePointAmount")
    val totalAvailablePointAmount: Long = 0,

    @SerializedName("poolCount")
    val poolCount: Int = 0,

    @SerializedName("pools")
    val pools: List<PointPool> = emptyList()
)

data class PointPool(
    @SerializedName("poolId")
    val poolId: Int = 0,

    @SerializedName("poolName")
    val poolName: String = "",

    @SerializedName("poolTotalPointAmount")
    val poolTotalPointAmount: Long = 0
)

3. Refund

Refund (Void/Refund) operations will also be included in the communication between the Integration application and the Platform. The bank-side Refund_Action flow is already available in the current protocol.