Client Callback (Intent)

Overview

This document describes the current technical details of the Intent URL integration between the Ödeal application and partners. The integration enables payment transactions to be carried out through JSON data exchange.

Prerequisites

1. Profile Type Setting

The profile type of the user logged into the Ödeal application must be EXTERNAL_BASKET_WITH_APP (APP2APP).

Attention

Payments cannot be accepted without this setting.

2. Intent URL Definition and Registration Process

Sample URL Format:

https://www.samplejsonapp.ode.al

3. Manifest Settings

An Intent Filter must be added to the partner application's AndroidManifest.xml file. The launchMode value must be singleTop.

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:label="@string/app_name"
    android:launchMode="singleTop"
    android:theme="@style/Theme.MyApplication">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="www.samplejsonapp.ode.al"
            android:scheme="https" />
    </intent-filter>
</activity>

Integration Flow and Data Directions

Sending Method (Partner → Ödeal)

Step 1: Invoking the Ödeal Application

For a normal payment:

val intent = Intent().apply {
    action = Intent.ACTION_VIEW
    data = Uri.parse("https://basket.ode.al/basketReferanceCode")
    putExtra("isCancelled", false) // For normal payment
}
startActivity(intent)

Cancellation Flow

To initiate a cancellation, set the isCancelled extra value to true:

val intent = Intent().apply {
    action = Intent.ACTION_VIEW
    data = Uri.parse("https://basket.ode.al/basketReferanceCode")
    putExtra("isCancelled", true) // Initiates the cancellation flow
}
startActivity(intent)

Inside the Ödeal Application

Step 2: Receiving and Processing the Data (SplashActivity)

Extract the basketReferenceCode value from the URL. Check the isCancelled extra value to determine the flow.

boolean isCancelled = intent.getBooleanExtra("isCancelled", false);
if (isCancelled) {
    // Start the cancellation flow
} else {
    // Start the payment flow
}

Step 3: Retrieving the Basket Data

Using the received basketReferenceCode, the basket details are retrieved and the basket is populated.

Step 4: Payment or Cancellation Transaction

If isCancelled is true, the Ödeal application starts the cancellation process. Otherwise, the payment transaction proceeds.

Return Method (Ödeal → Partner)

Step 5: Preparing the Result Data

Successful Payment:

String intentUri = dataManager.getCloseAfterPayment();
intentUri += "?basketReferenceCode=" + dataManager.getBasketReferenceCode();
intentUri += "&reason=Payment received successfully";
intentUri += "&result=" + true;
paymentDataModel.setIntentUriForReturnApp(Uri.parse(intentUri));
intent = new Intent(Intent.ACTION_VIEW, paymentDataModel.getIntentUriForReturnApp());

Cancelled Payment:

String intentUri = dataManager.getCloseAfterPayment();
intentUri += "?basketReferenceCode=" + dataManager.getBasketReferenceCode();
intentUri += "&reason=Payment cancelled";
intentUri += "&result=" + false;
paymentDataModel.setIntentUriForReturnApp(Uri.parse(intentUri));
intent = new Intent(Intent.ACTION_VIEW, paymentDataModel.getIntentUriForReturnApp());

Step 6: Processing the Result in the Partner Application

Extract the relevant fields from the returned URI and use them as needed.

Summary of the Cancellation Flow

1- Initiating the Cancellation: The partner application sends an intent with isCancelled = true.
2- Processing: The Ödeal application detects this flag and starts the cancellation process.
3- Result: The cancellation result is returned via the intent URI, following the same pattern as the payment flow.

Important Points

1- Use isCancelled = true to initiate the cancellation flow
2- Use isCancelled = false for the normal payment flow (or omit it entirely)
3- Both flows return their results through the same intent URI mechanism
4- The result parameter in the return URI indicates success/failure status
5- This structure clearly documents both the payment and cancellation scenarios.