Wallet API: Stripe Connect Status and Payout Management

The /wallet endpoint manages each employee's Stripe Express connected account - the mechanism by which tips are paid out to individual employees.

Get Wallet Status

GET /v2/wallet?environment=live
Authorization: Bearer <idToken>

Response

{
  "connected": true,
  "onboarded": true,
  "canReceivePayments": true,
  "canWithdraw": true,
  "stripeAccountId": "acct_xxxxxxxxxxxxxxxx",
  "stripeAccountEmail": "maria@hotel.com",
  "availableBalance": 125.50,
  "pendingBalance": 32.00,
  "currency": "usd",
  "requirementsDue": [],
  "pendingVerification": []
}

Status Flags

Flag	Meaning when true
`connected`	Stripe Express account created
`onboarded`	Identity and banking info submitted; Stripe has enabled charges and payouts
`canReceivePayments`	The account can accept incoming tip funds
`canWithdraw`	The account has a valid payout method (bank account linked)

If onboarded is false, check requirementsDue for the list of fields Stripe still needs (e.g., individual.address.city).

Start Wallet Onboarding

Creates the Stripe Express account (if it doesn't exist) and returns a Stripe-hosted onboarding URL.

POST /v2/wallet
Content-Type: application/json
Authorization: Bearer <idToken>

{
  "action": "connect",
  "returnUrl": "https://my.aplauso.io/wallet",
  "refreshUrl": "https://my.aplauso.io/wallet/refresh",
  "environment": "live"
}

Response

{
  "success": true,
  "onboardingUrl": "https://connect.stripe.com/setup/e/..."
}

Redirect the user to onboardingUrl. After completing the Stripe flow, Stripe redirects back to returnUrl. If the user abandons midway, Stripe redirects to refreshUrl.

Get Stripe Dashboard Login Link

Returns a time-limited link for the employee to access their personal Stripe Express dashboard.

POST /v2/wallet
Content-Type: application/json
Authorization: Bearer <idToken>

{
  "action": "loginLink",
  "environment": "live"
}

Response

{
  "success": true,
  "loginUrl": "https://connect.stripe.com/express/..."
}

Query Dividends (Wallet Balance Detail)

To get itemized dividend records making up the wallet balance, use the Dividends endpoint:

GET /v2/dividends?employeeId=emp_xxx&organizationId=org_xxx&environment=live
Authorization: Bearer <idToken>

Response

{
  "dividends": [ ... ],
  "total": 157.50,
  "pending": 32.00,
  "paid": 125.50,
  "count": 12
}

Stripe Environment

The wallet operates in the environment matching the environment parameter:

live uses real Stripe keys; real money moves.
sandbox uses Stripe test keys; no real money.

Never use a sandbox wallet for production tips and vice versa. Each environment stores a separate stripeAccountId.