Skip to content

Failed online reconciliation

Problem

Records, like installments, mandates, payment profiles and contacts/accounts are updated through inbound reports created from PSP notifications. These are matched and reconciled against Salesforce data using Guided Matching.

There are many potential problems that lead to failed inbound report processing. The most common problems typically involve Salesforce permissions or org-specific customizations that are triggered during Guided Matching rule execution.

Resolution

Troubleshooting these inbound reports follows the same approach as payment intents:

  1. Review inbound reports for “Action Required” states.
  2. Open the problem record and review the details to understand the root cause. Focus on the following key fields and components:
    • Guided Matching Error field
    • Guided Matching Log field
    • Guided Matching / Review Component
    • Guided Matching Progress Component
  3. Check for the most common failure reasons:
    • A validation rule triggered on a record created through Guided Matching
    • Missing permissions or restricted field-level access
  4. Continue to Message records if no clear reason was identified through inbound reports.
  5. Check for messages with status Failed and type Inbound.
  6. Review Failure Reason field to determine possible next steps and resolution.
  7. Where relevant, check ProcessingHub Manager (see below).

For some payment methods and PSPs that use files, inbound reports are created through ProcessingHub. This includes:

  • Files automatically pulled from the bank or PSP file server endpoint
  • Certain files types manually uploaded to Chatter

In these reconciliation scenarios, use ProcessingHub Manager to help identify problems:

  1. Open ProcessingHub Manager and review the jobs related to file extraction. Check if any other failed jobs are blocking queued extract jobs.
  2. If the extraction task itself failed, the error message usually indicates which data or element in the file caused the problem.
  3. Expand data load jobs and check for error messages.
    1. If the issue is clear and you can take corrective action (e.g., update data), go ahead and fix it.
    2. If not, an admin user should review the error details and handle the failure.
  4. For admins: Some extract operations are handled as data load jobs. If an error refers to a Bulk Data Load Job, use the Bulk Data Load Job ID link to navigate directly to Salesforce Setup > Bulk Data Load Jobs for deeper investigation and troubleshooting.