Syncing Stripe Failed Payments to Slack for Follow-up

Hey there, Darian here. Let’s talk about a silent revenue killer: failed payments. For a while, I had a weekly calendar reminder to log into Stripe, filter for failed charges, and manually export a list for our finance team. It felt productive, but in reality, I was wasting a couple of hours every week on a task a simple script could handle. That’s why I built this workflow. It pipes failed payment alerts directly into a Slack channel, turning a manual chore into an automated, real-time notification system. This frees up my time and helps the team follow up with customers immediately, which is a huge win for recovering revenue.

This guide will walk you through setting up the exact same system. It’s a straightforward process that will save you a ton of headache.

Prerequisites

Before we dive in, make sure you have the following ready:

• Stripe Account: You’ll need API access, specifically your secret key.
• Slack Workspace: You need permissions to create a new app and generate an Incoming Webhook URL.
• Python 3 Environment: A place to run our script.
• Basic Familiarity: A little comfort with Python and using environment variables will go a long way.

The Guide: Step-by-Step

Step 1: Create a Slack Incoming Webhook

First, we need a way to post messages to Slack programmatically. Slack’s Incoming Webhooks are perfect for this. They give you a unique URL that you can send a simple HTTP request to, and your message will appear in the designated channel.

1. Go to api.slack.com/apps and click “Create New App”.
2. Choose “From scratch”, give it a name like “Stripe Payment Alerts”, and select your workspace.
3. On the next screen, under “Add features and functionality”, select “Incoming Webhooks”.
4. Toggle the “Activate Incoming Webhooks” switch to “On”.
5. Click “Add New Webhook to Workspace” at the bottom. Choose the channel you want the alerts to post to (I recommend a dedicated channel like #finance-alerts) and click “Allow”.

Slack will generate a Webhook URL for you. It’ll look something like https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX. Copy this URL and keep it safe; it’s our first secret.

Step 2: Find Your Stripe Secret API Key

Next, we need to give our script permission to read data from your Stripe account. We’ll use your secret API key for this.

1. Log into your Stripe Dashboard.
2. Navigate to the “Developers” section in the left-hand menu, then click on “API keys”.
3. You’ll see a “Standard keys” section with a “Publishable key” and a “Secret key”. We need the Secret key.
4. Click “Reveal live key” to view it. Copy this key. This is our second secret, and it’s extremely sensitive. Never expose it in your client-side code or commit it to version control.

Step 3: Prepare the Python Environment

Now, let’s get our local setup in order. I’ll skip the standard virtual environment setup commands since you likely have your own workflow for that. The important part is to create a new project directory and activate a virtual environment within it.

Once your environment is active, you’ll need to install three Python libraries. You can do this with your package manager, for instance, by running: pip install stripe slack_sdk python-dotenv.

• stripe: The official Stripe Python library.
• slack_sdk: Slack’s official SDK for interacting with their APIs.
• python-dotenv: A handy tool for managing environment variables in a file.

Next, create two files in your project directory: config.env for our secrets and check_payments.py for our script’s logic.

In your config.env file, add your secrets like this:

STRIPE_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T000...

Step 4: Write the Python Script

This is where the magic happens. Open check_payments.py and let’s build the script. We’ll load our secrets, fetch failed charges from Stripe, format a message, and send it to Slack.

Here’s the complete code. I’ve added comments to explain each part.

import os
import stripe
from datetime import datetime, timedelta
from slack_sdk.webhook import WebhookClient
from dotenv import load_dotenv

# Load environment variables from config.env file
load_dotenv('config.env')

# --- Configuration ---
STRIPE_API_KEY = os.getenv("STRIPE_API_KEY")
SLACK_WEBHOOK_URL = os.getenv("SLACK_WEBHOOK_URL")

# --- Initialize API Clients ---
stripe.api_key = STRIPE_API_KEY
webhook = WebhookClient(SLACK_WEBHOOK_URL)

def get_failed_charges_since(hours_ago=24):
    """
    Fetches all failed Stripe charges from the last N hours.
    """
    if not STRIPE_API_KEY:
        print("Error: STRIPE_API_KEY not found in environment variables.")
        return []

    # Calculate the timestamp for the start of our search window
    start_time = datetime.utcnow() - timedelta(hours=hours_ago)
    start_timestamp = int(start_time.timestamp())

    try:
        # Fetch charge events that have failed
        failed_charges = stripe.Charge.list(
            created={'gte': start_timestamp},
            status='failed',
            limit=100  # Adjust limit based on expected volume
        )
        return failed_charges.data
    except Exception as e:
        print(f"Error fetching charges from Stripe: {e}")
        return []

def format_slack_message(charge):
    """
    Formats a single failed charge into a nice Slack message block.
    """
    # Convert amount from cents to dollars/euros etc.
    amount = f"{charge.amount / 100.0:.2f} {charge.currency.upper()}"
    customer_email = charge.billing_details.get('email', 'N/A')
    failure_message = charge.failure_message or "No specific reason provided."
    charge_link = f"https://dashboard.stripe.com/charges/{charge.id}"

    message = {
        "blocks": [
            {
                "type": "header",
                "text": {
                    "type": "plain_text",
                    "text": ":warning: Failed Stripe Payment"
                }
            },
            {
                "type": "section",
                "fields": [
                    {"type": "mrkdwn", "text": f"*Amount:* {amount}"},
                    {"type": "mrkdwn", "text": f"*Customer Email:* {customer_email}"},
                    {"type": "mrkdwn", "text": f"*Reason:* {failure_message}"},
                    {"type": "mrkdwn", "text": f"*Stripe Link:* <{charge_link}|View Charge>"}
                ]
            },
            {"type": "divider"}
        ]
    }
    return message

def send_to_slack(message_payload):
    """
    Sends the formatted message payload to the Slack webhook.
    """
    if not SLACK_WEBHOOK_URL:
        print("Error: SLACK_WEBHOOK_URL not found in environment variables.")
        return

    try:
        response = webhook.send(
            blocks=message_payload["blocks"]
        )
        if response.status_code != 200:
            print(f"Error sending to Slack: {response.status_code} {response.body}")
    except Exception as e:
        print(f"An exception occurred while sending to Slack: {e}")

# --- Main Execution ---
if __name__ == "__main__":
    print("Checking for failed payments...")
    failed_charges = get_failed_charges_since(hours_ago=24)

    if not failed_charges:
        print("No failed payments found in the last 24 hours.")
    else:
        print(f"Found {len(failed_charges)} failed payments. Sending to Slack...")
        for charge in failed_charges:
            slack_message = format_slack_message(charge)
            send_to_slack(slack_message)
        print("Done.")

Pro Tip: The script fetches charges from the last 24 hours. If you run this script once a day, this is perfect. If you run it weekly, you should change `hours_ago=24` to `hours_ago=168` (7 days * 24 hours). This prevents sending duplicate notifications for the same failed payment.

Step 5: Schedule the Script with Cron

A script is only useful if it runs automatically. On a Linux-based system, cron is the standard tool for this. We’ll set up a cron job to run our script once a day.

You can add a new job to your system’s scheduler. The command will look something like this. Be sure to use the path to your python executable and script file that is correct for your system.

0 2 * * * python3 /path/to/your/project/check_payments.py

This specific line means: “At 2:00 AM, every day of the month, every day of the week, run this script.” It’s a reliable way to ensure you get a daily digest of any payment issues.

Common Pitfalls

I’ve set this up a few times, and here are the places I usually stumble:

• Test vs. Live Keys: It’s easy to accidentally use your Stripe *test* key (sk_test_...) in production or vice-versa. Double-check that you’re using the `sk_live_…` key in your `config.env` for the real deal.
• Environment Variables Not Loaded: The script will fail silently if it can’t find your `config.env` file. Make sure you run the script from the same directory where your `config.env` is located, or provide an absolute path to it.
• Slack Webhook Permissions: If you create the webhook but forget to add it to a channel, or if the channel is private and the app isn’t invited, you’ll get errors. Always test the webhook with a simple curl command first to make sure it’s working.
• Stripe API Pagination: My script uses a `limit` of 100. If you have more than 100 failed payments in your time window (which would be a very bad day!), you’ll need to implement pagination to fetch all of them. For most use cases, 100 is plenty.

Conclusion

And that’s it. You’ve now got a robust, automated system for monitoring failed payments. It’s a simple “set it and forget it” solution that closes a critical feedback loop, helps your team act faster, and ultimately protects your revenue. It’s one of those small DevOps wins that has a surprisingly big impact. Hope this helps you out!

---

🤖 Frequently Asked Questions