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 without authentication. Send appName, callbackUrl, and at least one supported type: coupon, loyalty, status, or points.

   {
     "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:

   tapcoupon://complete-session?token=YOUR_SESSION_TOKEN
   

   TapCoupon fetches metadata through GET /payment-sessions//info, 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/ 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 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.