Skip to content

Failed payment intents

Problem

With online payments, issues can arise at different points when accepting payments. For example:

  • Payer encounters an error while filling out an online payment form.
  • Payment setup fails, taking the payer to failure URL redirect.
  • Payment created by a service agent appears successful, but the expected records are missing.

Resolution

Errors can occur for various reasons, for instance:

  • Missing permissions or restricted field access
  • Incorrect or incomplete data in the payment intent
  • A customization triggered on a record created or updated through Guided Matching, such as a follow-up flow for a failed payment

To correct common issues with payment intents:

  1. Check that the required permissions and sharing are correctly configured and assigned.
  2. Go to FinDock Setup > Connect and check that WebHub and ProcessingHub connections are okay.
  3. Check if WebHub was recently disconnected and reconnected. This can temporarily disrupt PSP notification handling.
  4. If all of the above are in order, proceed with the root cause analysis outlined below.

Root cause analysis

Step 1 - Check inbound reports

Start your investigation with inbound reports. New payments should always result in an Inbound Report record with type PaymentIntent and subtype Default. FinDock provides a ready-to-use list view for the Inbound Reports tab called “Action Required” which shows records with the following statuses:

  • Error
  • Failed
  • Guided Review

Monitoring this list view regularly helps you detect failed or incomplete processes early. Helpful Inbound Report fields and Guided Review components include:

  • Guided Matching / Review Component
  • Guided Matching Progress Component
  • Guided Matching Error field
  • Guided Matching Log field

You can also use Global Search in Salesforce to locate relevant Inbound Report records related to a payment intent by searching with the Payment Intent ID or transaction timestamp.

Step 2 - Check logs

If no inbound report is found for the expected payment intent, the next step is to check the Log records. If you haven’t already, create a tab for the Log object (cpm__Log__c) and look for logs with type Error. If no inbound report was created, check for logs with origin ApiException. These records often reveal issues that prevented an inbound report from being created.

The Message field on the log contains details of the error, helping you pinpoint where the problem originated. If the log message isn’t clear, your administrator can review related records or triggers for more context.

Step 3 - Check messages

If you have located problematic inbound reports, but logs did not clarify the root cause of the issue, move on to Message records. If you haven’t already, create a tab for the Messages object (cpm__Message__c) and look for records with:

  • Status: Failed
  • Type: Inbound
  • Handler: cpm.GuidedMatchingJob or [prefix].NotificationGatewayHandler (prefix is processor-specific, like phstr for Stripe)

Check the Failure Reason field (under the Error section) for details on why the process failed. If the message or failure reason isn’t clear, a system administrator can review the related configuration or handler class for further details.

Step 4 - Resolve root cause

By following this order, Inbound Report Log Message, you can systematically trace where a payment acceptance process stopped, identify and resolve the root cause.

If after investigating the root cause is still unclear, please contact FinDock Support and be sure to include:

  • Description of the issue
  • Summary of investigation findings