Failed payment schedule runs

A failure may occur in a phase of the payment schedule for different reasons. The type of problem and resolution steps depend on the payment schedule phase.

In this phase, FinDock selects existing installments or generates new installments based on the payment schedule parameters. An error in this phase, like a stalled process due to a timeout, will set the schedule state to Failed.

To determine the cause:

1. Open the failed schedule record and check the Last Status Reason field.
2. Expand the details pane on the schedule path component and check for errors.
3. For admins:
   1. Verify the user who started the payment schedule has the FinDock Payment Operator permission set group assigned and has access to Installment, especially if the Org-Wide Default Sharing for Installment is set private.
   2. If step 2 above reveals a failed Apex job (to fetch or generate installments), use the Job Ud to trace detailed logs or failure reasons.
   3. Review queueable jobs in Salesforce Setup > Apex Jobs to check for failed or incomplete jobs related to the failed payment schedule.
4. Once the issue is resolved, click Back to Scheduled on the schedule’s path and re-run the Generate step. However, you should only do this if you have not modified linked installments or related records that changed the scope of the original run. Create and run a new schedule if the scope changed.

After installments are generated or queried and linked to the payment schedule, FinDock starts processing the payment instructions for those installments. Depending on the payment processor, the instructions are handled as API callouts to the PSP or compiled into a file that is manually transferred to a bank.

When FinDock is the native payment processor, ProcessingHub handles the payment instructions. Errors in the Processing phase can result from stuck processes on ProcessingHub.

Once the Processing phase starts, a job is queued in ProcessingHub, status and subtasks become visible in the details section of the schedule path component. Further details are available in ProcessingHub Manager accessible from direct links in the path details pane.

A payment schedule run may also hang because some other process earlier in the queue has stalled. Use ProcessingHub Manager to monitor processes and initiate retries, which typically resolves the problem.

If the Processing phase stops or otherwise shows an error:

1. Check for errors in the details for the Processing phase of the path component.
2. For stuck (queued) jobs, open it in ProcessingHub Manager and check whether any previous failed jobs are blocking the schedule’s queued jobs.
3. Review the Workflow and Logs Tab the Payment Schedule job details to identify if anything failed.
4. Verify that no installments linked to the schedule were changed after processing started. Particularly deleted related records can cause issues.
5. For admins:
   1. Ensure the integration user for the ProcessingHub connection is active and has the FinDock Integration User permission set group assigned.
   2. Check the failed Workflow tasks in ProcessingHub Manager for more detailed error messages.
   3. If the error is from a workflow task with a data load job, review the details shown in the task. For data load jobs FinDock uses either REST or Bulk API to query or insert data. Check for failed Bulk API queries or inserts from Salesforce Setup > Bulk Data Load Jobs.
   4. If you fix the issue causing the data load job to fail, use the retry buttons in ProcessingHub Manager under the related workflow that failed.
6. If retrying failed jobs is not possible, change the schedule status back to Generated and restart the Processing step.

For payments processed through PSPs, ProcessingHub is not involved. (Gift Aid and Bacs DD through Access PaySuite are exceptions.) Payment instructions to the PSPs are handled within Salesforce using asynchronous Apex Batch Jobs. A Message record is created for each installment for the PSP submission to collect the payment.

Failures during the Processing phase can occur with individual installments, but that doesn’t block the payment schedule like with native payment processing. This is indicated by the schedule status Success with Errors - some (usually most) of the installment collections were successful.

If there are errors during Processing phase:

1. Review the Last Status Reason field on the payment schedule.
2. Expand the details pane on the schedule path component and check for errors.
3. If the schedule status is Success with Errors, check the installments related to the schedule and look for records with Failed status.
4. With failed installments, check the Last Status Reason field for more details.
5. For admins: if no failure details are visible on the payment schedule or installments, review Message records with an Outbound handler to check for errors.
6. Once the errors are resolved, change the status of the uncollected installments to New or Pending recollection so they are picked up by the next payment schedule run.

For payment collection through PSPs, the payment schedule completes the Close phase automatically. Installment updates, like reversals or cancellations, are handled via reconciliation, where PSP notifications are processed through Guided Matching.

For native payment processing (file-based payment collection), however, the Close phase includes an explicit verification step. When a payment instruction file is generated, the payment schedule moves to Pending Verification.

At this stage, the payment operations user must manually confirm the outcome. After uploading the generated collection file to the bank, the user selects either File Accepted for File Rejected.

Selecting File Accepted (either via the schedule path component or by updating the status to Verified) triggers the final closing step which updates the status of all linked installments to Collected. This is managed by ProcessingHub with a job called ClosePaymentSchedule.

If the payment schedule closing fails or appears stuck:

1. Ensure that the correct verification action was selected, File Accepted or File Rejected.
2. Open the ProcessingHub Manager and locate the ClosePaymentSchedule job for the schedule and check if any other failed jobs are blocking it.
3. Verify that no Installments were modified (changed Status, Last Collection Date, Open Amount, etc.) or deleted after the payment instruction file was generated.

If further investigation is needed, FinDock admins can:

1. Open the Workflow and Logs for the ClosePaymentSchedule job job. Check for failed workflow tasks. They may provide additional error details.
2. Ensure that the FinDock Integration User for ProcessingHub has the FinDock Integration User permission set group assigned.
3. If the error is from a workflow task with a data load job, review the details shown in the task. For data load jobs FinDock uses either REST or Bulk API to query or insert data. Check for failed Bulk API queries or inserts from Salesforce Setup > Bulk Data Load Jobs.