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