> 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/other-payment-services/tts-app-integration.md).

# TTS App Integration

## 1. App Definition

For your app to be recognized properly by the device, you should add the following meta-data to your AndroidManifest.xml file.

{% hint style="warning" %}
"1234" will be your payment operator id. We will send it to you.
{% endhint %}

```xml
<meta-data android:name="app_name" android:value="TTS_1234_APPNAME" />
<meta-data
    android:name="app_model_type"
    android:value="1000TR" />
<meta-data
    android:name="app_version"
    android:value="100000001" />
```

## 2. Protocol

The information required for communication between the banking application and the platform is provided below.

### 2.1. Sale

<figure><img src="https://3604734571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPaz8tFKqEd6volXC5G4B%2Fuploads%2FFzcIJuELOIWfK98oqqTn%2Fimage.png?alt=media&amp;token=6d2b9ffc-e75d-481a-ab22-aa2f00abf43a" alt=""><figcaption></figcaption></figure>

Following code snippet is used by PaymentGateway in order to open payment application:

```java
Bundle bundle = new Bundle();
bundle.putInt("Amount",amount);
bundle.putString("Plate",plate)
bundle.putString("TaxID",taxId); 
bundle.putString("UUID",uuid);
bundle.putString("FuelType",fuelType);
bundle.putInt("FuelQuantity",fuelQuantity);
bundle.putInt("FuelPrice",fuelPrice); // Price per liter
bundle.putInt("SaleType", saleType);
bundle.putString("foodCardTaxes": [{"amount": int, "taxPercent": (int)}]);
```

**Amount** : Integer: Ex: 1.25 TL is written 125

**UUID:** Transactions are kept with this value on Payment Gate Way and your application in case of a power cut. Payment Gate Way sends this value and waits for the return of the transaction result.

**Plate**: String: Ex: "34AA111"

**Fuel Type:**

| **Yakıt Tipi** | **id**           |
| -------------- | ---------------- |
| KURSUNSUZ95    | 1                |
| KURSUNSUZ95-2  | 2                |
| KURSUNSUZ98    | 3                |
| MOTORIN        | 4                |
| MOTORIN2       | 5                |
| OTOGAZLPG      | 6                |
| GAZYAGI        | 7                |
| YAKITNAFTA     | 8                |
| LNG            | 9                |
| ELEKTRIK       | 10               |
| CNG            | 11               |
| ADBLUE         | <p></p><p>12</p> |

**SaleType**

| **Satış Tipi**      | **id** |
| ------------------- | ------ |
| TASIT\_TANIMA       | 1      |
| PLAKA\_GIRISI       | 2      |
| TEST                | 3      |
| TRANSFER            | 4      |
| PLAKASIZ            | 5      |
| TANKERLE\_SATIS     | 6      |
| UTTS                | 7      |
| UTTS\_TASIT\_TANIMA | 8      |

**foodCardTaxes:** (JSON Array): A list of objects containing the `amount` (int) and the `taxPercent`  (int,e.g., 1800 = 18.00%).

After the payment process, the payment application should return the result.

```java
void onSaleResponseRetrieved(Integer price, ResponseCode code, Boolean hasSlip, SlipType slipType, String cardNo, String ownerName) {
   Intent resultIntent = new Intent();
   Bundle bundle = new Bundle();
   bundle.putInt("ResponseCode", code.ordinal());
   bundle.putInt("Amount",price);
   bundle.putInt("BatchNo",0);
   bundle.putInt("TxnNo",0);
   bundle.putBoolean("IsSlip", hasSlip);
   bundle.putString("RefundInfo", refound_info); 
  
   if (hasCustomerSlip) {
       bundle.putString("customerSlipData", PrintHelper.getFormattedText(getSampleReceipt(cardNo, ownerName), SlipType.CARDHOLDER_SLIP));
   }
   if (hasMerchantSlip) {
       bundle.putString("merchantSlipData", PrintHelper.getFormattedText(getSampleReceipt(cardNo, ownerName), SlipType.MERCHANT_SLIP));
   }
   resultIntent.putExtras(bundle);
   setResult(Activity.RESULT_OK,resultIntent);
   finish();
}
```

**responseCode** : Result of the payment process

```java
enum  RESPONSE_CODE{
    SUCCESS,
    ERROR,
    CANCELLED,
    OFFLINE_DECLINE,
    UNABLE_DECLINE,
    ONLINE_DECLINE
}
```

**amount** : Integer. Amount that is charged by the payment application. If amount is less than the Broadcasted Amount by Payment Gateway, it means Partial Limit is applied.

**batchNo** : The current Batch No which includes current sale.

**txnNo** : The current Txn No of the sale in current Batch.

**IsSlip**: Indicates that if a payment slip will be printed or not. (true to print slip)

**customerSlipData**: Formatted String for card holder slip.

**merchantSlipData**: Formatted String for merchant slip.

**Sample Code to Generate Formatted Slip String**

```java
public static String getFormattedText(SampleReceipt receipt, SlipType slipType) {
        StyledString styledText = new StyledString();

        styledText.setLineSpacing(0.5f);
        styledText.setFontSize(12);
        styledText.setFontFace(PrinterDefinitions.Font_E.SourceSansPro);
        styledText.addTextToLine(receipt.getMerchantName(), Alignment.Center);

        styledText.newLine();
        styledText.setFontFace(PrinterDefinitions.Font_E.Sans_Semi_Bold);
        styledText.addTextToLine("İŞYERİ NO:", Alignment.Left);
        styledText.setFontFace(PrinterDefinitions.Font_E.SourceSansPro);
        styledText.addTextToLine(receipt.getMerchantID(), Alignment.Right);

        styledText.newLine();
        styledText.setFontFace(PrinterDefinitions.Font_E.Sans_Semi_Bold);
        styledText.addTextToLine("TERMİNAL NO:", Alignment.Left);
        styledText.setFontFace(PrinterDefinitions.Font_E.SourceSansPro);
        styledText.addTextToLine(receipt.getPosID(), Alignment.Right);

        styledText.newLine();
        if (slipType == SlipType.CARDHOLDER_SLIP) {
            styledText.addTextToLine("MÜŞTERİ NÜSHASI", Alignment.Center);
            styledText.newLine();
        }
        else if (slipType == SlipType.MERCHANT_SLIP) {
            styledText.addTextToLine("İŞYERİ NÜSHASI", Alignment.Center);
            styledText.newLine();
        }
        styledText.addTextToLine("SATIŞ", Alignment.Center);

        SimpleDateFormat sdf = new SimpleDateFormat("dd-MM-yy HH:mm:ss", Locale.getDefault());
        String time = sdf.format(Calendar.getInstance().getTime());

        styledText.newLine();
        styledText.addTextToLine(time + " " + "C ONLINE", Alignment.Center);

        styledText.newLine();
        styledText.addTextToLine(receipt.getCardNo(), Alignment.Center);

        styledText.newLine();
        styledText.addTextToLine(receipt.getFullName(), Alignment.Center);

        styledText.setLineSpacing(1f);
        styledText.setFontSize(14);
        styledText.setFontFace(PrinterDefinitions.Font_E.Sans_Semi_Bold);
        styledText.newLine();
        styledText.addTextToLine("TUTAR:");
        styledText.addTextToLine(receipt.getAmount(), Alignment.Right);

        styledText.setLineSpacing(0.5f);
        styledText.setFontSize(10);
        styledText.newLine();
        if (slipType == SlipType.CARDHOLDER_SLIP) {
            styledText.addTextToLine("KARŞILIĞI MAL/HİZM ALDIM", Alignment.Center);
        }
        else {
            styledText.addTextToLine("İşlem Şifre Girilerek Yapılmıştır", Alignment.Center);
            styledText.newLine();
            styledText.addTextToLine("İMZAYA GEREK YOKTUR", Alignment.Center);
        }

        styledText.setFontFace(PrinterDefinitions.Font_E.Sans_Bold);
        styledText.setFontSize(12);
        styledText.newLine();
        styledText.addTextToLine("SN: " + "0001");
        styledText.addTextToLine("ONAY KODU: " + "235188", Alignment.Right);

        styledText.setFontSize(8);
        styledText.setFontFace(PrinterDefinitions.Font_E.Sans_Semi_Bold);
        styledText.newLine();
        styledText.addTextToLine("GRUP NO:" + receipt.getGroupNo());

        styledText.newLine();
        styledText.addTextToLine("AID: " + receipt.getAid());

        styledText.newLine();
        styledText.addTextToLine("BU İŞLEM YURT İÇİ KARTLA YAPILMIŞTIR", Alignment.Center);
        styledText.newLine();
        styledText.addTextToLine("BU BELGEYİ SAKLAYINIZ", Alignment.Center);
        styledText.newLine();

        styledText.printBitmap("ykb", 20);
        styledText.addSpace(100);

        return styledText.toString();
    }
```

You can receive the Z No and the Receipt No as;

```java
getIntent().getExtras().getString("zNO");
getIntent().getExtras().getString("receiptNo");
```

#### **2.1.1 Manifest Modifications**

To be able to get data from payment gateway, there should be intent filter like below in related class.

```xml
<activity android:name=".SaleActivity">
    <intent-filter>
        <action android:name="TTS_Sale_Action" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>
```

### 2.2. Pos Transactions <a href="#id-2.-pos-transactions" id="id-2.-pos-transactions"></a>

<img src="https://developer.tokeninc.com/token-developer-portal-1/~gitbook/image?url=https%3A%2F%2F3604734571-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FPaz8tFKqEd6volXC5G4B%252Fuploads%252FwZycfGi4jWutJgNGqcrj%252Fimage.png%3Falt%3Dmedia%26token%3Df2d7bd3f-9cf2-415d-b852-3e0da90aa4a2&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=9d18a7b771219beeb58caf96bb640ef0&#x26;sv=3" alt="" height="78" width="346">

Following code snippet is used by PaymentGateway in order to open payment application:

```java
	Intent sendIntentPosTxn = new Intent();
	sendIntentPosTxn.setPackage(tag);
	sendIntentPosTxn.setAction(getResources().getString(R.string.PosTxn_Action));//PosTxn_Action="PosTxn_Action"
	sendIntentPosTxn.setType("text/plain");
	startActivityForResult(sendIntentPosTxn, getResources().getInteger(R.integer.PosTxn_Request_Code)); //PosTxn_Request_Code=13
```

After the pos transaction process, the payment application should send the result.

```java
	Intent resultIntent = new Intent();
	Bundle bundle = new Bundle();
    bundle.putInt("ResponseCode",responseCode);
    resultIntent.putExtras(bundle);
    setResult(Activity.RESULT_OK,resultIntent); //PosTxn_Request_Code=13
    finish();
```

**responseCode** : Return of the pos transaction request.

#### **2.2 .1 Manifest Modifications**

To be able to get data from payment gateway, there should be intent filter like below in related class.

```xml
        <activity android:name=".PosTxnActivity">
            <intent-filter>
                <action android:name="PosTxn_Action" />

                <category android:name="android.intent.category.DEFAULT" />

                <data android:mimeType="text/plain" />
            </intent-filter>
        </activity>
```

### 2.3. Pos Settings

<figure><img src="https://3604734571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPaz8tFKqEd6volXC5G4B%2Fuploads%2FGvGN6M2vTgkgmEdfieNv%2Fimage.png?alt=media&amp;token=ce3bcafe-d3b9-4072-b4f0-6a0d3ec7b9f2" alt=""><figcaption></figcaption></figure>

Following code snippet is used by PaymentGateway in order to open payment application:

```java
Intent sendIntentSettingsTxn = new Intent();
sendIntentSettingsTxn.setPackage(tag);
sendIntentSettingsTxn.setAction(getResources().getString(R.string.Settings_Action)); //Settings_Action="Settings_Action"
sendIntentSettingsTxn.setType("text/plain");
startActivityForResult(sendIntentSettingsTxn, getResources().getInteger(R.integer.Settings_Request_Code)); //Settings_Request_Code=24
```

```java
Intent resultIntent = new Intent();
Bundle bundle = new Bundle();
bundle.putInt("ResponseCode",responseCode);
resultIntent.putExtras(bundle);
setResult(Activity.RESULT_OK,resultIntent); //Settings_Request_Code=24
finish();
```

**responseCode** : Return of the pos settings request.

#### **2.3.1 Manifest Modifications**

To be able to get data from payment gateway, there should be intent filter like below in related class.

```xml
<activity android:name=".SettingsActivity">
    <intent-filter>
        <action android:name="Settings_Action" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>
```

After the pos settings process, the payment application should send the result.

### 2.4. Batch Close

<figure><img src="https://3604734571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPaz8tFKqEd6volXC5G4B%2Fuploads%2FJRABUEapuTaisZfyCSBs%2Fimage.png?alt=media&amp;token=6e21b5b8-fae7-4ccb-aa00-b9413f6d17c2" alt=""><figcaption></figcaption></figure>

Following code snippet is used by PaymentGateway in order to open payment application:

```java
Intent sendIntentPosTxn = new Intent();
sendIntentPosTxn.setPackage(packages.get(i));
sendIntentPosTxn.setAction(getResources().getString(R.string.BatchClose_Action)); //BatchClose_Action="BatchClose_Action"
sendIntentPosTxn.setType("text/plain");
startActivityForResult(sendIntentPosTxn, getResources().getInteger(R.integer.BatchClose_Request_Code)); //BatchClose_Request_Code=25
```

```java
Intent resultIntent = new Intent();
Bundle bundle = new Bundle();
bundle.putInt("ResponseCode",responseCode);
resultIntent.putExtras(bundle);
setResult(Activity.RESULT_OK,resultIntent); //BatchClose_Request_Code=25
finish();
```

**responseCode** : Return of the pos settings request.

#### **2.4.1 Manifest Modifications**

To be able to get data from payment gateway, there should be intent filter like below in related class.

```xml
<activity android:name=".BatchCloseActivity">
    <intent-filter>
        <action android:name="BatchClose_Action" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>
```

After the batch close process, the payment application should send the result.

### 2.5. Parameter

Following code snippet is used by PaymentGateway in order to open payment application:

```java
	Intent sendIntentSettingsTxn = new Intent();
	sendIntentSettingsTxn.setPackage(data.getPackage());
	sendIntentSettingsTxn.setAction(getResources().getString(R.string.Parameter_Action)); //Parameter_Action="Parameter_Action"
	sendIntentSettingsTxn.setType("text/plain");
	startActivityForResult(sendIntentSettingsTxn, getResources().getInteger(R.integer.Parameter_Request_Code)); //Parameter_Request_Code=16
```

```java
Intent resultIntent = new Intent();
Bundle bundle = new Bundle();
bundle.putInt("ResponseCode",responseCode);
resultIntent.putExtras(bundle);
setResult(Activity.RESULT_OK,resultIntent); //Parameter_Request_Code=16
finish();
```

**responseCode** : Return of the pos settings request.

#### **2.5.1 Manifest Modifications**

To be able to get data from payment gateway, there should be intent filter like below in related class.

```xml
<activity android:name=".ParameterActivity">
    <intent-filter>
        <action android:name="Parameter_Action" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>
```

After the parameter update process, the payment application should send the result.

### 2.6. Power Cut Inquiry

If there has been a power cut during a sale transaction, transaction is inquired after device reboot. In order to receive inquiry and return transaction information, a broadcast receiver must be registered in the Android manifest file with action "check\_sale" like below:

```xml
<receiver android:name=".receivers.CheckSaleReceiver">
    <intent-filter>
        <action android:name="check_sale" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>
```

When inquiry broadcast is received, in the broadcast receiver's onReceive() method, if transaction is successful, transaction info must be returned in a bundle like below.

```java
   @Override
    public void onReceive(Context context, Intent intent) {
        if (intent.hasExtra("UUID")) {
            String uuid = intent.getExtras().getString("UUID");
            ...
                //check if a successful transaction with uuid exists
            ...
            Intent resultIntent = new Intent();
            if (transaction != null) {
                Bundle bundle = new Bundle();
                bundle.putInt("ResponseCode", ResponseCode.SUCCESS.ordinal());
                bundle.putInt("Amount", ...);
                bundle.putString("customerSlipData", ...);
                bundle.putString("merchantSlipData", ...);
                bundle.putInt("BatchNo", ...);
                bundle.putInt("TxnNo", ...);
                bundle.putBoolean("IsSlip", true);
                resultIntent.putExtras(bundle);
            }

            resultIntent.setAction("check_sale_result");
            resultIntent.setPackage("com.tokeninc.sardis.paymentgateway");
            context.sendBroadcast(resultIntent);
        }
    }
```

If you are using SQLite database to store transactions, you should configure your database to insert record instantly when a transaction completed in case of a power cut scenario. <https://www.sqlite.org/pragma.html#pragma\\_synchronous>

To do this, in your SQLiteOpenHelper class, override onConfigure() method and add the following code:

```java
    @Override
    public void onConfigure(SQLiteDatabase db) {
        db.execSQL("PRAGMA synchronous = 2");
    }
```

Following code snippet is used by PaymentGateway in order to check the payment, if there is a power cut PaymentGateway checks for the last sale result then returns UUID to ask for the result of the last sale status.

```java
registerReceiver(receiver, new IntentFilter("check_sale_result"));
Intent intent = new Intent("check_sale");
intent.setPackage(packageName);
intent.putExtra("UUID", uuid);
sendBroadcast(intent);
```

### 2.7. Manual App Activation

Let's say some operator needs to install your application manually and doesn't have a chance to send remote activation process. For that kind of situations, please use function setBankParams at&#x20;

{% file src="/files/YoZnonyTxJ48fqcpy7pD" %}
DeviceInfo.zip
{% endfile %}

<mark style="color:red;">**Important Note:**</mark> If you don't implement this function, your application can't be activated and it can't seen in ATMS. Therefore you couldn't see your applications on POS transactions and sale menu! You can read [Pos Settings on the Template Banking app](https://developer.tokeninc.com/token-developer-portal-1/v/payment-service/template-banking-app#id-3.1.-pos-settings) for more information.&#x20;

```java
DeviceInfo deviceInfo = new DeviceInfo(context);
deviceInfo.setAppParams(
    object : DeviceInfoAppParamsSetterHandler {
        override fun onReturn(result: Boolean) {
            Log.i("RESULT", result.toString())
        }
    },
    "TERMINAL_ID", "MERCHANT_ID",
)
```

Our UIComponents library provides components such as **ListMenuFragment**, **InfoDialog**, **InputListFragment** and **NumPadDialog** [which are explained here.](https://developer.tokeninc.com/token-developer-portal-1/payment-service/payment-services/ui-components.md)

## **3. Contactless Card Read**

#### Import CTOS Lib

{% file src="/files/OB06CvphQdYpGL4esFeD" %}

The `implementation` dependency should be added to the `app/build.gradle` file.

```kotlin
dependencies {
    implementation(files("libs/ctos_0.0.12.jar"))
}
```

#### Read Card API's

**Contactless**\
Contactless APIs are available in the attached document.

{% file src="/files/pSX5SyM2ALxHYcXjbEvR" %}
