Back to Onboarding

Stripe API Key Setup Guide

Follow these steps to securely connect your Stripe account to Vantirs

1

Log in to Stripe

Go to dashboard.stripe.com

Log in to your Stripe account

Mode Selection

Make sure you are in the correct mode:

  • Use Test mode if you are testing
  • Use Live mode if you want real protection

⚠️ Vantirs only works on the mode you connect.

Test keys → Test disputes
Live keys → Real disputes

2

Create a Restricted API Key (Recommended)

We strongly recommend using a Restricted Key instead of a full secret key.

How to create it:

  1. In Stripe Dashboard, go to Developers → API keys
  2. Click "Create restricted key"
  3. Name it something like: Vantirs – Dispute Protection
3

Set Required Permissions

Enable only the permissions below:

Required (must be ON)

  • Charges → Read
  • Disputes → Read & Write
  • Payment Intents → Read
  • Customers → Read
  • Balance Transactions → Read

Optional (recommended)

  • Events → Read (helps with webhook reliability)

Must be OFF

  • Creating charges
  • Refunds
  • Payouts
  • Account settings
  • Anything related to moving money

🔒 Security Guarantee

Vantirs cannot withdraw funds or charge customers.

4

Copy the API Key

After saving:

  • Copy the key that starts with:
  • rk_test_... (Test mode)
  • rk_live_... (Live mode)
  • Paste this key into the Vantirs onboarding form.
5

Set Up Stripe Webhooks (Important)

Webhooks allow Stripe to notify Vantirs instantly when a dispute happens.

Add the Vantirs webhook URL

Vantirs will give you a URL like:

https://vantirs.com/api/webhooks/stripe/{your_merchant_id}

In Stripe:

  1. Go to Developers → Webhooks
  2. Click "Add endpoint"
  3. Paste the webhook URL
  4. Select these events:
    • charge.dispute.created
    • charge.dispute.updated
  5. Save the endpoint
6

Copy the Webhook Secret

After saving the webhook:

  1. Click the webhook you just created
  2. Copy the Signing secret:whsec_...
  3. Paste it into Vantirs when asked

This ensures all events are secure and verified.

7

(Optional) Run Historical Sync

To enable protection immediately, Vantirs may ask to sync past transactions.

This allows us to:

  • Find historical trusted payments
  • Qualify disputes for Visa CE 3.0
  • Avoid waiting 3–4 months for data

You can start this with one click inside Vantirs.

8

Send IP & device on each charge (required for CE 3.0)

For Vantirs to qualify disputes for Visa CE 3.0 liability shift, we need to match the disputed charge to 2+ prior successful charges using the same IP or device.

When you create charges (or Payment Intents), send these in metadata:

  • metadata.ip_address – customer IP at payment time
  • metadata.device_fingerprint – device/browser fingerprint (e.g. from Stripe.js or your fraud tool)

Without these, we cannot find historical matches and disputes will show as "not eligible" even when the cardholder has a long history with you.

If you don’t send metadata today, start with your next integration update. We’ll use it for all new charges and future disputes.

Win more disputes — checklist

Complete these for the best results. Missing steps show up as "Why not CE 3.0?" in your dashboard.

  • Webhook connected — so we receive disputes instantly (Steps 5–6)
  • Run 12‑month backfill — from Dashboard or after onboarding (Step 7)
  • Pass IP (and device) on each charge — in metadata (Step 8)
  • Optional: activity tracking — use /api/track for login/usage so we can attach activity logs to evidence

What Vantirs Can Access (Transparency)

Vantirs can:

  • Read past successful charges
  • Detect disputes
  • Upload dispute evidence (only when approved)
  • Monitor dispute ratios (VAMP)

Vantirs cannot:

  • Move money
  • Create or cancel charges
  • Change your Stripe settings
  • Access full card numbers

We use Stripe's official APIs and follow best-practice security.

Common Questions

❓Is this safe?

Yes. We recommend restricted keys and encrypt all credentials at rest.

❓Can I revoke access?

Yes. You can delete the API key or webhook anytime in Stripe.

❓Does this affect my customers?

No. Everything happens behind the scenes.

Done 🎉

Once connected:

  • Vantirs automatically monitors disputes
  • Detects liability-shift eligibility
  • Generates bank-ready evidence
  • Helps you recover money you'd otherwise lose
Back to Onboarding