> For the complete documentation index, see [llms.txt](https://docs.sensepass.com/sensepay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sensepass.com/sensepay/developers/tap-to-pay-pos-integration.md).

# Tap to Pay: POS integration

This page explains how a POS app on an Android device starts a card payment with the **SensePass Tap to Pay** app and receives the result.

The POS app does not embed a SensePass SDK and does not hold SensePass or processor credentials. Those are set up once inside the SensePass Tap to Pay app on the device.

```mermaid
sequenceDiagram
    participant POS as POS app
    participant TTP as SensePass Tap to Pay app
    POS->>TTP: Intent PROCESS_TRANSACTION (amount, currency)
    Note over TTP: Customer taps the card on the device
    TTP-->>POS: Activity result SP_RESPONSE (JSON)
```

| Item                       | Value                                              |
| -------------------------- | -------------------------------------------------- |
| Interaction model          | Android implicit Intent + activity result          |
| Action                     | `com.sensepass.payment.action.PROCESS_TRANSACTION` |
| Contract version           | 1.0                                                |
| Supported service          | Payment (`SP_SVC_PAYMENT`)                         |
| Credentials in the POS app | None                                               |

The SensePass app owns the payment screen, SensePass transaction creation, card acceptance and reporting. The POS app only sends the amount and currency (and optional details) and handles the JSON result.

## Before you start

1. The SensePass Tap to Pay app is installed on the device (`applicationId`: `com.sensepass.ttp.app`).
2. The app was opened once and set up: SensePass credentials, Sandbox or Production, and card acceptance provider. See **Device setup (merchant)** below.
3. Your POS app runs on Android and can launch activities for a result.
4. If your POS app targets Android 11 or later, declare package visibility (step 1 below).

## Step 1: Declare visibility (Android 11+)

Without this, your app may not find the SensePass app. Add to your manifest:

```xml
<queries>
    <intent>
        <action android:name="com.sensepass.payment.action.PROCESS_TRANSACTION" />
    </intent>
</queries>
```

## Step 2: Build the request

Launch with `startActivityForResult` or the Activity Result API. All extras are strings and all are required.

| Extra             | Value                     | Description                                     |
| ----------------- | ------------------------- | ----------------------------------------------- |
| `SP_SERVICE_TYPE` | `SP_SVC_PAYMENT`          | Operation type                                  |
| `SP_REQUEST`      | JSON string               | Payment payload (below)                         |
| `SP_VERSION`      | `1.0`                     | Contract version (the major version must match) |
| `SP_SESSION_ID`   | Unique string per request | Correlation ID, returned in the response        |

Example `SP_REQUEST`:

```json
{
  "currency": "AUD",
  "amount": 1250,
  "reference": "order-1001",
  "timeoutSeconds": 120,
  "products": [
    {
      "name": "Coffee",
      "quantity": 1,
      "amount": 1250,
      "discount": 0,
      "vat": 0,
      "posIdentifier": "SKU-42"
    }
  ]
}
```

| Field                      | Required                   | Description                                                                                                                                |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `currency`                 | Yes                        | ISO 4217 code, for example `AUD` or `USD`. Must match the terminal's currency, or the processor rejects the request before a card is read. |
| `amount`                   | Yes                        | Total in minor units (A$12.50 = `1250`). A positive integer.                                                                               |
| `reference`                | No                         | Your order or sale ID.                                                                                                                     |
| `timeoutSeconds`           | No                         | Local timeout. Default `120`.                                                                                                              |
| `products`                 | No                         | Line items. Amounts should add up to `amount`: `(amount + vat - discount) * quantity`.                                                     |
| `products[].name`          | Yes, if `products` is sent | Item name                                                                                                                                  |
| `products[].quantity`      | No                         | Default `1`                                                                                                                                |
| `products[].amount`        | Yes, if `products` is sent | Unit price in minor units                                                                                                                  |
| `products[].discount`      | No                         | Discount per unit in minor units                                                                                                           |
| `products[].vat`           | No                         | VAT per unit in minor units                                                                                                                |
| `products[].posIdentifier` | No                         | Your SKU or line ID                                                                                                                        |

Example (Kotlin):

```kotlin
private val paymentLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result -> handlePaymentResult(result) }

fun startPayment(amountMinor: Long, currency: String, orderId: String) {
    val sessionId = UUID.randomUUID().toString()
    // Save sessionId with the sale. Your process can be killed while the payment app is in front.
    val request = JSONObject().apply {
        put("currency", currency)
        put("amount", amountMinor)
        put("reference", orderId)
        put("timeoutSeconds", 120)
    }
    val intent = Intent("com.sensepass.payment.action.PROCESS_TRANSACTION").apply {
        putExtra("SP_SERVICE_TYPE", "SP_SVC_PAYMENT")
        putExtra("SP_REQUEST", request.toString())
        putExtra("SP_VERSION", "1.0")
        putExtra("SP_SESSION_ID", sessionId)
    }
    try {
        paymentLauncher.launch(intent)
    } catch (e: ActivityNotFoundException) {
        // The SensePass Tap to Pay app is not installed
    }
}
```

## Step 3: Read the result

The SensePass app returns exactly one activity result. Read these extras from `result.data`:

| Extra             | Description         |
| ----------------- | ------------------- |
| `SP_SERVICE_TYPE` | Same as the request |
| `SP_RESPONSE`     | JSON result (below) |
| `SP_VERSION`      | Contract version    |
| `SP_SESSION_ID`   | Same as the request |

{% hint style="warning" %}
**Important:** If `SP_RESPONSE` is missing (for example the process was killed), the result is unknown. Do not assume success or failure. Check the transaction status in your back office or in SensePass.
{% endhint %}

Success:

```json
{
  "result": "SP_RESULT_SUCCESS",
  "errorCondition": "SP_ERR_COND_NONE",
  "transactionNumber": "<SENSEPASS_TRANSACTION_ID>",
  "approvalId": "123456",
  "cardType": "VISA",
  "lastFourDigits": "4242",
  "cardMask": "XXXXXXXXXXXX4242",
  "currency": "AUD",
  "amount": 1250,
  "timestamp": "2026-08-04T10:15:00+10:00"
}
```

| Field               | Description                                  |
| ------------------- | -------------------------------------------- |
| `result`            | `SP_RESULT_SUCCESS`                          |
| `errorCondition`    | `SP_ERR_COND_NONE`                           |
| `transactionNumber` | SensePass transaction ID                     |
| `approvalId`        | Approval code, when available                |
| `cardType`          | Card brand, when available                   |
| `lastFourDigits`    | Last four digits of the card, when available |
| `cardMask`          | Masked card number, when available           |
| `currency`          | Currency of the authorization                |
| `amount`            | Authorized amount in minor units             |
| `timestamp`         | ISO 8601 timestamp                           |

Failure:

```json
{
  "result": "SP_RESULT_FAILURE",
  "errorCondition": "SP_ERR_COND_USER_CANCEL",
  "remark": "The payment was cancelled"
}
```

Example result handler:

```kotlin
fun handlePaymentResult(result: ActivityResult) {
    val data = result.data
    val responseJson = data?.getStringExtra("SP_RESPONSE")
    val sessionId = data?.getStringExtra("SP_SESSION_ID")
    if (responseJson == null) {
        // Unknown result: reconcile later
        return
    }
    // Check that sessionId matches the sale you started
    val response = JSONObject(responseJson)
    when (response.optString("result")) {
        "SP_RESULT_SUCCESS" -> {
            val tn = response.optString("transactionNumber")
            val auth = response.optString("approvalId")
            // Mark the sale as paid
        }
        else -> {
            val code = response.optString("errorCondition")
            val remark = response.optString("remark")
            // Show a message or retry, based on the code
        }
    }
}
```

## Error conditions

| `errorCondition`                      | Meaning                                                     | What the POS should do                      |
| ------------------------------------- | ----------------------------------------------------------- | ------------------------------------------- |
| `SP_ERR_COND_NONE`                    | Success                                                     | Complete the sale                           |
| `SP_ERR_COND_USER_CANCEL`             | Cancelled by the merchant or customer                       | Return to the cart; allow a retry           |
| `SP_ERR_COND_HOST_REFUSAL`            | Card declined by the processor                              | Offer another card or cancel                |
| `SP_ERR_COND_TRANSACTION_TIMEOUT`     | Timed out                                                   | Retry as a new payment                      |
| `SP_ERR_COND_NETWORK_ISSUE`           | SensePass API or network failure                            | Check the connection; retry                 |
| `SP_ERR_COND_BUSY`                    | Another payment is in progress                              | Wait; do not start another                  |
| `SP_ERR_COND_NOT_CONFIGURED`          | The SensePass app has no credentials                        | Open the SensePass app and set it up        |
| `SP_ERR_COND_READER_UNAVAILABLE`      | Card acceptance is not available                            | Check the SensePass app and processor setup |
| `SP_ERR_COND_INVALID_TRANSACTION_REQ` | Bad request (missing field, wrong currency, invalid amount) | Fix the request; do not retry it unchanged  |
| `SP_ERR_COND_VERSION_NOT_SUPPORTED`   | `SP_VERSION` not supported                                  | Update the POS app or the SensePass app     |
| `SP_ERR_COND_SERVICE_NOT_SUPPORTED`   | Unknown `SP_SERVICE_TYPE`                                   | Use `SP_SVC_PAYMENT` only (v1.0)            |
| `SP_ERR_COND_INTERNAL`                | Internal or reporting failure (see `remark`)                | Handle with care; you may need to reconcile |

## Integration rules

1. **One payment at a time.** Do not start a new payment until the previous result is known.
2. **Save `SP_SESSION_ID`.** The SensePass app comes to the front and your process can be killed. Save the session ID with the open sale and check it in the response.
3. **The currency must match the terminal.** For example, an AUD terminal rejects USD with `SP_ERR_COND_INVALID_TRANSACTION_REQ`.
4. **Amounts are always in minor units.** Never send decimal strings in `amount`.
5. **No credentials in the POS app.** Device and API keys and processor setup live only in the SensePass Tap to Pay app.
6. **A missing `SP_RESPONSE` is not a decline.** Treat it as unknown and reconcile.

## Scope of version 1.0

| Supported                            | Not in this version              |
| ------------------------------------ | -------------------------------- |
| Sale (`SP_SVC_PAYMENT`)              | Refund, void, reversal           |
| Activity-result request and response | Embedded SDK in the POS app      |
| Optional line items (`products`)     | Pre-authorization and completion |

Refunds and related operations may be added in a later contract version.

## Device setup (merchant)

The merchant does this once on the SensePass Tap to Pay app's setup screen. The POS app is not involved.

1. Enter the SensePass device ID or API key, and choose Sandbox or Production.
2. Choose the card acceptance provider: Fiserv or Worldline Tap on Mobile.
3. For Worldline: register the Tap on Mobile terminal to this app.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sensepass.com/sensepay/developers/tap-to-pay-pos-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
