API Documentation

Complete reference for integrating Revive into your application. Connect Stripe, configure webhooks, and recover failed payments programmatically.

🚀Getting Started

Quick Setup Guide

Revive connects to your Stripe account and automatically handles failed payment recovery. Setup takes less than 3 minutes.

1

Connect Your Stripe Account

Click "Connect with Stripe" in your dashboard. We use OAuth for secure, one-click authorization.

2

Configure Webhooks

Revive automatically registers the required webhooks. You can verify in your Stripe Dashboard:

Endpoint: https://revive-hq.com/api/webhooks/stripe
3

Customize Recovery Settings

Configure retry schedules, dunning email templates, and recovery preferences in Settings.

✓

You're Live!

Revive now monitors your account 24/7 and automatically recovers failed payments.

No code changes required

Revive works entirely through Stripe webhooks. You don't need to modify your application code or payment flow.

🔔Webhook Events

Revive listens to the following Stripe webhook events to automatically detect and recover failed payments:

invoice.payment_failedCritical

Triggered when an invoice payment attempt fails. Revive immediately creates a recovery record, analyzes the failure reason, and schedules smart retries based on the decline code.

Triggers:Payment record creation, retry scheduling
Actions:Dunning email sent (if applicable), retry scheduled
invoice.payment_succeededRecovery

Triggered when a payment succeeds. If this invoice was previously marked as failed, Revive marks it as recovered and sends a confirmation email to the customer.

Triggers:Recovery detection, analytics update
Actions:Mark as recovered, send confirmation, update stats
customer.subscription.updatedMonitoring

Triggered when subscription details change (e.g., payment method updated, plan changed). Revive uses this to detect manual payment method updates and adjust retry strategies.

Use case:Customer updated card → cancel pending retries
customer.subscription.deletedCleanup

Triggered when a subscription is cancelled. Revive stops all pending retries for this subscription and marks the recovery attempt as cancelled.

Actions:Cancel pending retries, update analytics

Example Webhook Configuration

# Configure in Stripe Dashboard:
# 1. Go to Developers → Webhooks
# 2. Add endpoint: https://revive-hq.com/api/webhooks/stripe
# 3. Select events:
#    - invoice.payment_failed
#    - invoice.payment_succeeded
#    - customer.subscription.updated
#    - customer.subscription.deleted

⚡REST API Endpoints

Programmatically access Revive's recovery data and trigger manual actions. All endpoints require authentication.

GET
/api/health

Health check endpoint. Returns system status and connection info.

Response

{
  "timestamp": "2026-02-05T18:30:00.000Z",
  "env": {
    "hasRedisUrl": true,
    "hasStripeKey": true,
    "hasWebhookSecret": true
  },
  "db": {
    "status": "connected",
    "latency": 45
  },
  "stats": {
    "totalPayments": 847,
    "recovered": 796
  }
}

Example Request

curl https://revive-hq.com/api/health \
  -H "Authorization: Bearer YOUR_API_KEY"
GET
/api/dashboard/stats

Get comprehensive recovery statistics and metrics.

Query Parameters

accountId•Optional: Filter by Stripe account ID

Response

{
  "stats": {
    "totalRecovered": 24750.00,
    "recoveryRate": 94.2,
    "activeRetries": 18,
    "dunningCount": 5,
    "failedThisMonth": 42,
    "recoveredThisMonth": 38,
    "mrrSaved": 3250.00,
    "churnPrevented": 87.5
  },
  "dailyTrend": [
    {
      "date": "2026-02-05",
      "recovered": 3,
      "failed": 1,
      "amount": 450.00
    }
  ],
  "dbHealth": {
    "status": "connected"
  }
}

Example Request

curl https://revive-hq.com/api/dashboard/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
POST
/api/webhooks/stripe

Stripe webhook receiver. Handles all payment and subscription events.

Note: This endpoint is automatically configured when you connect Stripe. Direct calls are not recommended.

GET
/api/recovery/status

Get recovery status for a specific invoice or customer.

Query Parameters

invoiceId•Stripe invoice ID (e.g., in_xxx)
customerId•Alternative: Stripe customer ID

Response

{
  "payment": {
    "id": "pay_xxx",
    "stripeInvoiceId": "in_xxx",
    "status": "retrying",
    "amount": 4900,
    "currency": "usd",
    "retryCount": 2,
    "maxRetries": 5,
    "nextRetryAt": 1738792800000,
    "failureReason": "insufficient_funds",
    "retryHistory": [
      {
        "attemptedAt": 1738706400000,
        "result": "failed",
        "reason": "insufficient_funds"
      }
    ],
    "emailsSent": [
      {
        "type": "dunning_initial",
        "sentAt": 1738706400000,
        "opened": true
      }
    ]
  }
}

Example Request

curl "https://revive-hq.com/api/recovery/status?invoiceId=in_xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST
/api/recovery/retry

Manually trigger a retry for a failed payment.

Request Body

{
  "invoiceId": "in_xxx"
}

Response

{
  "success": true,
  "message": "Payment retry initiated",
  "payment": {
    "id": "pay_xxx",
    "status": "retrying",
    "retryCount": 3,
    "nextRetryAt": 1738879200000
  }
}

Example Request

curl -X POST https://revive-hq.com/api/recovery/retry \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoiceId": "in_xxx"}'

🔐Authentication

All API requests require authentication using an API key. You can generate API keys in your dashboard settings.

Using API Keys

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure

Never commit API keys to version control or expose them in client-side code. Use environment variables and rotate keys regularly.

Key Management Best Practices

  • •Use separate keys for development, staging, and production
  • •Rotate keys every 90 days or immediately if compromised
  • •Store keys in secure environment variables or secret managers
  • •Monitor API key usage in your dashboard for suspicious activity

⏱️Rate Limits

To ensure fair usage and system stability, API requests are rate-limited per account.

Standard Limits

100
requests per minute
5,000
requests per hour

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1738706460

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}

Need higher limits?

Contact support@revive-hq.com to discuss custom rate limits for your use case.

⚠️Error Codes

Revive uses conventional HTTP response codes and returns detailed error messages in JSON format.

2xxSuccess
200 OK

Request succeeded

201 Created

Resource successfully created

4xxClient Errors
400 Bad Request

Invalid request format or parameters

401 Unauthorized

Missing or invalid API key

403 Forbidden

API key doesn't have required permissions

404 Not Found

Requested resource doesn't exist

429 Too Many Requests

Rate limit exceeded

5xxServer Errors
500 Internal Server Error

Something went wrong on our end

503 Service Unavailable

Temporary service disruption

Error Response Format

All error responses follow a consistent structure:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid invoice ID format",
    "param": "invoiceId",
    "code": "invalid_format"
  }
}

Ready to recover lost revenue?

Connect your Stripe account and start recovering failed payments in minutes.

Get Started FreeContact Support