Dunning Management#

How AuxCORE handles failed recurring payments: automatic retries, customer notices, and recovery tools.

Overview#

When a scheduled charge is declined, AuxCORE automatically:

• 🔄 Auto-retries - Retries the charge on a fixed schedule
• 📧 Notifies the customer - Payment-failed email after each failed run, a dunning notice when retries run out
• ⏸️ Auto-pauses - Subscriptions are paused after the last retry; payment plans become defaulted
• 📊 Tracks attempts - Failure counters and an activity log on every schedule

All endpoints on this page use admin authentication (Authorization: Bearer YOUR_JWT + X-Tenant-ID). See Subscriptions.

How Dunning Works#

Subscriptions (recurring schedules)#

Payment fails → retry after 24h → retry after 24h → ... → max attempts reached → Pause + dunning email

• Each schedule allows maxRetryAttempts retries (default 3).
• After each decline, failCount and failedPaymentCount increase, lastFailedPaymentDate is set and the next retry is scheduled 24 hours later (nextRetryAt).
• Due charges are processed every hour; failed charges are also swept every 6 hours.
• When the retries are exhausted the schedule becomes paused (isRecurring: false, pausedReason: "Payment failed after 3 retry attempts") and a dunning email is sent once (only when the schedule has sendNotifications: true and the merchant's failedPaymentNoticeEnabled is on).
• A successful charge resets failedPaymentCount, retryCount and nextRetryAt.

Payment Plans#

• A declined installment is retried every retryIntervalDays (default 3 days) up to maxRetryAttempts (default 3) attempts, while retryFailedPayments is true.
• While a retry is pending the installment status is pending with nextRetryAt set.
• After the last failed attempt the plan becomes defaulted.
• Late fees (if configured) keep accruing on overdue installments and are added to the retried charge. See Payment Plans.

Note: The retry schedule and the action after the last retry are fixed by the platform. There are no dunning-settings endpoints, no configurable retry schedule, no grace period and no cancel / manual_review action.

Failure Notice Setting#

The only merchant-level dunning control is whether the failed-payment notice is sent. It is part of the merchant's messaging defaults.

curl https://uat.auxcore.net/api/v1/merchants/c1a7e5d2-3b4f-4e6a-9c8d-7f0b1a2e3d45/messaging-defaults \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "successfulPaymentReceiptEnabled": true,
    "recurringPaymentReminderEnabled": true,
    "failedPaymentNoticeEnabled": true,
    "usingDefaults": true
  }
}

curl -X PUT https://uat.auxcore.net/api/v1/merchants/c1a7e5d2-3b4f-4e6a-9c8d-7f0b1a2e3d45/messaging-defaults \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "failedPaymentNoticeEnabled": false }'

Monitor Failed Payments#

There is no dedicated failed-payments endpoint. Use these instead:

• GET /api/v1/recurring/overview — data.failed is the number of schedules with at least one failed payment.
• GET /api/v1/recurring/:id — failedPaymentCount, retryCount, maxRetryAttempts, nextRetryAt, lastFailedPaymentDate, pausedReason.
• GET /api/v1/recurring/:id/schedule — cycle rows with status failed.
• GET /api/v1/billing/payment-plans?status=defaulted — defaulted payment plans.

curl -X POST https://uat.auxcore.net/api/v1/recurring/8d2f1c4b-6a3e-4f7d-b1c9-0e5a7d3f2b61/retry-failed \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "id": "8d2f1c4b-6a3e-4f7d-b1c9-0e5a7d3f2b61",
    "status": "active",
    "failedPaymentCount": 0,
    "retryCount": 0,
    "nextRetryAt": "2026-10-01T16:45:00.000Z"
  },
  "message": "Payment retry initiated successfully"
}

{
  "success": true,
  "data": { "success": true, "transactionId": "5b9e2d7a-1c3f-4a8e-b6d0-2f4c8a1e7b93" },
  "message": "Payment processed successfully"
}

Update the Customer's Card#

Most failures are fixed by a new card.

Send Update Link#

Emails the customer a secure link (valid 24 hours) to replace the card on file.

For payment plans: POST /api/v1/billing/payment-plans/:id/send-method-update-link.

{ "pciToken": "pci_tok_1a2b3c4d5e6f", "last4": "4242", "brand": "visa" }

Notifications#

AuxCORE does not emit dunning webhook events. Each attempt is an ordinary transaction, so declined attempts appear as declined transactions. Customer emails:

Common Failure Reasons#

Best Practices#

✅ DO:#

• Watch the overview - Follow up on schedules with failed payments
• Send the update link early - Before the last retry runs
• Resume after fixing - Auto-paused schedules stay paused until resumed
• Keep failure notices on - Customers can only fix what they know about

❌ DON'T:#

• Don't hammer Charge Now - Repeated declines can trigger issuer blocks
• Don't retry stop-recurring declines - The cardholder revoked the authorization
• Don't cancel immediately - A paused schedule can be resumed

Testing Dunning#

# 1. Create a schedule with a card that will decline in the Sandbox, due today
# 2. Charge it now and confirm the decline
curl -X POST https://uat.auxcore.net/api/v1/recurring/8d2f1c4b-6a3e-4f7d-b1c9-0e5a7d3f2b61/charge-now \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

# 3. Inspect the retry state
curl https://uat.auxcore.net/api/v1/recurring/8d2f1c4b-6a3e-4f7d-b1c9-0e5a7d3f2b61 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

See Testing for Sandbox decline cards.

Next Steps#

• Create subscriptions →
• Payment plans →
• Handle webhooks →

Need help? Contact support@auxcore.net