Balance & Funding

Manage your tenant balance and funding operations.

Get Balance Summary

GET /api/v1/balance/summary

Returns available, pending, and locked balances.

curl -X GET https://api.paystream.fi/api/v1/balance/summary \
  -H "Authorization: Bearer psk_test_xxx"

Response:

{
  "data": {
    "availableBalance": 100000,
    "pendingBalance": 50000,
    "lockedBalance": 25000,
    "currency": "USD"
  }
}

Top Up Balance

POST /api/v1/balance/topup

Fund your balance via ACH debit or RTP from a linked bank account.

curl -X POST https://api.paystream.fi/api/v1/balance/topup \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "fundingSourceId": "ba_123"
  }'

Request Body

Field	Type	Required	Description
amount	integer	Yes	Amount in cents
fundingSourceId	string	Yes	Funding source ID

Balance Transactions

GET /api/v1/balance/transactions

List all balance transactions (credits, debits, locks, settlements).

Query Parameters

Parameter	Type	Description
type	string	Filter: credit, debit, lock, unlock, settlement
limit	integer	Results per page (default: 50)
cursor	string	Pagination cursor

Auto-Funding

Configure automatic balance top-ups when your balance drops below a threshold.

Get Auto-Funding Config

GET /api/v1/balance/auto-funding/config

curl -X GET https://api.paystream.fi/api/v1/balance/auto-funding/config \
  -H "Authorization: Bearer psk_test_xxx"

Update Auto-Funding Config

POST /api/v1/balance/auto-funding/config

curl -X POST https://api.paystream.fi/api/v1/balance/auto-funding/config \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "lowBalanceThreshold": 50000,
    "fundingAmount": 200000,
    "fundingMethod": "ach_debit",
    "confirmationThreshold": 500000
  }'

Auto-Funding Fields

Field	Type	Description
enabled	boolean	Enable/disable auto-funding
lowBalanceThreshold	integer	Trigger when balance drops below (cents)
fundingAmount	integer	Amount to fund (cents)
fundingMethod	string	ach_debit or rtp
confirmationThreshold	integer	Require confirmation for amounts above this (cents). null to disable.

When confirmationThreshold is set and a funding amount exceeds it, PayStream sends a magic-link email for approval instead of processing immediately.

Funding Sources

Manage bank accounts linked for balance funding.

List Funding Sources

GET /api/v1/balance/funding-sources

curl -X GET https://api.paystream.fi/api/v1/balance/funding-sources \
  -H "Authorization: Bearer psk_test_xxx"

Add Funding Source

POST /api/v1/balance/funding-sources

Link a bank account for funding via Plaid or manual entry.

With Plaid (Recommended)

curl -X POST https://api.paystream.fi/api/v1/balance/funding-sources \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plaidProcessorToken": "processor-sandbox-xxxxxx",
    "plaidAccountId": "account-sandbox-xxxxxx",
    "accountHolderName": "Acme Corp"
  }'

Manual Bank Entry

curl -X POST https://api.paystream.fi/api/v1/balance/funding-sources/manual \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "4242424242",
    "routingNumber": "123456789",
    "accountHolderName": "Acme Corp",
    "accountHolderType": "business",
    "accountType": "checking"
  }'

Delete Funding Source

DELETE /api/v1/balance/funding-sources/:id

Funding History

GET /api/v1/funding/transactions

List historical funding transactions with status tracking.

curl -X GET https://api.paystream.fi/api/v1/funding/transactions \
  -H "Authorization: Bearer psk_test_xxx"

Funding Statuses

Status	Description
reserved	Funds reserved, awaiting processing
awaiting_confirmation	Large transfer pending magic-link approval
pending	Submitted to payment network
in_transit	Processing through banking system
completed	Funds received
failed	Transfer failed