Skip to main content
Revtain recovers failed payments without touching your checkout. What changes is only how Revtain learns about a failure: through your billing platform, through your API calls, or both. This page tells your engineering team exactly what they will build for each path — and what they will never need to build.
What you never build, on any path: retry logic, gateway failover, decline-code handling, card-update pages, or any customer-facing UI. Revtain runs all of it. Your customers see nothing new, and no card data ever flows through your servers to ours — tokens only.

​
Choose your path

Your stackPathEngineering effort
Chargebee, Recurly, Stripe Billing, Braintree Subscriptions, Zuora, or Shopify RechargeConnector~15 minutes — paste one URL
Custom subscription billing (you create the charges)Recovery APIHalf a day, including webhook handling
Ecommerce / one-time paymentsRecovery APIHalf a day, including webhook handling
Paths combine cleanly. A connector client can still call the API for edge cases, and every path uses the same webhook events.

​
Path A — Billing platform connector

If your subscriptions run on a supported billing platform, the platform already knows when a payment fails. The connector listens for that event directly, so your team writes no failure-handling code at all. What your engineers do:
1

Paste the Revtain webhook URL into your billing platform

You receive a unique connector URL at onboarding. Add it in your platform’s webhook settings (for example, Chargebee → Settings → Webhooks). One URL, one paste.
2

Add the signing credential

Your platform signs its webhooks; Revtain verifies every one and rejects anything unsigned. The exact credential (an HMAC secret or basic-auth pair, depending on platform) is exchanged at onboarding.
3

Stand up a webhook receiver for results (recommended)

Revtain writes successful recoveries back into your billing platform automatically — the invoice gets marked paid where it lives. The webhook endpoint is for your own records and any custom logic.
After that, the loop is closed without you: payment fails → platform notifies Revtain → Revtain recovers → Revtain marks the invoice paid in your platform → your platform resumes the subscription. Your team ships nothing further as Revtain evolves.
This is the gold-standard integration. If you are on one of these platforms, do not build against the API first — the connector covers the entire failure lifecycle.

​
Path B — Recovery API (subscriptions)

For teams that run their own billing engine: you already have the moment in your code where a renewal charge fails. The integration is one HTTP call at that moment, plus a webhook receiver. What your engineers do:
1

On charge failure, call /api/recovery/execute

Pass the gateway token you already hold (for example a Stripe pm_xxx), the exact amount, the currency, and the decline code your gateway returned. See the API integration guide for working code in Node and Python.
2

Stop your own retry logic for that invoice

Hand off means hand off. Revtain manages attempt timing and card-network retry limits; parallel retries from your side would burn the issuer’s tolerance for both of you.
3

Receive the outcome by webhook

recovery.success → mark the invoice paid and resume service. recovery.failed → branch on the recommendedAction field — it tells you whether to wait, request a card update, or review the account. Full event reference: Webhooks.
4

Store updated card tokens

When a customer updates their card through a Revtain-hosted link, the card.updated event delivers the new gateway token. Save it against the customer and discard the old one.
Idempotency: send an idempotencyKey (your invoice ID works well) on every /execute call. Duplicate submissions of the same key return 409 instead of risking a second charge — safe to retry your call on network errors. Optional, worth the extra hour:
  • Call /api/recovery/pulse on successful organic charges so your monthly report can compute recovery lift against your true baseline.
  • Handle card.expiring_soon — Revtain monitors active cards and warns you before a renewal fails, with a ready-made card-update link to forward to the customer. Recovery without a decline ever happening.

​
Path C — Recovery API (ecommerce and one-time)

One-time payments fail for the same issuer-side reasons subscriptions do — but the customer relationship is thinner, so speed matters more. The mechanics are identical to Path B with two differences in emphasis. Difference 1 — the customer may still be present. A declined first payment or trial conversion often happens while the customer is still on your page. Flag it: 
{
  "paymentMethodToken": "pm_xxx",
  "amount": 4900,
  "currency": "USD",
  "originalDeclineCode": "do_not_honor",
  "idempotencyKey": "order_18241",
  "customerPresent": true
}
customerPresent: true tells the engine a human is waiting: the attempt is treated as time-critical rather than scheduled for optimal timing, and the response comes back while your customer is still deciding. Difference 2 — the rescue link arrives in the response itself. When a customer-present attempt fails on something the customer can fix — an expired card, a typo, not enough funds — the response includes a ready-made update surface: 
{
  "success": false,
  "message": "Recovery Failed",
  "cardUpdateUrl": "https://pay.yourdomain.com/update-card/abc123xyz",
  "customerFixable": true,
  "recommendedAction": "request_card_update"
}
Surface cardUpdateUrl immediately — a modal on the order page, an inline banner. The link expires in one hour because it is built for the customer standing in front of the failure, not for an email three days later. When the decline is one the customer cannot fix (for example a card the issuer flagged), no link is returned by design — fall back to your normal order-failed flow. For one-time buyers there is no next billing cycle to catch them on; this moment is the recovery. (isTrialConversion: true remains available for SaaS trial-to-paid conversions and has the same urgency effect.) What your engineers do: identical to Path B — one /execute call at the failure point, one webhook receiver, store updated tokens.

​
The contract you can build against

Revtain’s API surface is frozen in shape: integrate once and you never ship integration code again.
  • New request fields are always optional with safe defaults.
  • Existing webhook fields never change meaning. New fields are appended — ignore what you don’t use.
  • New webhook events are additive. An unrecognised event value is always safe to skip.
  • New capabilities default to backend-only: where a feature could require you to pass new data or let Revtain infer it, Revtain infers it.
Next step: the integration checklist is the full pre-launch list your team can work through, and testing covers exercising the engine safely before go-live.