Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.revtain.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide shows the recommended Fast Track flow: your checkout stays exactly as it is, and Revtain handles recovery when payments fail.
Your checkout doesn’t change. Customers continue to pay with Stripe, Apple Pay, Google Pay — whatever you already support. Revtain operates entirely behind the scenes. No iFrame, no UI changes, nothing customer-facing.

​
How It Works

1

Customer pays through your existing checkout

Stripe, Chargebee, custom — anything.
2

Payment succeeds → log it (optional)

Call /pulse so Revtain can calculate Lift accurately.
3

Payment fails → hand off to Revtain

Pass the gateway token, amount, and decline code.
4

Revtain runs the engine

AI scoring, heuristics, multi-gateway cascade.
5

You receive a webhook with the result

recovery.success, recovery.failed, or recovery.blocked.

​
Backend: Charge, Then Recover

app.post('/your-backend/charge', async (req, res) => {
  const { paymentMethodId, amount, stripeCustomerId } = req.body;

  let declineCode;

  // 1. Try charging through YOUR primary gateway using YOUR token
  //    (Your normal checkout — Revtain not involved yet)
  try {
    const charge = await stripe.paymentIntents.create({
      amount,
      currency: 'usd',
      customer: stripeCustomerId,
      payment_method: 'pm_xxx',
      confirm: true
    });

    // Log the organic success so Revtain can calculate Lift
    await fetch(`${REVTAIN_BASE_URL}/api/recovery/pulse`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': process.env.REVTAIN_API_KEY
      },
      body: JSON.stringify({ amount, currency: 'USD', transactionId: charge.id })
    });

    return res.json({ success: true, chargeId: charge.id });
  } catch (stripeError) {
    declineCode = stripeError.decline_code;
  }

  // 2. Primary failed — hand off to Revtain
  const recovery = await fetch(`${REVTAIN_BASE_URL}/api/recovery/execute`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.REVTAIN_API_KEY
    },
    body: JSON.stringify({
      paymentMethodToken: paymentMethodId,
      amount,
      currency: 'USD',
      originalDeclineCode: declineCode,
      cardOrigin: 'US',
      idempotencyKey: `order_${orderId}_recovery`
    })
  });

  const result = await recovery.json();

  if (recovery.status === 200 && result.success) {
    return res.json({ success: true, recovered: true, transactionId: result.transactionId });
  } else if (recovery.status === 202) {
    return res.json({ success: false, queued: true, message: result.message });
  } else if (recovery.status === 403) {
    return res.status(403).json({ success: false, blocked: true, error: result.error });
  } else if (recovery.status === 409) {
    return res.json({ success: false, duplicate: true, existing: result.existingTransactionId });
  }

  return res.json({ success: false, error: result.error || result.message });
});

​
Custom / In-House Billing

For in-house billing without a webhook event, call Revtain directly from your payment failure handler: 
async function handlePaymentFailure(payment) {
  const recovery = await fetch('https://api.revtain.com/api/recovery/execute', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.REVTAIN_API_KEY
    },
    body: JSON.stringify({
      paymentMethodToken: payment.paymentToken,
      amount: payment.amountCents,
      currency: payment.currency || 'USD',
      originalDeclineCode: payment.declineCode || 'unknown',
      idempotencyKey: `custom_${payment.id}_recovery`
    })
  });
  return recovery.json();
}
The only requirement is that you have the customer’s payment token from your gateway. Everything else is the same regardless of billing platform.
Need help? Contact the Revtain team at support@revtain.com for guidance on integrating with your specific billing platform.