Recipient Balances

Recipients can hold balances in PayStream and withdraw funds on demand. This enables gig workers to accumulate earnings and withdraw when convenient.

Tenant API (API Key Auth)

Credit Recipient Balance

POST /api/v1/recipients/:id/balance/credit

Credit funds to a recipient's balance instead of sending a direct payout.

curl -X POST https://api.paystream.fi/api/v1/recipients/rec_abc123/balance/credit \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Delivery earnings - Week 8",
    "idempotencyKey": "earnings-week8-rec_abc123"
  }'

Credits have a 24-hour settlement delay by default before becoming available for withdrawal.

Get Recipient Balance

GET /api/v1/recipients/:id/balance

{
  "data": {
    "availableBalance": 45000,
    "pendingBalance": 15000,
    "currency": "USD",
    "status": "active"
  }
}

Get Transaction History

GET /api/v1/recipients/:id/balance/transactions

Freeze Balance

POST /api/v1/recipients/:id/balance/freeze

Freeze a recipient's balance for compliance review. Prevents withdrawals.

Unfreeze Balance

POST /api/v1/recipients/:id/balance/unfreeze

Recipient Portal (Session Auth)

Recipients access their own balance via the recipient portal with session tokens.

Get My Balance

GET /api/portal/recipients/me/balance

Get My Transactions

GET /api/portal/recipients/me/balance/transactions

Get Payment Methods with Withdrawal Options

GET /api/portal/recipients/me/payment-methods

Returns the recipient's payment methods annotated with available withdrawal options and fees.

Request Withdrawal

POST /api/portal/recipients/me/withdrawals

curl -X POST https://api.paystream.fi/api/portal/recipients/me/withdrawals \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "paymentMethodId": "pm_abc123",
    "speed": "standard"
  }'

Field	Type	Description
amount	integer	Amount in cents
paymentMethodId	string	Payment method for withdrawal
speed	string	standard (free) or instant ($2.50 fee)

List Withdrawals

GET /api/portal/recipients/me/withdrawals

Get Withdrawal Details

GET /api/portal/recipients/me/withdrawals/:id

Cancel Withdrawal

POST /api/portal/recipients/me/withdrawals/:id/cancel

Only pending withdrawals can be cancelled.

Estimate Withdrawal Fee

POST /api/portal/recipients/me/withdrawals/estimate

curl -X POST https://api.paystream.fi/api/portal/recipients/me/withdrawals/estimate \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "speed": "instant"
  }'

Response:

{
  "data": {
    "amount": 25000,
    "fee": 250,
    "netAmount": 24750,
    "estimatedArrival": "~30 seconds",
    "speed": "instant"
  }
}