Skip to main content

Stripe

Stripe is a leading payment processing platform that enables businesses to accept online payments, manage subscriptions, handle refunds, and process financial transactions. With Stripe, businesses can accept credit cards, digital wallets, bank transfers, and other payment methods while managing complex billing scenarios including one-time payments, recurring subscriptions, invoicing, and marketplace operations.

Authentication Types​

Stripe supports 1 authentication method:

  • API Key - Use your Stripe secret API key for secure server-side access.
    • Pros: Simple setup, full API access, works immediately, secure when properly stored
    • Cons: Provides full account access (use restricted keys for limited permissions if needed)
    • Best for: Server-side integrations, backend automation, payment processing workflows

Setting up API Key Authentication​

To use Stripe with Webrix, you need to obtain your API key from the Stripe Dashboard.

1. Access Your Stripe Dashboard​

  1. Log in to your Stripe account at https://dashboard.stripe.com

  2. Make sure you're in the correct mode (Test or Live) using the toggle in the top-right corner

tip

Always start with Test mode for development and testing. Test mode uses separate API keys and doesn't process real payments or charge real cards.

2. Get Your API Key​

  1. In the Stripe Dashboard, click Developers in the left sidebar

  2. Click API keys

  3. You'll see two types of keys:

    • Publishable key (starts with pk_test_ or pk_live_) - Used in client-side code
    • Secret key (starts with sk_test_ or sk_live_) - Used in server-side code

  4. Click Reveal test key or Reveal live key next to the Secret key

  5. Copy the secret key value

warning

Keep your secret API key secure! Never share it publicly, commit it to version control, or expose it in client-side code. Anyone with your secret key can perform any action on your Stripe account.

3. Understanding Test vs Live Mode​

Stripe provides two separate environments:

  • Test Mode (sk_test_* keys):

    • For development and testing
    • Uses test credit cards (e.g., 4242 4242 4242 4242)
    • No real money is processed
    • Separate test data from production
    • Free to use with no transaction fees

  • Live Mode (sk_live_* keys):

    • For production use with real customers
    • Processes actual payments
    • Real credit cards and bank accounts
    • Transaction fees apply
    • Requires activated Stripe account

4. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Stripe and click Use

  3. Under Authentication Type, select API Key

  4. Paste your Secret Key in the API Key field

  5. Click Save Changes

5. Test the Connection​

  1. After saving, you can test the connection by using any read-only tool like "Get Balance" or "List Customers"

  2. If using test mode, try creating a test customer to verify the integration works

Common Use Cases​

Processing Payments with Payment Intents​

Payment Intents are the recommended way to accept payments with Stripe:

  1. Create Payment Intent - Initialize a payment with amount and currency
  2. Confirm Payment Intent - Complete the payment (may trigger 3D Secure)
  3. Get Payment Intent - Check the payment status

Payment Intents handle complex payment flows automatically including authentication, webhooks, and retries.

Managing Customer Subscriptions​

Create and manage recurring billing:

  1. Create Customer - Store customer information
  2. Create Product and pricing (done in Dashboard or via API)
  3. Create Subscription - Start recurring billing
  4. List Subscriptions - Monitor active subscriptions
  5. Cancel Subscription - End recurring billing

Handling Refunds​

Process refunds for completed payments:

  1. List Charges or List Payment Intents - Find the payment to refund
  2. Create Refund - Issue full or partial refund
  3. Get Refund - Check refund status

Refunds are processed immediately and return funds to the original payment method.

Viewing Balance and Payouts​

Track your account funds:

  1. Get Balance - Check available and pending balances
  2. List Balance Transactions - View all balance movements
  3. List Payouts - Track transfers to your bank account

Troubleshooting​

Invalid API Key Error​

If you see "Invalid API key provided" or authentication errors:

Cause: The API key format is incorrect, the key has been deleted, or you're using the wrong key type.

Solution:

  1. Verify you're using the secret key (starts with sk_test_ or sk_live_), not the publishable key
  2. Make sure you copied the entire key without extra spaces or characters
  3. Check that the key hasn't been deleted in your Stripe Dashboard (Developers → API keys)
  4. Verify you're using the correct mode key (test vs live) for your intended operation
  5. Try generating a new secret key if the issue persists

Test Mode vs Live Mode Mismatch​

If operations work in test mode but fail in live mode (or vice versa):

Cause: Using a test mode API key when trying to access live mode data, or vice versa.

Solution:

  1. Check which mode your API key is for (test keys start with sk_test_, live keys start with sk_live_)
  2. Ensure you're using the correct key for your intended environment
  3. Remember that test and live mode have completely separate data - customers, payments, subscriptions, etc. created in test mode won't appear in live mode

Rate Limiting​

If you see 429 (Too Many Requests) errors:

Cause: You've exceeded Stripe's API rate limits. Stripe enforces rate limits to ensure platform stability.

Solution:

  1. Stripe typically allows 100 read requests per second and 100 write requests per second
  2. Implement exponential backoff: retry failed requests with increasing delays (e.g., 1s, 2s, 4s, 8s)
  3. Use pagination efficiently with appropriate limit values
  4. Cache frequently accessed data when possible
  5. For bulk operations, consider batching requests with small delays between them

Idempotency and Duplicate Requests​

If you're accidentally creating duplicate charges or customers:

Cause: Network issues or retries can cause the same request to be processed multiple times.

Solution:

  1. Stripe supports idempotency for POST requests - include an Idempotency-Key header with a unique value
  2. If the same request is sent again with the same idempotency key, Stripe returns the original result
  3. Use unique identifiers (like order IDs or UUIDs) as idempotency keys
  4. Idempotency keys are valid for 24 hours

Currency and Amount Formatting​

If payments fail with "invalid amount" errors:

Cause: Amount is not in the correct format or currency is not supported.

Solution:

  1. Amounts must be in the smallest currency unit (cents, not dollars)
    • $10.00 USD = 1000 (cents)
    • €15.50 EUR = 1550 (cents)
    • ¥500 JPY = 500 (yen has no decimal places)
  2. Currency codes must be three-letter ISO codes in lowercase (e.g., 'usd', 'eur', 'gbp')
  3. Check Stripe's supported currencies for a full list
  4. Zero-decimal currencies (like JPY, KRW) use the currency value directly without decimal places

Webhooks and Event Handling​

If you need real-time notifications about payment events:

Note: Webhook setup is done through the Stripe Dashboard, not through the MCP connector.

Solution:

  1. Go to Stripe Dashboard → Developers → Webhooks
  2. Click "Add endpoint" and enter your webhook URL
  3. Select the events you want to receive (e.g., payment_intent.succeeded, customer.subscription.deleted)
  4. Use the webhook signing secret to verify webhook authenticity
  5. Respond to webhooks quickly (within 5 seconds) and process async if needed

Payment Method Declined​

If legitimate payments are being declined:

Cause: Various reasons including insufficient funds, fraud detection, incorrect card details, or issuer restrictions.

Solution:

  1. Check the decline code in the charge or payment intent error details
  2. Common decline codes:
    • insufficient_funds - Customer needs to use a different card
    • card_declined - Generic decline, customer should contact their bank
    • incorrect_cvc - Card security code is wrong
    • expired_card - Card has expired
  3. Stripe Radar may block high-risk payments - review in Dashboard under Radar → Reviews
  4. For test mode, use Stripe test cards for different scenarios

Subscription Billing Issues​

If subscription charges are failing:

Cause: Payment method issues, expired cards, or billing configuration problems.

Solution:

  1. Ensure customer has a valid default payment method attached
  2. Check the subscription's default_payment_method or customer's invoice_settings.default_payment_method
  3. Review failed invoices in Stripe Dashboard → Billing → Invoices
  4. Configure Smart Retries in Dashboard → Settings → Billing to automatically retry failed payments
  5. Set up email notifications to alert customers of failed payments

Missing Data or Empty Responses​

If API calls return empty data when you expect results:

Cause: Filtering by wrong parameters, using wrong resource IDs, or accessing wrong mode (test vs live).

Solution:

  1. Verify you're in the correct mode (test vs live) - they have separate data
  2. Check that IDs start with the correct prefix (e.g., cus_ for customers, pi_ for payment intents)
  3. Remove filters temporarily to see if data exists
  4. Use the Search tools instead of List tools for more flexible querying
  5. Check the Stripe Dashboard to verify the data exists

Additional Resources​