Troubleshooting

This document covers the end-to-end troubleshooting for the Payment Connect integration. It is intended for administrators, support engineers, and developers diagnosing issues in production or sandbox environments.

Integration Architecture Summary

The Payment Connect integration follows a hybrid architecture, processing synchronous transactions in real-time while relying on asynchronous batches and webhooks for recurring billing and ACH settlement.

Prerequisites and Configuration Checklist

Before diagnosing any issue, verify the following are correctly configured in the org:

Active Payment Gateway

Check that the credentials are added on the Payment Gateway Configuration component located on the cm_finance__Payment_Gateway__c record. Verify that it displays "Gateway Configured" in green. If the gateway is disconnected or is not marked as active, fill in all the required credentials and click Connect on that component to establish the connection.

Remote Site Settings

Ensure all gateway endpoint domains (e.g., https://api.actumprocessing.com, https://api.fiserv.com) are registered under Setup → Remote Site Settings. Missing entries cause callout failures with no descriptive error surfaced on the record.

Webhook URL Registration

For ACH processing (especially with Actum), the Salesforce webhook endpoint is typically:

https://<your-org-domain>.secure.force.com/services/apexrest/cm_finance/actum/return/

This URL must be registered in your gateway's merchant portal as the callback URL. If the webhook domain changes (e.g., after a sandbox refresh), ACH payments will remain stuck in "Accepted" status.

Issue 1: No Active Payment Gateway found

Symptom: The Payment Console will show warning that there are no active payment gateway found in the org.

Diagnostic Steps:

• Root Cause — No Active Gateway: The component queries cm_finance__Payment_Gateway__c for an active, default gateway. Ensure at least one gateway record has Is_Active__c = true.

Issue 2: Submission Fails Immediately (Status = Failed)

Symptom: Clicking "Process Payment" results in a red error message, and the cm_finance__Payment_Transaction__c record is created with Status = Failed.

Diagnostic Steps:

1. Open the Payment_Transaction__c record and inspect the Gateway Response Code and Gateway Response Message fields.

2. Root Cause 1 — Authentication Failure: If the response message indicates "Unauthorized" or "Invalid Credentials", the API keys in your Payment_Gateway__c record are invalid, expired, or belong to a different environment (e.g., Production keys in a Sandbox).

3. Root Cause 2 — Missing infomation: If there is some missing information like not provded full name (only the first name) then the status will also be failed with error message on payment transaction record.

4. Root Cause 3 — Card/Bank Decline: A response code like "Decline" or "Incorrect Account" means the gateway successfully received the request but the customer's bank rejected it. This is expected behavior; instruct the customer to use a different payment method.

Issue 3: ACH Payment Stuck in "Accepted" Status

Symptom: An ACH transaction was processed days ago but the Payment_Transaction__c status has not moved to "Settled" or "Failed".

This almost always involves the webhook pathway or the status refresh batch.

• Step 1 — Verify Webhook Delivery: Check the gateway portal (e.g., Actum). If the transaction is settled there, the webhook failed to reach Salesforce.

• Step 2 — Check Site Guest User Permissions: Webhooks are received via a public @RestResource endpoint on your Salesforce Site. Go to Setup → Sites → Public Access Settings → Apex Class Access and confirm the Webhook_ActumReturnHandler class is enabled. Also ensure the Site Guest User has Read/Write access to the Payment_Transaction__c object.

• Step 3 — Run Status Refresh Batch: If webhooks are lost, you can manually force a sync by executing the status refresh batch via Developer Console:

  Database.executeBatch(new cm_finance.BatchGetPaymentTransactionStatus(), 50);
  

Issue 4: Recurring Payments Are Not Generating

Symptom: A customer has an active cm_finance__Recurring_Payment__c record, but the system is not automatically generating new Payment_Transaction__c records on the "Next Payment Date".

• Root Cause 1 — Batch Not Scheduled: Recurring billing requires BatchRecurringPaymentProcess to run daily. Go to Setup → Scheduled Jobs and verify this batch is scheduled to run (preferably early morning, e.g., 2:00 AM).

• Root Cause 2 — Missing Payment Method: The Recurring Payment record must have a valid lookup to a cm_finance__Payment_Method__c. If the stored token was deleted or expired, the batch will skip the record.

• Root Cause 3 — Next Payment Date in Past: If the batch was turned off for a few days, the Next_Payment_Date__c might be in the past. Ensure your batch logic is configured to catch up on missed dates, or manually advance the date to today.

Issue 5: Payment Request Link Shows "Unauthorized" or Fails to Load

Symptom: A customer receives a Payment Request email, but clicking the "Pay Now" link opens a Salesforce error page or a blank screen.

• Root Cause 1 — Site Inactive: Navigate to Setup → Sites and ensure the Payment Connect Experience Cloud site or Force.com site is "Active".

• Root Cause 2 — URL Mismatch: Check Custom Metadata Payment_Guru_Common_Settings__mdt. If PaymentRequest_SiteURL contains an old Sandbox URL, the email templates will generate broken links. Update it to the current environment's Site URL.

Debugging Workflow (Quick Reference)

Transaction Status = Failed (Immediately)
│
├─ Gateway Response is Blank?
│   ├─ YES → Callout never reached gateway.
│   │         Check: Remote Site Settings.
│   │         Check: Apex limits or unhandled exceptions in Developer Console.
│   └─ NO  → Callout reached gateway.
│             Check: Gateway Response Code (e.g., Invalid Auth vs. Card Declined).
│
Transaction Status = Accepted (For 10+ Days)
│
├─ Payment Method is ACH?
│   ├─ YES → Webhook missing.
│   │         Check: Gateway Portal for actual settlement status.
│   │         Check: Site Guest User Apex Access for Webhook listener.
│   │         Workaround: Run BatchGetPaymentTransactionStatus.
│   └─ NO  → Credit Card Authorization not captured.
│             Check: BatchCaptureScheduledPayment is scheduled to run.

Relevant Apex Classes Reference

Relevant Objects Reference