# Intent Parameters

This reference page lists all the input parameters (Intent "extras") you can use when communicating with the Tap on Phone application.

You must pass these parameters using the `putExtra()` method when building your `Intent` objects. The required parameters vary depending on the action you are performing (such as initializing the POS, processing a payment, or broadcasting a request).

## Authentication and Session Parameters

These parameters manage user identity, terminal linking, and Single Sign-On (SSO) authorization. They are mandatory for almost all operations, including initializations, transactions, and background attestations.

| Parameter Name | Data Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `userId` | Int | Yes | Your system's technical identifier for the current user/merchant. |
| `userToken` | String | Yes | The secure authentication token for the user. The Tap on Phone backend sends this token to your SSO endpoint to authorize the operation. |
| `merchantId` | Int | Yes | The unique Tap to Pay ID representing the merchant business. You receive this identifier during the merchant onboarding process. |
| `operationMetadata` | String | Conditional | A serialized JSON string required for SSO authorization. **It must contain your `ClientID`** (e.g., `{"ClientID":"your-client-id"}`). Required for initialization, refunds, and cancellations. |

## Transaction Parameters

You pass these parameters to the `POSActivity` when initiating financial operations.

| Parameter Name | Data Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `transactionType` | String | Yes | Defines the operation. Accepted values: `PURCHASE`, `REFUND`, `CANCEL`, `PREAUTH`, `WITHDRAW`. |
| `amount` | Long | Yes | The total amount of the transaction in **cents** (e.g., pass `1200` for \$12.00). *Note: For purchases, this must include any tips.* |
| `tip` | Long | No | The tip amount in **cents**. This is strictly metadata. The application does **not** add this value to the `amount` automatically. |
| `originalTransaction` | Int | Conditional | The Tap on Phone transaction ID of the original payment. **Required only** when the `transactionType` is `REFUND` or `CANCEL`. |
| `paymentMode` | String | No | Specifies the payment method. Defaults to `Card`. Accepted values: `Card`, `Link` (if supported by your merchant configuration). |
| `externalTransactionReference` | String | No | Your internal system's reference ID for this order. If provided, the application attaches this string to the transaction receipt. |
| `acquirerMetadata` | String | No | A serialized string attached to the transaction data and forwarded to the payment acquirer. You can use this for advanced reporting or fraud prevention logic agreed upon with your gateway. |

## User Interface and Behavior Parameters

You can use these parameters to modify how the Tap on Phone payment screen behaves and appears to the user.

| Parameter Name | Data Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `locale` | String | No | Forces a specific language for the payment screen. Format as `LANGUAGE`, `LANGUAGE_COUNTRY`, or `LANGUAGE-COUNTRY` (e.g., `en_US`, `fr_FR`). Defaults to English if the requested language is unsupported. |
| `transitionAuto` | Boolean | No | If `true`, the Tap on Phone application automatically transitions and returns control to your application immediately after the transaction finishes. If omitted or `false`, it retains its default manual closure behavior. |

## Broadcast Parameters

You use these parameters when sending asynchronous Android Broadcasts (e.g., to check status, force attestation, or query past transactions).

| Parameter Name | Data Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `TransactionId` | String | Conditional | The UUID of the transaction you want to check. **Required only** when sending a `TRANSACTION_STATUS_BROADCAST`. |
| `ResponseAction` | String | No | A custom action name you define. The Tap on Phone application will emit its response broadcast using this exact string instead of its default action name. |