CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

Payment Review and Recovery

CartThrob Subscriptions 6 keeps a payment operation under review when a gateway result is uncertain or when the gateway completed the payment but CartThrob could not finish the related Subscription, Order, or permission changes. The review prevents a second charge or refund while the first result may already have succeeded.

Find subscriptions that need review

Open CartThrob Subscriptions > Subscriptions and select Needs review from the Payments filter. Affected rows display Review independently of the Subscription’s Open, Pending, Hold, or Closed status.

Open the Subscription to see its Payment Review panel. While the review is active:

  • normal Subscription fields are read-only and the ordinary Save button is unavailable;
  • Charge Next Billing and Cancel are unavailable;
  • automatic rebilling, cancellation payments, and paid plan changes are blocked;
  • the linked saved card can’t be deleted, from the storefront or CartThrob > Vaults, even after the Subscription is Closed or its access has ended (see When deletion is refused);
  • the panel shows the operation, expected amount and currency, gateway, provider state and reference when available, related Order, saved prior state, timestamps, and the latest safe provider message;
  • when CartThrob has a matching reconciliation event, a read-only CartThrob reconciliation evidence section shows its reason, provider and expected amounts, references, last-detected time, and occurrence count.

A Pending status alone does not prove that an older Subscription has recoverable payment evidence. A cancellation refund can also need review while the Subscription remains Open or after its paid-through date closes it. Use Needs review in the Payments filter and the review panel instead of relying on status alone.

Check the processor result

Do not retry the payment, edit the Subscription, or change its status before completing these checks:

  1. Open the Subscription’s Payment Review panel and record the operation, expected amount and currency, gateway, related Order ID, approximate time, and every saved provider reference.
  2. Open the related CartThrob Order. Do not use Complete paid order — no charge as the only recovery step; that action does not complete Subscription bookkeeping.
  3. Sign in to the payment processor’s merchant dashboard.
  4. Search by the provider reference first. If no reference was returned, search by amount, currency, approximate time, customer details, and CartThrob Order ID or description when the processor stores it.
  5. Confirm whether the transaction is a charge or refund, its final state, amount, currency, and whether it was later voided or reversed.
  6. If the result is still pending or uncertain, leave the Subscription under review. Contact the processor rather than submitting another payment.

Always resolve a Subscription incident with Resolve payment review on the Subscription. CartThrob’s separate general payment reconciliation screen may contain the same provider event, but its Mark handled action records only a core audit decision. It does not renew, restore, cancel, unlock, or otherwise complete the Subscription. Do not use that general action for a Subscription incident.

Legacy or incomplete reviews

The panel labels a review Legacy or incomplete payment review when the Subscription does not contain enough saved facts to apply a safe recovery action. It lists the missing or changed information and keeps the Subscription locked.

Common causes include:

  • an older explicit payment-review marker or claim without its prior status, prior Order, amount, currency, or intended operation;
  • a Subscription, Order, or replacement Subscription changed after the claim;
  • a partial payment, different currency, chargeback, or other result that does not match the saved operation.

Record the Subscription ID, Order ID, gateway result, provider reference, amount, currency, and the missing or mismatched fields shown in the panel when investigating the incident. Do not change the status or detach the Order to bypass the review.

Resolve a verified processor result

Choose Resolve payment review only after the processor result matches the saved operation, amount, currency, customer, and Order. Every resolution requires a note describing what you verified. CartThrob rechecks the active attempt and its related records under a lock before it saves anything.

The resolution updates local records only. It does not contact the gateway, repeat a charge, issue a refund, or send a reversal.

Resolving a reviewed payment does not dispatch CartThrob’s configured rebill success or failure notification. Contact the customer separately when the verified outcome changes their access, cancellation, or retry status.

Payment completed

Choose Payment completed when the processor proves that the exact saved charge or refund completed. Enter the provider reference if CartThrob did not receive it. CartThrob refuses a reference already owned by another Order and refuses a refund reference that is the same as the original payment reference.

CartThrob then performs the saved local work:

  • an automatic rebill completes its Order, renews the Subscription, and applies its normal occurrence and permission behavior;
  • Charge Next Billing completes its Order and applies the renewal choice made for that charge;
  • a cancellation balance charge completes its Order and cancellation;
  • a plan-change charge or refund closes the original Subscription, activates the replacement, completes the replacement Order, and applies the replacement Plan permissions;
  • a cancellation refund updates the original Order’s remaining recorded total and closes the Subscription.

Payment did not complete

Choose Payment did not complete only when the processor proves that no charge or refund completed. CartThrob marks an attempted charge or replacement Order failed where applicable, restores the saved prior Subscription state and Order link, and clears the active review. A reviewed automatic rebill enters the normal retry policy once; this resolution does not dispatch the retry.

For a cancellation refund, use Refund did not complete instead. See Cancellation refund reviews.

Payment was reversed

Choose Payment was reversed when the processor proves that the payment completed and was later reversed or voided. Enter the original completed payment reference if it is not already shown. If the processor issued a separate reversal or void reference, enter it as the reversal reference.

For a charge, CartThrob gives the attempted Order the store’s configured Reversed status and restores the safe prior Subscription state. A reversed automatic rebill enters the normal retry policy once. CartThrob records the outcome but does not send another reversal. For a cancellation refund, use Refund was reversed; see Cancellation refund reviews.

After confirmation

Reopen the Subscription and related Order and verify their status, dates, amount, and plan or permission result. If CartThrob reports that the Subscription was updated but reconciliation could not be synchronized, submit the same verified result again from the form shown. That retry only updates the CartThrob reconciliation record; it does not repeat the local Subscription or Order changes.

The resolution screen can return these responses:

Response Meaning and next step
Payment review resolved CartThrob saved and verified the local result. Reopen the Subscription and Order to confirm the expected outcome.
The Subscription was updated, but its CartThrob reconciliation record could not be synchronized. The local result is final. Submit the same outcome again from the displayed form to retry only the reconciliation update.
This subscription is temporarily busy. Wait a moment and try again. Another request holds the short-lived operation lock. Wait, reload the review, and try once.
The payment review changed. Reopen it and check the current details. The saved attempt no longer matches the submitted form. Reload and use the current evidence.
This payment review does not contain enough verified information for an automatic resolution. CartThrob cannot safely reconstruct the result. Keep it under review and provide the displayed evidence to support.
The local Subscription records could not be updated. The payment review remains locked. CartThrob rolled back the attempted local change. Correct the database or configuration problem, then retry the same verified result.
Enter the provider reference required for this result. Supply the real completed payment or refund reference shown by the processor.
Enter a refund or reversal reference that differs from the original payment reference. The gateway returned or you entered the original charge reference. Enter the processor’s distinct refund or reversal reference.
That provider reference already belongs to another Order. Recheck the processor result and related Order. CartThrob will not move a reference already recorded for another Order.

Cancellation refund reviews

A refund requested during cancellation can need review when the gateway’s answer is uncertain. The review panel shows Renewal: Stopped and Access ends no later than the paid-through date. The Subscription never renews again, whatever outcome you record. Only the end of access changes.

Outcome to record When Result
Refund completed The processor shows the exact refund completed. CartThrob records the refund against the original Order, closes the Subscription, and ends access immediately.
Refund did not complete The processor shows no refund was made. The original Order stays paid. Renewal stays stopped, the saved card is detached, and the customer keeps the paid time that remains.
Refund was reversed The refund completed, then was reversed or voided. Same as Refund did not complete: renewal stays stopped and only the remaining paid time continues.

These labels appear only on cancellation-refund reviews. Renewal and charge reviews use Payment completed, Payment did not complete and Payment was reversed. Manual refunds use Manual refund completed and Refund not issued (see below).

Access never outlasts the paid-through date while a refund is under review. If the review is still unresolved when that date passes, access ends, and the review stays listed under Payments > Needs review until you record the result. The rebill command later changes the status to Closed, but access has already ended. See Cancellation refunds for a worked example.

Manual cancellation refunds

Some gateways require a refund in the processor dashboard instead of supporting CartThrob’s automatic refund call. Prepare the manual work in CartThrob before issuing the refund:

  1. Open the Subscription’s Cancel screen, confirm cancellation, choose the refund option, and submit the form.
  2. When CartThrob reports that the gateway requires a manual refund or has no callable refund method, choose Prepare manual refund on that screen. Do not first cancel without a refund.
  3. CartThrob verifies the expected refund, original payment, saved Vault, Order, currency, and paid-through date. It saves an active review without contacting the gateway. The review blocks renewal and other payment actions while preserving access through the paid-through date.
  4. Open the Subscription’s Payment Review panel and note the exact expected amount, currency, original payment reference, and Order ID.
  5. Sign in to the processor, find the original payment, issue the exact refund, and wait until the processor reports a final result.
  6. Return to Resolve payment review. If the refund completed, choose Manual refund completed, enter the new refund reference and a note, and confirm. Do not reuse the original payment reference. CartThrob records the refund and completes the local cancellation without another gateway request.
  7. If you did not issue a refund, choose Refund not issued and enter a note. CartThrob applies the ordinary no-refund cancellation, stops future renewal, and preserves access through the paid-through date.

If the refund remains pending or cannot be verified, leave the review active. Access ends at the paid-through date, but the unresolved review remains visible until you record the processor result. The saved Vault stays attached while the review is active so the verified outcome can still be applied. If an earlier no-refund cancellation already detached the Vault, CartThrob refuses manual-refund preparation because it cannot reconstruct the verified claim safely.

The frontend cancel_sub_form continues returning its customer-safe contact-the-store message and does not create a manual-refund claim. The store operator must prepare and resolve the manual refund in the Control Panel.

Outcomes that must remain under review

Leave the record unchanged and contact the processor or CartThrob support when:

  • the processor outcome is still pending or unknown;
  • the processor cannot locate the transaction conclusively;
  • required recovery facts are missing;
  • the current records no longer match the saved operation;
  • the amount or currency differs;
  • the result is a partial payment, chargeback, or unrelated adjustment;
  • a local database or configuration problem prevents CartThrob from saving and verifying the intended resolution.

The review is a payment-safety guard. Clearing it without the matching Order, Subscription, access, and accounting changes can cause duplicate payments or incorrect customer access.