Skip to content

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.

bash
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

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

bash
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"
  }'
FieldTypeDescription
amountintegerAmount in cents
paymentMethodIdstringPayment method for withdrawal
speedstringstandard (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

bash
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:

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

Released under the MIT License.