Tip-Recipient Linking
The tip-recipient linking flow lets a staff member connect their OpenApp account to their POS-side tipRecipientId. Once linked and KYC-confirmed, tips attributed to that tipRecipientId are routed directly to the staff member's OpenApp wallet instead of going to merchant settlement.
The POS is responsible for collecting the phone number a staff member wants to link. How the POS presents this to the user is its own concern.
Endpoints used in this flow:
| Endpoint | Direction | Purpose |
|---|---|---|
GET /tip-recipients | POS -> OpenApp | Retrieve the full roster of tip-recipient records for the location. |
GET /tip-recipients/:id | POS -> OpenApp | Retrieve a single tip-recipient record, including current status. |
PUT /tip-recipients/:id | POS -> OpenApp | Upsert a tip-recipient record and initiate account linking. Request body: PutTipRecipientRequest. Response: LinkTipRecipientResponse. |
Reading the roster
The POS may fetch the current roster at any time to populate a staff picker or verify records.
GET /tip-recipients - response: array of TipRecipient.
GET /tip-recipients/:id - response: single TipRecipient, or HTTP 404 if no record exists for the given identifier.
Linking submission
The POS sends PUT /tip-recipients/:id with the staff member's phone number and display name. This is an upsert: if the tip-recipient record does not yet exist OpenApp creates it; if it exists the display name is updated. OpenApp then stores the association in PENDING state and handles the rest of the flow.
See PutTipRecipientRequest for the full request body reference.
Checking link status
The POS can surface the status to the staff member - for example, showing a Pending badge that updates to Connected when the staff member has confirmed.
When status is PENDING, TipRecipient.expiresAt carries the deadline by which the staff member must complete the process. If they do not confirm before that time, the pending submission is silently discarded. The POS must submit a new PUT /tip-recipients/:id to start over.
See Link status for the full status vocabulary.
Unlinking a tipRecipientId from an OpenApp account is done by the staff member directly in the OpenApp app. There is no POS-side unlink endpoint.