Team access in the app

A merchant can give other people access to their account with exactly the permissions they choose — for example someone who can only take payments with Tap to Pay and sees nothing else. The owner invites them on the web Team page; the person signs in to the app with their own login. Every permission is enforced on every request, so the app only has to pick the account, send one header, and show what the permissions allow.

After login: who can I act as?

text

GET /api/team/me
Authorization: Bearer mob_…

The response lists ownAccount (the login's own account, everything allowed) and memberships — each with accountUserId, accountName, businesses (only the businesses this person may act in — the owner can limit a member to some of them; businessIds is that limit, or null for all) and capabilities, the complete list of what this person may do there. Call it on every app start and after any 403; the owner can change permissions at any time.

Acting inside an account

Send the chosen account on every request, together with the usual token:

text

POST /api/terminal/tap-to-pay/record
Authorization: Bearer mob_…
x-team-account: <accountUserId>

Everything is then scoped to that account. Do not send the header when the user acts in their own account. Every action is recorded with the real person's identity, so the owner's activity log shows who did it.

Permissions

take_payments (Tap to Pay, virtual terminal, charge a saved card, payment links, receipts) · view_transactions · refunds (refunds, voids, disputes) · view_balances (dashboard money, balances, payouts, settlements) · view_customers · manage_customers · billing (invoices, subscriptions, products, plans) · view_reports · export_data · business_settings · manage_team · team_view · api_keys.

Use the list to decide which tabs and buttons exist. Without view_balances, do not call /api/finix/dashboard; make Tap to Pay the home screen. A person with only take_payments should see: pick business → Tap to Pay → charge → receipt.

Errors

text

HTTP 403
{ "success": false, "error": "Your team permissions don't include this. Ask the account owner.",
  "code": "team_capability_required", "capability": "view_balances" }

team_capability_required — the person lacks that permission: show a short message naming it, then refresh /api/team/me. team_business_denied — the merchantId sent is not one of the member's businesses: pick a business from that list. team_access_denied — no longer an active member of that account, or an owner-only endpoint: return to the account picker. Any endpoint not listed below refuses team members even if they are administrators.

What each permission unlocks

  • any active member: GET /api/merchants/my, GET /api/team/me
  • take_payments: /api/terminal/*, POST /api/finix/transfers, POST /api/customers/{id}/charge, POST /api/transactions/attempts, /api/payment-links, /api/receipts
  • view_transactions: GET /api/finix/transfers, GET /api/transactions, GET /api/activity, GET /api/disputes
  • refunds: POST /api/finix/transfers/{id}/reversals, POST /api/refunds, dispute accept, submit and evidence
  • view_balances: GET /api/finix/dashboard, GET /api/payouts, GET /api/settlements
  • view_customers / manage_customers: reads / writes under /api/customers
  • billing: /api/invoices, /api/subscriptions, /api/products, /api/pricing-tables, /api/arrangements
  • view_reports / export_data: GET /api/reports/data, /api/analytics; POST /api/reports/pdf, report schedules