Handling Failed Payments

Configure retry logic and recover revenue from failed subscription payments.

Why Payments Fail

Common reasons for failed subscription renewals:

Reason	Description
Insufficient funds	Customer's account lacks funds
Expired card	Card expiration date has passed
Card declined	Issuer declined the transaction
Invalid card	Card number is invalid or cancelled
Fraud prevention	Transaction blocked by fraud systems

How Flintn Handles Failures

When a subscription renewal payment fails:

1. Status change - Subscription status changes to BILLING_RETRY

2. Webhook sent - SUBSCRIPTION_BILLING_RETRY event fired

3. Automatic retry - Flintn retries per your retry strategy

4. Final outcome - Subscription either renews or expires

Configuring Retry Strategies

Assign a retry strategy when creating a subscription plan:

curl -X POST https://api.flintn.com/v1/subscription-plans \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBSCRIPTION_NO_TRIAL",
    "name": "Monthly Pro",
    "currency": "USD",
    "full_price_amount": 29.99,
    "billing_frequency_value": 1,
    "billing_frequency_unit": "MONTHS",
    "retry_strategy_id": 5,
    "status": "ACTIVE"
  }'

Choosing a Strategy

Strategy Type	Best For
WEEKLY_NO_DISCOUNT	High-value subscriptions where discounts hurt revenue
WEEKLY_ESCALATING_25	General use - progressive discounts increase recovery
MONTHLY_NO_DISCOUNT	Monthly plans, gives customers time
NO_RETRY	When you prefer manual intervention

See Retry Strategies for the complete list.

Monitoring Failed Payments

Via Webhooks

Listen for billing retry events:

app.post('/webhooks/flintn', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'SUBSCRIPTION_BILLING_RETRY':
      // Payment failed, retry attempt made
      handleBillingRetry(event.data);
      break;

    case 'SUBSCRIPTION_RENEWED':
      // Retry succeeded
      handleRenewalSuccess(event.data);
      break;

    case 'SUBSCRIPTION_EXPIRED':
      // All retries failed
      handleSubscriptionExpired(event.data);
      break;
  }

  res.status(200).send('OK');
});

function handleBillingRetry(data) {
  const { subscription_id, customer_id, retry_count, next_retry_date } = data;

  // Log the retry
  console.log(`Subscription ${subscription_id}: retry ${retry_count}`);

  // Optionally notify customer
  if (retry_count === 1) {
    sendPaymentFailedEmail(customer_id);
  }
}

Via Dashboard

1. Navigate to Subscriptions

2. Filter by status: Billing Retry

3. View retry history and next retry date

Via API

curl -X GET "https://api.flintn.com/v1/subscriptions?status=BILLING_RETRY" \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Dunning Communication

Dunning is the process of communicating with customers about failed payments. Effective dunning can recover 20-40% of failed payments.

Dunning Email Sequence

Email	Timing	Content
Payment Failed	Immediately	Notify customer, provide update card link
Reminder 1	3 days	Gentle reminder, emphasize service continuity
Reminder 2	7 days	Urgency, mention approaching service interruption
Final Notice	14 days	Final warning before subscription expires

Example: Payment Failed Email

async function sendPaymentFailedEmail(customerId, subscriptionId) {
  const customer = await getCustomer(customerId);
  const subscription = await getSubscription(subscriptionId);

  await sendEmail({
    to: customer.email,
    subject: 'Action required: Update your payment method',
    template: 'payment-failed',
    data: {
      firstName: customer.first_name,
      planName: subscription.plan_name,
      amount: subscription.amount,
      updateUrl: `https://yoursite.com/update-payment?sub=${subscriptionId}`
    }
  });
}

Providing a Card Update Flow

Create a self-service card update page:

1. Generate a new client session for the subscription

2. Display the payment iframe for card entry

3. Process the update and notify the customer

// Generate client session for card update
const response = await fetch(
  'https://api.flintn.com/v1/subscriptions/client-sessions',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.FLINTN_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subscription_id: subscriptionId,
      update_payment_method: true
    })
  }
);

const { client_token } = await response.json();

Handling Expired Subscriptions

When all retry attempts fail, the subscription expires:

function handleSubscriptionExpired(data) {
  const { subscription_id, customer_id } = data;

  // Revoke access
  revokeCustomerAccess(customer_id);

  // Send expiration notice
  sendExpirationEmail(customer_id);

  // Update internal records
  markSubscriptionExpired(subscription_id);
}

Win-Back Campaigns

For expired subscriptions, consider:

• Offering a discount to re-subscribe

• Sending a "we miss you" email

• Providing a limited-time offer

Best Practices

1. Act Quickly

Send the first dunning email immediately after a failure. The faster you reach the customer, the higher the recovery rate.

2. Make Updates Easy

Provide a direct link to update payment method. Don't make customers log in and navigate to settings.

3. Use Multiple Channels

• Email (primary)

• In-app notifications

• SMS for high-value customers

4. Be Helpful, Not Aggressive

Frame communications around helping the customer maintain their service, not demanding payment.

5. Monitor Recovery Rates

Track:

• Overall recovery rate (payments recovered / total failures)

• Recovery by retry attempt

• Recovery by dunning email

6. Consider Timing

• Avoid retrying on weekends for B2B subscriptions

• Retry after common paydays (1st and 15th of month)

• Consider the customer's timezone

Metrics to Track

Metric	Description	Target
Recovery Rate	% of failed payments eventually recovered	>50%
Involuntary Churn	% of customers lost due to payment failure	<3%
Average Retry Count	Number of retries before recovery	<2
Dunning Email Open Rate	% of dunning emails opened	>40%

Next Steps

• Retry Strategies - Detailed strategy reference

• Managing Subscriptions - Monitor subscription health

• Webhooks - Set up event notifications