Payment Recovery Guide

This guide explains how failed payments and payment recovery work from a Customer Support and clinic operations point of view. It covers subscription renewal failures, paused subscriptions, retry behavior, patient invoice payment, payment method issues, notifications, and when CS should escalate.

What Payment Recovery Is

Payment recovery is the process used when a subscription cycle charge or eligible order payment fails.

The app creates or keeps an order/invoice in AWAITING_PAYMENT, stores recovery metadata on the order, and gives the patient a way to update/pay from the patient portal.

Payment recovery is most important for:

• recurring subscription cycle orders
• failed automatic renewal charges
• missing saved payment methods
• retrying failed subscription cycle charges

What Happens When a Subscription Charge Fails

When the subscription processor creates a cycle order and the charge fails:

1. order is created for the subscription cycle
2. invoice is created
3. payment attempt fails or no compatible payment method is found
4. order moves to AWAITING_PAYMENT
5. recovery metadata is stored on the order
6. subscription may be paused
7. payment.failed workflow can fire
8. recovery retry may be scheduled
9. patient can pay/update payment method from the patient portal

If payment later succeeds, the system can mark the invoice paid, recalculate the order status, and reactivate the paused subscription.

Where CS Can See Recovery

Useful places:

• EMR -> Subscriptions
• EMR -> Failed Payments
• EMR -> Orders
• Patient profile -> Orders / Subscriptions / Invoices
• Patient Portal -> Invoices
• Patient Dashboard recovery warning

Patient recovery URL:

• /patient/invoices?recovery=1

Recovery Statuses

NEEDS_PAYMENT_METHOD

No compatible saved payment method is available.

Common causes:

• patient has no saved card
• card exists only in another gateway vault
• active payment gateway changed
• saved payment method was removed or invalid

What CS should say:

We need an updated payment method before the system can retry the subscription charge. Please add or re-save your card in the patient portal.

RETRY_SCHEDULED

The system has a saved payment method and will retry the charge later.

What CS should say:

Your payment is scheduled for another automatic retry. You can also pay the invoice from the patient portal if you want to resolve it sooner.

RESOLVED

The recovery payment succeeded.

What happens:

• invoice is paid
• order status is recalculated
• subscription can reactivate if it was paused
• recovery metadata is marked resolved

FAILED_FINAL

The system has exhausted configured retry attempts.

What CS should say:

The automatic retry attempts have been exhausted. We need to review or collect payment manually before the subscription can continue.

Escalate FAILED_FINAL cases to billing/admin operations.

Auto-Retry Behavior

Payment recovery retries are processed by the subscription processor cron.

That same processor handles:

• recurring subscription billing
• payment recovery retries

Important: turning off payment recovery notifications does not stop retry attempts. It only stops the configured automatic email/SMS recovery notices.

Retry behavior:

• failed subscription cycle orders stay in AWAITING_PAYMENT
• retry timing comes from Admin payment recovery settings
• if retry succeeds, order is recovered
• if retry fails enough times, recovery becomes FAILED_FINAL

Payment Method Behavior

The app retries using a compatible saved payment method for the active organization gateway.

If status is NEEDS_PAYMENT_METHOD:

• the system usually skips retry while no compatible method exists
• once patient adds/re-saves a compatible payment method, the processor can retry

If CS sees "No compatible payment method":

• ask patient to add or re-save the card
• confirm the saved card matches the active gateway
• avoid creating duplicate orders

Subscription Pause Behavior

When a subscription renewal payment fails, the subscription may be marked PAUSED.

What that means:

• no new normal cycle orders should be generated while paused
• the recovery order/invoice still needs attention
• successful recovery can reactivate the subscription

How to explain it:

Your subscription is paused because the renewal payment did not go through. Once the payment is resolved, the subscription can continue.

Patient Invoice Payment

Patients can pay outstanding invoices from the patient portal.

If payment succeeds:

• invoice becomes PAID
• order status is recalculated
• payment.succeeded workflow can fire
• Beluga may auto-submit if the order becomes ready for script

If payment fails:

• order remains or moves to AWAITING_PAYMENT
• payment.failed workflow can fire
• patient sees a gateway decline message

CS should check the invoice before creating any replacement order.

Manual Retry From EMR

Staff may be able to retry eligible charges from EMR order tools.

Current retry charge logic is intended for:

• subscription cycle orders
• switch payoff orders

It is not a generic retry button for every manual order type.

If retry is unavailable or rejected, check the order source/context and invoice status.

Recovery Notifications

Configured in:

• Admin -> Settings -> Payment Recovery

Notification settings can include:

• needs payment method email/SMS
• retry reminder email/SMS
• final failure email/SMS
• max retry count
• retry delay schedule
• reminder threshold

Important: notification settings control messages, not whether retries happen.

Workflow trigger:

• payment.failed

Useful workflow fields:

• order.recoveryStatus
• order.retryCount
• order.maxRetryCount
• order.nextRetryAt
• order.recoveryUrl
• paymentRecovery.status
• paymentRecovery.recoveryUrl

What CS Should Check

Before advising the patient, check:

• order status
• invoice status
• payment status
• recovery status
• auto-charge message
• retry count
• next retry date
• subscription status
• saved payment method exists
• active gateway
• whether patient recently added/re-saved card
• whether recovery has reached FAILED_FINAL

Common Patient Questions

Why is my subscription paused?

The renewal payment did not go through. The subscription may pause while payment recovery is active.

Will the system try again?

If a compatible payment method is saved and retries are still available, yes. Retry timing depends on the clinic's recovery settings.

I added a new card. What happens now?

The system can retry once a compatible payment method is available. CS can also check whether a manual retry is available.

Why do I still see an unpaid invoice?

The failed cycle order remains open until payment succeeds. Pay the invoice or update your payment method from the patient portal.

Does disabling notifications mean you will stop charging me?

No. Notification settings only control emails/SMS. They do not stop recovery retry attempts or subscription billing rules.

Should I place a new order?

Usually no. If there is already a recovery invoice, pay or resolve that invoice first. Creating a new order can duplicate billing or fulfillment work.

Troubleshooting

Subscription is paused but patient says they paid

Check:

• invoice status
• latest payment record
• order recovery status
• whether payment was for the correct order/invoice
• whether subscription reactivated

Escalate if invoice is paid but subscription remains paused.

Order is stuck in AWAITING_PAYMENT

Check:

• recovery status
• auto-charge message
• payment method availability
• retry count and max retry count
• next retry date
• gateway decline reason

Recovery status is NEEDS_PAYMENT_METHOD

Ask patient to add or re-save a payment method.

Then check:

• payment method gateway
• default card
• whether retry can run

Recovery status is RETRY_SCHEDULED

Check:

• next retry date
• retry count
• whether patient wants to pay manually now
• whether payment method is still valid

Recovery status is FAILED_FINAL

Escalate to billing/admin operations.

Check:

• number of failed retries
• final notice sent
• subscription status
• whether manual collection or cancellation is needed

Patient paid wrong invoice

Escalate. Do not mark recovery resolved manually unless billing/admin confirms the payment should apply to that recovery order.

CS Escalation Checklist

Escalate to admin/development or billing operations when:

• invoice is paid but order remains AWAITING_PAYMENT
• invoice is paid but subscription remains paused
• recovery status does not match payment records
• patient was charged multiple times for the same recovery order
• recovery reached FAILED_FINAL
• payment method exists but retry says no compatible method
• gateway decline message is unclear
• CS suspects duplicate recovery orders

Include these details when escalating:

• patient name/email
• subscription id
• order number
• invoice number
• invoice status
• latest payment status
• recovery status
• retry count / max retry count
• next retry date, if any
• auto-charge message
• gateway used
• patient-facing message or screenshot