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

# Partner integration

> Hand off coupon, loyalty, points, and status operations to the TapCoupon app.

## Complete an operation on the POS device

Your app creates a short-lived session, opens TapCoupon on the same device, and reads the result after TapCoupon opens your callback URL. The employee authenticates and scans the card in TapCoupon.

**1. Create a session**

Call [POST /payment-sessions](https://tapcoupon.mintlify.site/api-reference/integration/create-session.md) without authentication. Send `appName`, `callbackUrl`, and at least one supported type: `coupon`, `loyalty`, `status`, or `points`.

```json theme={null}
{
  "appName": "Your POS",
  "callbackUrl": "yourpos://payment-complete",
  "supportedCardTypes": ["coupon", "loyalty", "status", "points"]
}
```

The response is `201` with a 32-character `token`. The session has a five-minute completion window. The creation request does not specify an amount; the employee enters it in TapCoupon.

**2. Open TapCoupon**

Open this deep link on the device where TapCoupon is installed:

```text theme={null}
tapcoupon://complete-session?token=YOUR_SESSION_TOKEN
```

TapCoupon fetches metadata through [GET /payment-sessions/{token}/info](https://tapcoupon.mintlify.site/api-reference/integration/get-info.md), using its API key and device id. This consumes one session read.

**3. Scan and confirm**

The employee completes an operation for a supported card type. The card request includes `sessionToken`; the backend checks session eligibility and records the card operation and session completion together. Unsupported types leave the session pending and return an error. A successful operation opens your callback URL with the session token appended as the `token` query parameter. Existing query parameters are preserved. For example, `yourpos://payment-complete?order=123` becomes `yourpos://payment-complete?order=123&token=YOUR_SESSION_TOKEN`.

**4. Read the result once**

Read `token` from the callback query parameters and restore the matching transaction context. From your callback handler, call [GET /payment-sessions/{token}](https://tapcoupon.mintlify.site/api-reference/integration/get-status.md) without authentication. Check `status: completed`, `cardType`, and the coupon `amount` if applicable. Points, status, and loyalty completions have `amount: null`.

Only confirm an operation after you have verified the stored result. Store the result in your app so repeated callbacks do not trigger another session read or fulfillment.

## Android deep link behavior

On Android, callback handling depends on the receiving activity and its `android:launchMode` in `AndroidManifest.xml`. A deep link may open another app instance. Configure your activity for your app's navigation flow and restore transaction context from the callback token instead of relying only on in-memory state.

The TapCoupon source repository includes a Flutter integration example in `partner_app_demo`, including session creation, deep-link handling, and result retrieval. Contact [support](mailto:hilfe@tapcoupon.at) for help adapting the demo.

## Read budget and expiry

A session has **two successful reads total**, shared between info and status. Pending status reads count too. The expected sequence is one TapCoupon info read and one callback status read. Avoid polling.

Missing or exhausted tokens return `410`. Info reads and new card operations reject expired sessions. Status reads can return a stored result after its deadline until MongoDB's asynchronous TTL cleanup removes the session, provided reads remain. Do not rely on that retention delay.

## Protect the handoff

The token grants access to the public status endpoint. Keep it private. Custom-scheme deep links can be intercepted by other apps; a callback alone is not proof of completion. Read and verify the stored result.

A `410` means the result is unavailable. It can follow exhausted reads or cleanup, and does not alone prove tampering. If you cannot verify completion, do not automatically mark the transaction successful. Check the card's history before asking the employee to repeat an operation.

The actual card operation always requires a valid API key, bound device id, and employee token. The session token does not grant card-write access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.