How to check pending payouts in Stripe?

How to Check Pending Payouts in Stripe

Stripe is a popular payment processing platform that allows businesses to manage transactions, subscriptions, and payouts. Checking pending payouts is essential for tracking your expected payments and financial planning. This comprehensive tutorial will guide you through various methods to check pending payouts in Stripe.

Step 1: Understanding Stripe Payouts

Before diving into checking pending payouts, it's important to understand what Stripe payouts are:

• Payouts represent transfers from your Stripe balance to your bank account.
• Pending payouts are scheduled transfers that haven't been deposited to your bank account yet.
• Stripe typically processes payouts on a daily, weekly, or monthly schedule, depending on your account settings.

Step 2: Accessing the Stripe Dashboard

The simplest way to check pending payouts is through the Stripe Dashboard:

• Go to https://dashboard.stripe.com/login
• Enter your credentials and login to your Stripe account
• Once logged in, you'll see your main dashboard with an overview of recent activity

Step 3: Navigate to the Payouts Section

From the Stripe Dashboard:

• Click on "Payouts" in the left sidebar menu
• This will display a list of all your payouts, including pending ones
• Pending payouts are typically labeled with a "Pending" status

Step 4: Filter Payouts to See Only Pending Ones

To focus only on pending payouts:

• In the Payouts section, look for the "Filter" option
• Click on "Status" and select "Pending"
• This will show only payouts that haven't been deposited to your bank account yet

Step 5: Checking Pending Payouts via Stripe API (Basic)

For developers who prefer programmatic access, Stripe offers a robust API. Here's a basic example using the Stripe API with Node.js:

const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');

async function listPendingPayouts() {
  try {
    const payouts = await stripe.payouts.list({
      status: 'pending',
      limit: 100
    });
    
    console.log('Pending Payouts:', payouts.data);
    return payouts.data;
  } catch (error) {
    console.error('Error fetching pending payouts:', error);
    throw error;
  }
}

listPendingPayouts();

Replace 'sk_test_YOUR_SECRET_KEY' with your actual Stripe secret key. Never expose your secret key in client-side code.

Step 6: Detailed Payout Information with Stripe API

To get more detailed information about pending payouts, including the transactions that make up each payout:

const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');

async function getPendingPayoutDetails() {
  try {
    // First, get all pending payouts
    const payouts = await stripe.payouts.list({
      status: 'pending',
      limit: 100
    });
    
    // For each payout, get its transactions
    const payoutDetails = await Promise.all(
      payouts.data.map(async (payout) => {
        const balanceTransactions = await stripe.balanceTransactions.list({
          payout: payout.id
        });
        
        return {
          payout: payout,
          transactions: balanceTransactions.data
        };
      })
    );
    
    console.log('Detailed Pending Payouts:', payoutDetails);
    return payoutDetails;
  } catch (error) {
    console.error('Error fetching payout details:', error);
    throw error;
  }
}

getPendingPayoutDetails();

Step 7: Using Stripe API with Python

For Python developers, here's how to check pending payouts:

import stripe

# Set your API key
stripe.api_key = "sk_test_YOUR_SECRET\_KEY"

def list_pending_payouts():
    try:
        # Retrieve pending payouts
        payouts = stripe.Payout.list(
            status="pending",
            limit=100
        )
        
        print("Pending Payouts:")
        for payout in payouts.data:
            print(f"ID: {payout.id}")
            print(f"Amount: {payout.amount / 100} {payout.currency.upper()}")
            print(f"Arrival Date: {payout.arrival\_date}")
            print("-------------------")
        
        return payouts.data
    except Exception as e:
        print(f"Error fetching pending payouts: {e}")
        raise e

list_pending_payouts()

Step 8: Checking Pending Payouts with cURL

If you prefer using cURL for API requests:

curl https://api.stripe.com/v1/payouts \\
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \\
  -d status=pending \\
  -d limit=25

Step 9: Setting Up Webhook Notifications for Payouts

To receive notifications when payout statuses change:

const express = require('express');
const bodyParser = require('body-parser');
const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');

const app = express();

// Use JSON parser for webhook requests
app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      'whsec_YOUR_WEBHOOK\_SECRET'
    );
  } catch (err) {
    console.log(`Webhook Error: ${err.message}`);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  if (event.type === 'payout.created') {
    const payout = event.data.object;
    console.log('New payout created:', payout);
  } else if (event.type === 'payout.paid') {
    const payout = event.data.object;
    console.log('Payout completed:', payout);
  } else if (event.type === 'payout.failed') {
    const payout = event.data.object;
    console.log('Payout failed:', payout);
  }

  // Return a 200 response to acknowledge receipt of the event
  res.json({received: true});
});

app.listen(3000, () => console.log('Running on port 3000'));

Remember to register your webhook endpoint in the Stripe Dashboard and replace 'whsec_YOUR_WEBHOOK_SECRET' with your actual webhook signing secret.

Step 10: Create a Scheduled Job to Monitor Pending Payouts

For ongoing monitoring, set up a scheduled job using Node.js and a scheduler like node-cron:

const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');
const cron = require('node-cron');
const nodemailer = require('nodemailer');

// Configure email transporter
const transporter = nodemailer.createTransport({
  service: 'gmail',
  auth: {
    user: '[email protected]',
    pass: 'your-email-password'
  }
});

// Schedule task to run daily at 9 AM
cron.schedule('0 9 _ _ \*', async () => {
  try {
    // Get pending payouts
    const payouts = await stripe.payouts.list({
      status: 'pending',
      limit: 100
    });
    
    if (payouts.data.length > 0) {
      // Create email content
      let emailContent = 'Pending Payouts Summary:\n\n';
      
      payouts.data.forEach(payout => {
        const amount = payout.amount / 100;
        const currency = payout.currency.toUpperCase();
        const arrivalDate = new Date(payout.arrival\_date \* 1000).toLocaleDateString();
        
        emailContent += `ID: ${payout.id}\n`;
        emailContent += `Amount: ${amount} ${currency}\n`;
        emailContent += `Expected Arrival: ${arrivalDate}\n`;
        emailContent += '-------------------\n';
      });
      
      // Send email notification
      await transporter.sendMail({
        from: '[email protected]',
        to: '[email protected]',
        subject: 'Stripe Pending Payouts Report',
        text: emailContent
      });
      
      console.log('Payouts report sent successfully');
    } else {
      console.log('No pending payouts found');
    }
  } catch (error) {
    console.error('Error in scheduled payout check:', error);
  }
});

console.log('Payout monitoring scheduled');

Step 11: Integrating Payout Checks into Your Application

If you have a custom dashboard for your business, you might want to integrate payout checking. Here's a React component example:

import React, { useState, useEffect } from 'react';
import axios from 'axios';

const PendingPayouts = () => {
  const [payouts, setPayouts] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchPayouts = async () => {
      try {
        // This should call your backend API that communicates with Stripe
        // Never expose your Stripe secret key in frontend code
        const response = await axios.get('/api/stripe/pending-payouts');
        setPayouts(response.data);
        setLoading(false);
      } catch (err) {
        setError('Failed to fetch pending payouts');
        setLoading(false);
        console.error(err);
      }
    };

    fetchPayouts();
  }, []);

  if (loading) return 
Loading pending payouts...
;
  if (error) return 
Error: {error}
;

  return (
    

      
Pending Payouts
      {payouts.length === 0 ? (
        
No pending payouts found
      ) : (
        
            {payouts.map(payout => (
              
            ))}
          

          

            

              
ID
              
Amount
              
Currency
              
Expected Arrival
            
          
          

                
{payout.id}
                
{(payout.amount / 100).toFixed(2)}
                
{payout.currency.toUpperCase()}
                
{new Date(payout.arrival\_date \* 1000).toLocaleDateString()}
              
        
      )}
    
  );
};

export default PendingPayouts;

This should be paired with a backend endpoint that communicates with Stripe.

Step 12: Troubleshooting Payout Issues

If you encounter issues with payouts or payout reporting:

• Check your Stripe account status to ensure it's in good standing
• Verify your bank account connection is valid
• Review any failed payouts and address the underlying issues
• Ensure your API keys are correct and have the appropriate permissions
• Check the Stripe status page at https://status.stripe.com for any service disruptions

Conclusion

Monitoring pending payouts in Stripe is crucial for maintaining visibility into your cash flow. Whether you prefer the user-friendly dashboard or programmatic API access, Stripe provides multiple ways to check your pending payouts. By implementing these methods, you can stay informed about when funds will be transferred to your bank account and plan your finances accordingly.