> For the complete documentation index, see [llms.txt](https://developer.tokeninc.com/token-developer-portal-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.tokeninc.com/token-developer-portal-1/payment-service/payment-services/bank-app-protocol-extended-actions.md).

# 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

<figure><img src="https://3604734571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPaz8tFKqEd6volXC5G4B%2Fuploads%2F3wsuPbfCP4rZAPA0jsZ3%2Fextended_sale.jpg?alt=media&amp;token=8a9fe93d-d7ec-4908-9cd5-a5966cb101b8" alt=""><figcaption></figcaption></figure>

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

`Extended_Sale_Action` extends [Sale\_Action](https://developer.tokeninc.com/token-developer-portal-1/payment-service/payment-services/bank-app-protocol#id-1.-sale) 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.

{% hint style="info" %}
`Extended_Sale_Action` uses the existing `Sale_Action` contract together with the additional parameters described below.
{% endhint %}

***

### 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**

```kotlin
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**

```kotlin
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`.

{% hint style="info" %}
`pointUsageData` is required only when `saleType = Point_Usage`.
{% endhint %}

| 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**

```kotlin
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

<figure><img src="https://3604734571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPaz8tFKqEd6volXC5G4B%2Fuploads%2FbS2KNVojv8MIzTFuaP9p%2Fpoint_inquiry.jpg?alt=media&amp;token=a9729179-eb23-4ae1-8f19-d8cd57158e6a" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
`PointInquiryResponse` contains the total available point amount and the details of the available point pools.
{% endhint %}

***

### 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**

```kotlin
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

<figure><img src="https://3604734571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPaz8tFKqEd6volXC5G4B%2Fuploads%2F370heMDkUYD0nLsTviHf%2Frefund.jpg?alt=media&amp;token=2336cd78-0aea-44cc-9353-ae8798b3adde" alt=""><figcaption></figcaption></figure>

Refund (Void/Refund) operations will also be included in the communication between the Integration application and the Platform. The bank-side [Refund\_Action flow](https://developer.tokeninc.com/token-developer-portal-1/payment-service/payment-services/bank-app-protocol#id-7.-void-refund-flow) is already available in the current protocol.