Documentation

Welcome to RecoverPay

RecoverPay Circuit™ is a Revenue Defense Platform that protects your Stripe account from fraud, recovers failed payments, and prevents account freezes—all without changing your existing payment flow.

What you can do with Circuit™

Choose your integration path

Quick Start Guide

Get protected in under 5 minutes. No code changes required for basic protection—just connect your Stripe account.

<script 
  src="https://recoverpay.io/shield.js" 
  data-key="pk_live_your_public_key"
  async defer
></script>

Plans & Feature Matrix

Choose the right level of protection for your business. All plans include Stripe OAuth integration and real-time webhooks.

Circuit™ Engine

The Circuit™ Engine is our intelligent protection system that monitors, detects, and defends your Stripe account from threats that lead to account freezes.

Core Components

Integration Modes

Choose the integration that fits your needs. Start with webhooks for zero-code setup, or add the SDK for real-time blocking.

Shadow Mode

It's the perfect way to audit your risk exposure before enabling active protection. See real-time risk scores, device fingerprints, and velocity patterns for every transaction.

Payment Recovery

Automatically recover failed payments with intelligent retry scheduling and personalized dunning emails.

Health Monitoring

Real-time monitoring of your Stripe account health with proactive alerts before issues become critical.

Risk Detection

Multi-layered fraud detection combining device fingerprinting, velocity checks, and IP intelligence.

Active Blocking

When Circuit™ detects a high-risk transaction, it can automatically block the payment before it reaches Stripe.

@recoverpay/shield

Add real-time fraud detection to your checkout with our lightweight JavaScript SDK (~12KB minified).

Installation

<script 
  src="https://cdn.recoverpay.io/shield.min.js" 
  data-key="pk_live_your_public_key"
  async defer
></script>

npm install @recoverpay/shield

Usage

Call shield.scan() before processing payment:

import { RecoverPayShield } from '@recoverpay/shield';

const shield = new RecoverPayShield({ 
  publicKey: 'pk_live_your_public_key' 
});

// Wait for fingerprinting to complete
await shield.whenReady();

// Scan when user clicks "Pay"
const result = await shield.scan({
  email: customer.email,
  amount: 9900, // Amount in cents
  billingCountry: 'US'
});

if (result.action === 'BLOCK') {
  showError('Unable to process payment');
  return;
}

// Send token to your backend
await fetch('https://your-app.com/checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: customer.email,
    amount: 9900,
    rpToken: result.token
  })
});

What It Detects

Response Actions

@recoverpay/shield-node

Verify Shield tokens on your backend, manage blacklists, and report fraud.

Installation

npm install @recoverpay/shield-node

Token Verification

import { RecoverPayNode } from '@recoverpay/shield-node';

const rp = new RecoverPayNode({
  secretKey: process.env.RECOVERPAY_SECRET_KEY
});

// In your payment endpoint
app.post('/checkout', async (req, res) => {
  const { rpToken, email, amount } = req.body;

  const result = await rp.verify({
    token: rpToken,
    email,
    amount
  });

  if (!result.allowed) {
    return res.status(403).json({ 
      error: 'Payment blocked',
      reason: result.reason 
    });
  }

  // Proceed with Stripe payment
  const payment = await stripe.paymentIntents.create({
    amount,
    currency: 'usd',
    payment_method: req.body.paymentMethodId,
    confirm: true
  });

  return res.json({ success: true });
});

Report Fraud

After receiving a chargeback, report it to improve the risk model:

// After receiving a chargeback notification
await rp.reportFraud({
  scanId: 'scan_abc123',
  email: 'fraudster@example.com',
  amount: 9900,
  stripePaymentId: 'pi_xxx',
  chargebackReasonCode: '10.4'
});
// Auto-blacklists the email for future transactions

Express Middleware

import { shieldMiddleware } from '@recoverpay/shield-node';

app.use('/api/checkout', shieldMiddleware({
  secretKey: process.env.RECOVERPAY_SECRET_KEY
}));

// req.rpVerified contains verification result
app.post('/api/checkout', (req, res) => {
  if (!req.rpVerified?.allowed) {
    return res.status(403).json({ error: 'Blocked' });
  }
  // Process payment...
});

Security Checks

API Reference

RESTful API endpoints for direct integration. All endpoints require authentication via API key.

Webhooks

Receive real-time notifications about important events. Configure your webhook endpoint in the dashboard.

Available Events

{
  "id": "evt_1234567890",
  "type": "transaction.blocked",
  "created": 1702800000,
  "data": {
    "email": "user@example.com",
    "amount": 99900,
    "risk_score": 92,
    "factors": ["velocity_exceeded", "vpn_detected"],
    "action": "BLOCK"
  }
}