HeldSway

Payouts

Dashboard (UI)

Navigate to Sidebar → Payouts (/payouts).

Metric Meaning
Pending Amount Total commission ready to be paid
Pending Count Number of affiliates with pending payouts
Completed This Month Total paid out this calendar month
Pending Requests Number of payout requests awaiting action

Payout Methods by Plan:

Plan Methods
Nano PayPal (manual trigger)
Basic PayPal + Bank/ACH
Standard PayPal + Bank/ACH + Automated W9/W8 collection
Custom All above + Crypto + 1099 e-filing

Payout Status Lifecycle

Pending ──► Processing ──► Completed
         ╰──────────────►  Failed
From To Endpoint
pending processing POST /v1/payouts/{id}/processing
pending completed POST /v1/payouts/{id}/complete
pending failed POST /v1/payouts/{id}/fail
processing completed POST /v1/payouts/{id}/complete
processing failed POST /v1/payouts/{id}/fail

Payouts REST API

Endpoints:

Method Path Scope Description
GET /v1/payouts payouts:read List payouts (paginated)
GET /v1/payouts/stats payouts:read Aggregated statistics
GET /v1/payouts/requests payouts:read List affiliate payout requests
GET /v1/payouts/export payouts:read Download CSV export
GET /v1/payouts/{id} payouts:read Single payout detail
GET /v1/payouts/{id}/statement payouts:read Download PDF statement
POST /v1/payouts/{id}/processing payouts:write Mark as processing
POST /v1/payouts/{id}/complete payouts:write Mark as completed
POST /v1/payouts/{id}/fail payouts:write Mark as failed
POST /v1/payouts/bulk-processing payouts:write Bulk mark as processing
POST /v1/payouts/bulk-complete payouts:write Bulk mark as completed
POST /v1/payouts/requests/{id}/approve payouts:write Approve a payout request
POST /v1/payouts/requests/{id}/reject payouts:write Reject a payout request
GET /v1/settings/payouts settings:read Read payout configuration
PUT /v1/settings/payouts settings:write Update payout configuration

Get Payout Stats:

curl "https://api.heldsway.com/api//v1/payouts/stats" \
  -H "Authorization: Bearer <access_token>"

{
  "data": {
    "total_pending_amount": 1250.00,
    "total_pending_count": 5,
    "completed_this_month": 3400.00,
    "failed_count": 1,
    "pending_requests_count": 2
  }
}

Mark Payout as Completed:

curl -X POST "https://api.heldsway.com/api//v1/payouts/42/complete" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "TXN-12345", "notes": "Paid via bank transfer" }'

Approve a Payout Request:

curl -X POST "https://api.heldsway.com/api//v1/payouts/requests/10/approve" \
  -H "Authorization: Bearer <access_token>"

Update Payout Settings:

curl -X PUT "https://api.heldsway.com/api//v1/settings/payouts" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_frequency": "monthly",
    "payout_day": 1,
    "min_payout": 50,
    "allow_early_requests": true,
    "auto_create_payouts": true
  }'

Error Reference:

HTTP Code Description
401 UNAUTHORIZED Missing or invalid Bearer token
403 FORBIDDEN Token lacks required scope
404 NOT_FOUND Payout or request not found
409 INVALID_STATUS Invalid status transition attempted
422 VALIDATION_ERROR Request parameters failed validation
429 — Rate limit exceeded
← Business SettingsIntegration Checklist →