Payout Processing

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/polarsource/polar/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Payout Process

​

Two-Step Process

​

Step 1: Transfer to Stripe Connect Account

1. Payout created in Polar
2. Funds transferred to your Stripe Connect account
3. Platform fees deducted
4. Payout transaction recorded

​

Step 2: Bank Transfer

1. Funds available in Stripe balance
2. Stripe payout triggered to your bank
3. Bank processes deposit
4. Payout marked as succeeded

​

Creating a Payout

​

Prerequisites

• Active account with payouts enabled
• Balance above minimum threshold
• No pending payout in progress
• Account not under review

​

Payout Estimation

const estimate = await polar.payouts.estimate({
  account_id: accountId
});

console.log(`Gross: $${estimate.gross_amount / 100}`);
console.log(`Fees: $${estimate.fees_amount / 100}`);
console.log(`Net: $${estimate.net_amount / 100}`);

​

Initiating a Payout

1. Navigate to Finance → Payouts
2. Click “Create Payout”
3. Review payout estimate
4. Confirm payout creation
5. Payout begins processing

​

Automatic Payout Creation

• Balance reaches minimum threshold
• Safety delay period has passed
• No pending payout exists

​

Payout Status Flow

​

Status Progression

Pending → In Transit → Succeeded
         ↓
       Failed → Retry
         ↓
      Canceled

​

Pending

• Payout created successfully
• Funds reserved from balance
• Transfer to Stripe initiated
• Waiting for Stripe confirmation

​

In Transit

• Transfer to Stripe completed
• Bank transfer initiated
• Funds en route to bank account
• Typically takes 2-7 business days

​

Succeeded

• Funds arrived in bank account
• Payout completed successfully
• Invoice available for download
• Transaction history updated

​

Failed

• Bank transfer unsuccessful
• Common reasons:
  • Invalid bank account details
  • Bank rejected transfer
  • Account closed
  • Currency restrictions

​

Canceled

• Payout manually canceled
• Funds returned to balance
• Reversal transaction created
• Can create new payout

​

Payout Attempts

​

Initial Attempt

• First try to transfer funds
• Uses full payout amount
• Creates attempt record

​

Retry Attempts

• Triggered if initial attempt fails
• May use adjusted amount
• Stripe has hidden payout rules
• Automatic retries for transient failures

​

Attempt Details

• Attempt ID
• Status (pending, succeeded, failed)
• Amount attempted
• Currency
• Failure reason (if failed)
• Timestamp

​

Fee Calculation

​

Platform Fees

Platform Fee = (Gross Amount × 0.04) + $0.40

​

Fee Deduction Timing

1. Payout created
2. Fee transactions generated
3. Credits applied first
4. Remaining fees deducted from balance

​

Fee Credits

• Credits applied automatically
• Reduces platform fees
• No action required
• Credit usage shown in transactions

​

Currency Conversion

​

Multi-Currency Payouts

1. Conversion rate determined by Stripe
2. Rate applied during transfer
3. Actual amount may vary slightly
4. Conversion fees may apply

​

Zero-Decimal Currencies

• Payout amounts rounded down
• Must be whole units (no cents)
• Remainder stays in balance
• Logged for transparency

​

Payout Invoices

​

Generating Invoices

1. Navigate to payout details
2. Click “Generate Invoice”
3. Optionally set custom invoice number
4. Invoice generated and stored

​

Invoice Requirements

• Payout must have succeeded
• Billing details configured
• Invoice number unique per account

​

Invoice Contents

• Invoice number (e.g., POLAR-0001)
• Billing entity details
• Fee breakdown
• Payment information
• Transaction summary

​

Downloading Invoices

const invoice = await polar.payouts.getInvoice(payoutId);
console.log(`Invoice URL: ${invoice.url}`);

​

Transaction Export

​

CSV Export

• All transactions included in payout
• Fee breakdown
• Order and subscription details
• Compatible with spreadsheet software

​

CSV Columns

• Date
• Payout ID
• Transaction ID
• Description
• Currency
• Amount
• Payout Total
• Account Currency
• Account Payout Total

​

Canceling Payouts

​

When You Can Cancel

• Status is Pending
• Transfer not yet completed
• Within cancellation window

​

Cancellation Process

1. Navigate to payout details
2. Click “Cancel Payout”
3. Confirm cancellation
4. Reversal transaction created
5. Funds returned to balance

​

Stripe Transfer Reversal

• Reversal initiated automatically
• Transfer reversed on Stripe
• Funds returned to Polar
• May take 1-3 business days

​

Payout Timing

​

Processing Time

• Transfer to Stripe: Immediate
• Stripe Processing: 1-2 business days
• Bank Transfer: 2-7 business days
• Total: 3-9 business days typically

​

Factors Affecting Timing

• Bank processing schedules
• Weekends and holidays
• Currency conversion
• First-time payout verification
• International transfers

​

Arrival Date

• Shown in payout details
• Updated if status changes
• Actual timing may vary
• Bank may delay slightly

​

Common Issues

​

Insufficient Balance Error

• Balance below minimum
• Recent refunds processed
• Payout fees exceed balance

​

Account Under Review

• Automated account review triggered
• Unusual activity detected
• Compliance requirements

​

Payouts Not Enabled

• Onboarding incomplete
• Bank details not verified
• Identity verification pending

​

Payout Amount Too Large

• Stripe limits for currency
• First payout restrictions
• Account limitations

​

Best Practices

​

Regular Payouts

• Process payouts consistently
• Don’t let balance accumulate excessively
• Monitor for failed attempts
• Keep bank details current

​

Invoice Management

• Generate invoices promptly
• Use sequential invoice numbers
• Store invoices securely
• Track for accounting

​

Balance Planning

• Maintain refund reserves
• Account for seasonal variations
• Plan for fee deductions
• Monitor minimum thresholds

​

API Integration

​

List Payouts

const payouts = await polar.payouts.list({
  account_id: accountId,
  status: ["succeeded", "pending"],
  page: 1,
  limit: 10
});

​

Get Payout Details

const payout = await polar.payouts.get(payoutId);
console.log(`Status: ${payout.status}`);
console.log(`Amount: $${payout.amount / 100}`);

​

Create Payout

const payout = await polar.payouts.create({
  account_id: accountId
});

​

Monitoring and Alerts

​

Webhook Events

• payout.created
• payout.invoice_generated
• Stripe payout status changes

​

Status Monitoring

• Check payout status regularly
• Set up alerting for failures
• Monitor arrival dates
• Track processing time

​

Next Steps

• Set up your Financial Account
• Monitor your Balance
• Review Fee Structure
• Understand Account Reviews