RecurFix
Recovery API
RecurFix detects failed Mollie payments automatically once you connect your account. Use the API to track recoveries, query failed payments, receive webhook events, and pull analytics into your own systems.
Quickstart
Connect your Mollie API key in the dashboard - RecurFix starts detecting failed payments automatically. Use a RecurFix API key only when you need to read recovery data or integrate webhooks programmatically.
Authentication
All API requests require a Bearer token in the Authorization header.
# Base URL
https://api.recurfix.com/v1
# Authentication header
Authorization: Bearer rly_live_xxxxxxxxxxxx
Content-Type: application/json
Base response format
All responses return JSON with a consistent envelope format.
// Success
{
"data": { ... },
"meta": { "page": 1, "total": 48 }
}
// Error
{
"error": { "code": "not_found", "message": "..." }
}
Core Endpoints
Recoveries
/api/recoveries
List all recovery records
Returns a paginated list of all recovery attempts and their current status. Supports filtering by status, date range, and failure type.
Query parameters
status=recovered|pending|failed
from=2024-01-01
to=2024-01-31
page=1&limit=25
Response
{"data": [
{"id": "rcv_1a2b3c",
"status": "recovered",
"amount": {"value": "49.00"},
"recovered_at": "..."
}]}
/api/recoveries/:id
Get a single recovery record
Returns the full recovery record including timeline, retry attempts, emails sent, and final outcome.
Failed Payments
Detected automatically from your connected Mollie account - you do not need to POST failures via the API.
/api/failed-payments
List failed payment events
Returns all detected failed payments with failure classification, current recovery status, and associated customer data.
// Sample record
{
"id": "fp_4d5e6f",
"mollie_payment_id": "tr_abc123",
"failure_reason": "insufficient_funds",
"amount": { "value": "99.00", "currency": "EUR" },
"recovery_status": "in_progress",
"next_retry_at": "2024-01-15T09:00:00Z"
}
Analytics
/api/analytics/summary
Overall recovery metrics for date range
/api/analytics/funnel
Recovery funnel breakdown
/api/analytics/trends
Time-series recovery data
Webhook Events
Configure a webhook endpoint in your RecurFix dashboard to receive real-time events. Each request includes an x-recurfix-signature header for authentication.
invoice.recovered
Recovery payment succeeded for mollie_subscriptions or both integrations (Type A).
mandate.updated
Recovery payment succeeded for custom_billing or both integrations (Type B).
recovery.failed
Recovery payment failed, expired, or was canceled.
dunning.started
Dunning escalates to hosted recovery.
dunning.completed
Recovery succeeded, or the customer churned after max retries.
retry.succeeded
An auto-debit retry is paid (Mollie webhook or cron poll).
retry.failed
A retry payment ends non-success. Also emitted when a new auto-debit retry is scheduled - the name can be misleading in that case.
Webhook Signing Secret
Use this to verify the x-recurfix-signature header on incoming webhooks. Copy your Webhook Signing Secret from the RecurFix dashboard - RecurFix sends the same value in x-recurfix-signature on every request. Compare the header to your secret before processing the payload.
Node.js example
const webhookSigningSecret = process.env.RECURFIX_WEBHOOK_SECRET;
const incoming = req.headers['x-recurfix-signature'];
const valid = incoming === webhookSigningSecret;
if (!valid) return res.status(401).send('Unauthorized');
PHP example
$webhookSigningSecret = getenv('RECURFIX_WEBHOOK_SECRET');
$incoming = $_SERVER['HTTP_X_RECURFIX_SIGNATURE'] ?? '';
$valid = hash_equals($webhookSigningSecret, $incoming);
if (!$valid) { http_response_code(401); exit; }
Integration Examples
Common integration patterns for connecting your billing system to RecurFix.
1. Connect Mollie - recovery starts automatically
Add your Mollie API key in the RecurFix dashboard. Failed recurring payments are detected automatically - no POST to report failures, no code changes required.
// Dashboard setup (no API call needed to start recovery)
1. Settings → paste Mollie API key
2. RecurFix monitors failed payments via Mollie
3. Recovery engine runs retries, dunning, hosted page
// Optional: list what RecurFix already detected
const res = await fetch(
'https://api.recurfix.com/v1/api/failed-payments', {
headers: { Authorization: `Bearer ${process.env.RECURFIX_API_KEY}` }
});
2. Handle recovery webhook and restore subscription access
Listen for invoice.recovered or mandate.updated when a recovery payment succeeds, and recovery.failed when it does not.
// Express webhook handler
app.post('/webhooks/recurfix', (req, res) => {
const { event, data } = req.body;
if (event === 'invoice.recovered') {
// Type A: mollie_subscriptions / both
await subscriptionService.restoreAccess(data);
}
if (event === 'mandate.updated') {
// Type B: custom_billing / both
await mandateService.update(data.customer_id, data.mandate_id);
}
if (event === 'recovery.failed') {
await subscriptionService.markRecoveryFailed(data);
}
res.sendStatus(200);
});
Rate limits
API rate limits vary by plan. Rate limit info is returned in response headers.
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1705312800
Developer resources
Full API reference documentation
OpenAPI / Swagger specification
Postman collection
Developer support: [email protected]
Start Building with RecurFix
Get your API key when you sign up. API access is included on all plans.