> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lab4pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Android App2App Integration

### Package name

```text theme={null}
// Production
com.lab4pay.pos

// Sandbox
com.lab4pay.pos.staging
```

<Columns cols={2}>
  <Card title="Charge" icon="credit-card" href="#charge-intent-contract">
    Generating or applying a payment using any card or digital method.
  </Card>

  <Card title="Revert" icon="arrow-rotate-left" href="#revert-intent-contract">
    Reversing a transaction, returning the money to the original account.
  </Card>

  <Card title="Refund" icon="cruzeiro-sign" href="#refund-intent-contract">
    Refund a related transaction, returning the money to the original account.
  </Card>

  <Card title="Independent refund" icon="cruzeiro-sign" href="#independent-refund-intent-contract">
    Refund an unrelated transaction, returning the money to tapped card.
  </Card>
</Columns>

## High-level flow

1. **Client’s app** constructs an explicit `Intent` targeting **Payment app** and specifies the desired action.
2. **Client’s app** launches the `Intent` with `registerForActivityResult(StartActivityForResult)`.
3. The user pays (or cancels).
4. **Payment app** returns a result `Intent` with details via `setResult(...)` and `finish()`.
5. **Client’s app** finalizes the order.

## Charge Intent Contract

### Request action

`com.lab4pay.pos.CHARGE`

### Request parameters

| Name                   | Type      | Example      | Notes                                                                     |
| ---------------------- | --------- | ------------ | ------------------------------------------------------------------------- |
| payConnectIntegratorId | `String`  | 9e6d06fe0322 | Your Integrator ID. For reference see the **Integrator Registry** section |
| payConnectId           | `String`  | 350344d0718b | Pay-Connect ID returned from **Pairing** section                          |
| amount                 | `Integer` | 2350         | The amount of the payment, in cents                                       |
| clientTransactionId    | `String`  | ref-49152    | Unique per payment attempt                                                |

### Response

* **Result codes:**
  * `Activity.RESULT_OK` -> The payment app completed normally and returned a valid result Intent. Additional details are provided in the Intent extras.
  * `Activity.RESULT_CANCELED` -> Payment flow ended unexpectedly (user exited early or app failed before returning a result). No Intent extras are available.
* **Data:** An `Intent` with **Response extras**

### Response extras

| Name                | Type      | Required             | Notes                                                                |
| ------------------- | --------- | -------------------- | -------------------------------------------------------------------- |
| transactionId       | `String`  | Yes - When `SUCCESS` | Our unique transaction reference                                     |
| clientTransactionId | `String`  | Yes                  | Echoed from original request                                         |
| paymentMethod       | `String`  | Yes - When `SUCCESS` | e.g., `CARD`, `MBILLS`, `VALU`                                       |
| paymentOption       | `String`  | No                   | Depends on payment method. e.g., `VISA`, `MASTERCARD`, `BTC`, `USDT` |
| amount              | `Integer` | Yes - When `SUCCESS` | The amount of the payment, in cents                                  |
| tipAmount           | `Integer` | Yes - When provided  | The tip amount of the payment, in cents                              |
| currency            | `String`  | Yes                  | Currency format ISO 4217                                             |
| status              | `String`  | Yes                  | `SUCCESS` \| `CANCELED` \| `FAILED`                                  |

## Revert Intent Contract

### Request action

`com.lab4pay.pos.REVERT`

### Request parameters

| Name                   | Type     | Example      | Notes                                                                     |
| :--------------------- | :------- | :----------- | :------------------------------------------------------------------------ |
| payConnectIntegratorId | `String` | 9e6d06fe0322 | Your Integrator ID. For reference see the **Integrator Registry** section |
| payConnectId           | `String` | 350344d0718b | Pay-Connect ID returned from **Pairing** section                          |
| transactionId          | `String` | 41dTf452a3b2 | The `CHARGE` transaction ID returned in `transactionId`                   |

<Note>
  Only the most recent `SUCCESS` transaction performed on the terminal can be reverted.
</Note>

<Note>
  Reverts are only available for certain payment methods.
</Note>

### Response

* **Result codes:**
  * `Activity.RESULT_OK` -> The payment app completed normally and returned a valid result Intent. Additional details are provided in the Intent extras.
  * `Activity.RESULT_CANCELED` -> Payment flow ended unexpectedly (user exited early or app failed before returning a result). No Intent extras are available.
* **Data:** An `Intent` with **Response extras**

### Response extras

| Name          | Type     | Required | Notes                        |
| ------------- | -------- | -------- | ---------------------------- |
| transactionId | `String` | Yes      | Echoed from original request |
| status        | `String` | Yes      | `SUCCESS` \| `FAILED`        |

## Refund Intent Contract

### Request action

`com.lab4pay.pos.REFUND`

### Request parameters

| Name                   | Type      | Example      | Notes                                                                     |
| :--------------------- | :-------- | :----------- | :------------------------------------------------------------------------ |
| payConnectIntegratorId | `String`  | 9e6d06fe0322 | Your Integrator ID. For reference see the **Integrator Registry** section |
| payConnectId           | `String`  | 350344d0718b | Pay-Connect ID returned from **Pairing** section                          |
| transactionId          | `String`  | 41dTf452a3b2 | The `CHARGE` transaction ID returned in `transactionId`                   |
| clientTransactionId    | `String`  | ref-49152    | Unique per refund attempt                                                 |
| amount                 | `Integer` | 2350         | The amount of the refund, in cents                                        |

<Note>
  Only `SUCCESS` charge transactions can be refunded.
</Note>

<Note>
  Refund amount must not exceed the remaining refundable amount.
</Note>

<Note>
  Refunds are only available for supported payment methods.
</Note>

### Response

* **Result codes:**
  * `Activity.RESULT_OK` -> The payment app completed normally and returned a valid result Intent. Additional details are provided in the Intent extras.
  * `Activity.RESULT_CANCELED` -> Payment flow ended unexpectedly (user exited early or app failed before returning a result). No Intent extras are available.
* **Data:** An `Intent` with **Response extras**

### Response extras

| Name                | Type      | Required             | Notes                                                                |
| ------------------- | --------- | -------------------- | -------------------------------------------------------------------- |
| transactionId       | `String`  | Yes - When `SUCCESS` | Our unique transaction reference                                     |
| clientTransactionId | `String`  | Yes                  | Echoed from original request                                         |
| paymentMethod       | `String`  | Yes - When `SUCCESS` | e.g., `CARD`, `MBILLS`, `VALU`                                       |
| paymentOption       | `String`  | No                   | Depends on payment method. e.g., `VISA`, `MASTERCARD`, `BTC`, `USDT` |
| amount              | `Integer` | Yes - When `SUCCESS` | The amount of the payment, in cents                                  |
| currency            | `String`  | Yes                  | Currency format ISO 4217                                             |
| status              | `String`  | Yes                  | `SUCCESS` \| `CANCELED` \| `FAILED`                                  |

## Independent Refund Intent Contract

### Request action

`com.lab4pay.pos.INDEPENDENT_REFUND`

### Request parameters

| Name                   | Type      | Example      | Notes                                                                     |
| :--------------------- | :-------- | :----------- | :------------------------------------------------------------------------ |
| payConnectIntegratorId | `String`  | 9e6d06fe0322 | Your Integrator ID. For reference see the **Integrator Registry** section |
| payConnectId           | `String`  | 350344d0718b | Pay-Connect ID returned from **Pairing** section                          |
| clientTransactionId    | `String`  | ref-49152    | Unique per refund attempt                                                 |
| amount                 | `Integer` | 2350         | The amount of the refund, in cents                                        |

<Note>
  Independent refunds are not linked to a previous charge transaction.
</Note>

<Note>
  Independent refunds require `CARD` payment method support on the terminal.
</Note>

### Response

* **Result codes:**
  * `Activity.RESULT_OK` -> The payment app completed normally and returned a valid result Intent. Additional details are provided in the Intent extras.
  * `Activity.RESULT_CANCELED` -> Payment flow ended unexpectedly (user exited early or app failed before returning a result). No Intent extras are available.
* **Data:** An `Intent` with **Response extras**

### Response extras

| Name                | Type      | Required             | Notes                                                 |
| ------------------- | --------- | -------------------- | ----------------------------------------------------- |
| transactionId       | `String`  | Yes - When `SUCCESS` | Our unique transaction reference                      |
| clientTransactionId | `String`  | Yes                  | Echoed from original request                          |
| paymentMethod       | `String`  | Yes - When `SUCCESS` | Only `CARD` payment method                            |
| paymentOption       | `String`  | No                   | Depends on payment method. e.g., `VISA`, `MASTERCARD` |
| amount              | `Integer` | Yes - When `SUCCESS` | The amount of the payment, in cents                   |
| currency            | `String`  | Yes                  | Currency format ISO 4217                              |
| status              | `String`  | Yes                  | `SUCCESS` \| `CANCELED` \| `FAILED`                   |

## Pay-Connect OTP Intent Contract

### Request action

`com.lab4pay.pos.PAY_CONNECT_OTP`

### Request parameters

| Name                   | Type     | Example      | Notes                                                                     |
| :--------------------- | :------- | :----------- | :------------------------------------------------------------------------ |
| payConnectIntegratorId | `String` | 9e6d06fe0322 | Your Integrator ID. For reference see the **Integrator Registry** section |

<Note>
  The terminal must not be already paired with Pay-Connect.
</Note>

### Response

* **Result codes:**
  * `Activity.RESULT_OK` -> The payment app completed normally and returned a valid result Intent. Additional details are provided in the Intent extras.
  * `Activity.RESULT_CANCELED` -> Payment flow ended unexpectedly (user exited early or app failed before returning a result). No Intent extras are available.
* **Data:** An `Intent` with **Response extras**

### Response extras

| Name | Type     | Required             | Notes                                     |
| ---- | -------- | -------------------- | ----------------------------------------- |
| otp  | `String` | Yes - When `SUCCESS` | OTP used for Pay-Connect terminal pairing |

## Example: Android Intent

```kotlin theme={null}
class PaymentActivity : AppCompatActivity() {

    private const val TAG = "PaymentActivity"

    private val chargeLauncher =
        registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
            handleChargeResult(result)
        }

    private fun launchCharge() {
        val intent = Intent("com.lab4pay.pos.CHARGE").apply {
            setPackage("com.lab4pay.pos")
            putExtra("amount", 2350)
            putExtra("clientTransactionId", "ref-49152")
        }
        chargeLauncher.launch(intent)
    }

    private fun handleChargeResult(result: ActivityResult) {
        when (result.resultCode) {
            Activity.RESULT_OK -> {
                val data = result.data ?: return
                val status = data.getStringExtra("status")
                val clientTransactionId = data.getStringExtra("clientTransactionId")

                when (status) {
                    "SUCCESS" -> {
                        val transactionId = data.getStringExtra("transactionId")
                        val paymentMethod = data.getStringExtra("paymentMethod")
                        val paymentOption = data.getStringExtra("paymentOption")
                        val amount = data.getIntExtra("amount", 0)
                        val tipAmount = data.getIntExtra("tipAmount", 0)
                        val currency = data.getStringExtra("currency")

                        Log.i(TAG, "Payment successful: id=$transactionId, amount=$amount $currency, method=$paymentMethod, ref=$clientTransactionId, ts=$timestamp")
                        // finalize order and update backend
                    }

                    "FAILED" -> {
                        Log.e(TAG, "Payment failed for ref=$clientTransactionId")
                        // show failure message or retry
                    }

                    "CANCELED" -> {
                        Log.w(TAG, "Payment canceled by user: ref=$clientTransactionId")
                        // handle user cancellation
                    }

                    else -> Log.e(TAG, "Unknown status: $status")
                }
            }

            Activity.RESULT_CANCELED -> {
                Log.w(TAG, "Payment flow aborted. No result Intent returned.")
                // allow retry or mark as incomplete
            }

            else -> Log.w(TAG, "Unexpected resultCode: ${result.resultCode}")
        }
    }
}
```