Troubleshooting
System Error Codes (1xxx)
System errors indicate internal PayPlus platform issues — not payment rail errors. These appear in the PayPlus application log and may also be surfaced in the System Dashboard under Active Alerts.
| Code | Description | Resolution |
|---|---|---|
1001 | Database connection failure — PayPlus cannot reach the database server. | Verify database server is running. Check payplus.properties DB connection parameters. Review database server logs. Check network connectivity from app server to DB server. |
1002 | Database connection pool exhausted — all database connections in use. | Increase db.pool.max.connections in payplus.properties. Check for long-running database queries or uncommitted transactions in the database. Review JVM heap allocation — insufficient memory causes slow query performance. |
1010 | OFAC screening engine unavailable — compliance screening cannot be performed. | Check the OFAC Screening Service status at Administration > Compliance > Screening Status. Restart the screening engine via payplus-admin.sh restart-compliance. All payments are automatically placed on hold until screening engine is restored. |
1011 | OFAC sanctions list stale — list has not been updated within the configured refresh window. | Trigger a manual list refresh at Administration > Compliance > List Management > Refresh Now. If automatic refresh is failing, check outbound connectivity to the OFAC list endpoint. Review the compliance service log for HTTP error details. |
1020 | License validation failure — PayPlus license file is missing, expired, or invalid. | Verify payplus.lic is present in config/license/. Check the license expiry date at Administration > System > License. Contact your vendor account manager to renew. |
1030 | JVM heap space exhausted — application out of memory. | Increase -Xmx JVM setting (see Installation > Application Server Configuration). Review for memory leaks — generate a heap dump with jmap -dump:format=b,file=heap.hprof <pid> and analyze with Eclipse MAT. Restart the service as a temporary measure. |
1050 | Scheduled job failure — a background processing job (e.g., ACH window processing, list update) did not complete. | Check the PayPlus Scheduler log at logs/scheduler.log. Identify the failing job and its exception. Most scheduler failures are transient — review if the job succeeds on the next cycle. If persistently failing, contact support. |
ACH Connector Errors (2xxx)
| Code | Description | Resolution |
|---|---|---|
2001 | ACH SFTP connection failure — cannot reach the ACH operator SFTP server. | Verify SFTP host/port configuration. Confirm outbound network path to SFTP server is open. Test SSH key authentication manually using ssh -i keyfile user@host. Check if SSH key has expired (ACH operator may require periodic key rotation). |
2010 | NACHA file hash total mismatch — the calculated hash total does not match the control record. | This indicates a data integrity issue in the NACHA file generation. Check logs/ach-connector.log for the batch that generated the mismatch. Do not resubmit the file — contact PayPlus support with the file content for investigation. |
2020 | ACH processing window missed — payment was not submitted before the processing window cut-off. | Payment remains in Approved state. Operations must manually reschedule the payment for the next available window: Payments > Queue > select payment > Reschedule. Inform the originator of the delay. |
2030 | FedACH file rejected — the submitted NACHA file was rejected by FedACH with an error notification. | Review the FedACH rejection notification in the ACH inbound directory. Common rejection causes: invalid ODFI routing number, file format error, duplicate file reference number. Correct the cause and resubmit. Do not resubmit a rejected file without correction — duplicate submission without correction will also be rejected. |
2040 | ACH return file processing error — PayPlus cannot parse an inbound return file from FedACH. | Check file format in ach/inbound/ directory. Verify the file is a valid NACHA 94-character format. If the file is corrupted in transit, contact FedACH support for a retransmission. PayPlus logs the unparseable file to logs/ach-returns.log. |
Fedwire and SWIFT Connector Errors (3xxx / 4xxx)
| Code | Rail | Description | Resolution |
|---|---|---|---|
3001 | Fedwire | FedLine connection timeout — no response from FedLine within configured timeout. | Check FedLine status at the Federal Reserve's FedLine service notification page. If FedLine is operational, verify the FedLine certificate has not expired (certificates must be renewed annually). Check firewall rules for outbound FedLine port. |
3010 | Fedwire | Fedwire message rejected — ISO 20022 message schema validation failed. | Review the rejected message in logs/fedwire-connector.log. Common causes: missing mandatory pacs.008 field (UETR, LEI, creditor address), amount format error, invalid BIC format. Correct the payment data and resubmit. |
3020 | Fedwire | Fedwire daylight overdraft — institution's Fed account has insufficient funds for the payment. | Contact Treasury to fund the Federal Reserve account. The payment will retry automatically when the account has sufficient balance, or can be manually held and resubmitted after funding. Monitor intraday Fed account balance via the Federal Reserve's account management portal. |
3030 | Fedwire | Fedwire submitted after operating hours — payment submitted outside the Fedwire operating window. | Fedwire operates Monday–Friday 9:00 PM ET (prior day) to 6:30 PM ET. Payments submitted outside these hours are held and submitted at the opening of the next Fedwire operating day. No action required — PayPlus will auto-submit at next open. |
4001 | SWIFT | SAA MQ connection failure — PayPlus cannot connect to SWIFTNet Alliance Access message queue. | Verify SAA server is running and accessible from PayPlus app server. Check MQ queue names in SWIFT connector configuration match SAA queue configuration. Verify SAA MQ listener is active on the configured port. Review logs/swift-connector.log for MQ exception details. |
4010 | SWIFT | SWIFT NAK (Negative Acknowledgement) received — SWIFTNet rejected the outbound message. | Review the NAK reason code in logs/swift-connector.log. Common causes: BIC not in SWIFT directory, MT message format error, invalid field 56A/57A correspondent BIC, value date not a valid banking day in the beneficiary country. |
4020 | SWIFT | SWIFT gSRP recall response timeout — no response received from the beneficiary bank for a camt.056 recall request within the SLA window. | Escalate the recall manually via bilateral SWIFT messaging. Escalation procedure: Operations > SWIFT Recalls > select recall > Escalate to Manual. Document the escalation attempt in the payment record for regulatory purposes. |
RTP and FedNow Errors (5xxx)
| Code | Rail | Description | Resolution |
|---|---|---|---|
5001 | RTP | TCH network connection lost — RTP connector cannot reach the TCH network. | Check TCH RTP service status notification (TCH provides a status portal to member banks). Verify TLS certificate for TCH connection has not expired. Review logs/rtp-connector.log. PayPlus automatically queues RTP payments during outage; they will not auto-retry — operations must manually release the queue once connectivity is restored. |
5010 | RTP | RTP payment timeout — Receiving Bank did not respond within the configured timeout window. | Payment status is Timeout — the payment is NOT settled. Notify the initiating customer that the payment did not complete. The customer may retry. Do not automatically retry — verify with TCH whether the original payment was delivered before resubmitting to avoid potential duplicate. |
5020 | RTP | RTP insufficient prefunded balance — TCH joint settlement account balance is too low to process the payment. | Treasury must fund the TCH settlement account via Fedwire transfer to the Federal Reserve Bank of New York. Payment will be rejected until the account is funded. Configure the RTP Balance Low alert to notify Treasury before balance reaches critical threshold. |
5030 | FedNow | FedNow LMT failure — Liquidity Management Transfer from Fed master account to FedNow balance was rejected. | Verify the Fed master account has sufficient balance. Check LMT configuration (threshold and transfer amount) at Administration > Connectors > FedNow. Contact your Federal Reserve Bank district relationship manager if LMT consistently fails. |
5040 | FedNow | FedNow receiving bank not participating — the payment destination bank is not enrolled in FedNow. | Route the payment to an alternative rail. Use the Rail Selection Rules Engine to configure automatic fallback: if Receiving Bank not in FedNow directory → attempt RTP → if not in RTP → route to ACH or Fedwire. Verify the Receiving Bank's FedNow participation status using the Federal Reserve's FedNow participant directory. |
Common Issues and Resolution
Users Cannot Log In After LDAP Configuration Change
If users cannot log in after an LDAP configuration change, verify:
- The Bind DN credentials are correct and the service account is active in LDAP.
- The Base DN path is correct — a typo in the Base DN causes all LDAP searches to fail silently.
- The LDAP server is reachable from the PayPlus app server on port 636 (LDAPS). Run:
openssl s_client -connect ad.bank.internal:636to verify TLS connectivity. - The User Search Filter uses the correct attribute for your LDAP implementation (
sAMAccountNamefor Active Directory;uidfor OpenLDAP). - At least one local System Administrator account remains active as a fallback while LDAP issues are investigated.
ACH Return Rate Alert Triggered
When an elevated return rate alert fires:
- Navigate to Operations > Reports > ACH Return Report. Filter for the past 7 days.
- Identify the dominant return reason codes. High R05/R07/R10 rates indicate unauthorized transaction issues — review the originator's customer authorization procedures.
- If the return rate for unauthorized transactions (R05, R07, R10, R29) exceeds 0.5%, NACHA requires the ODFI to identify and potentially suspend the originator. Contact your NACHA compliance representative.
- Document the investigation and corrective actions in the PayPlus Compliance Notes for the affected ACH batch.
FedNow Payments Rejected After Weekend
FedNow payments may be rejected Monday morning if the FedNow liquidity balance was not pre-funded before Fedwire close on Friday. To prevent this:
- Make sure the LMT (Liquidity Management Transfer) is configured and tested before each weekend.
- Review historical weekend FedNow volume and set the LMT threshold at 150% of average weekend peak to account for volume spikes.
- Pre-fund the FedNow position with a Fedwire transfer before 5:00 PM ET Friday.
- If payments were rejected over the weekend, contact affected customers and resubmit the payments on Monday morning after confirming the liquidity position is adequate.
Log File Locations
| Log File | Location | Contents |
|---|---|---|
| Application Log | $PAYPLUS_HOME/logs/payplus.log | General application events, startup/shutdown, configuration loading errors |
| Payment Processing Log | $PAYPLUS_HOME/logs/payment-engine.log | Payment lifecycle state changes, validation results, submission confirmations |
| ACH Connector Log | $PAYPLUS_HOME/logs/ach-connector.log | ACH file generation, SFTP/FedLine transfer activity, return file processing |
| Fedwire Connector Log | $PAYPLUS_HOME/logs/fedwire-connector.log | FedLine session activity, pacs.008 submission/response, error details |
| SWIFT Connector Log | $PAYPLUS_HOME/logs/swift-connector.log | SAA MQ activity, message submission, ACK/NAK processing |
| RTP Connector Log | $PAYPLUS_HOME/logs/rtp-connector.log | TCH network session, pacs.008 submission, acceptance/return responses |
| FedNow Connector Log | $PAYPLUS_HOME/logs/fednow-connector.log | FedLine FedNow session, LMT activity, payment submission/settlement |
| Compliance Log | $PAYPLUS_HOME/logs/compliance.log | OFAC screening results, hold queue actions, list update events |
| Scheduler Log | $PAYPLUS_HOME/logs/scheduler.log | Background job execution — ACH windows, list updates, report generation |
| Audit Log | Database (PayPlus Audit Schema) — not a flat file | All user actions, payment state changes, configuration changes |
Log files rotate daily. Configure log retention at Administration > System > Log Management. Default retention: 30 days of rolled log files. For compliance purposes, archive logs to your institution's long-term log storage (SIEM, cold storage) before deletion.
Support Escalation
| Issue Type | First Contact | Escalation |
|---|---|---|
| PayPlus application errors (1xxx codes) | PayPlus Technical Support Portal — submit ticket with error code, log excerpt, and system snapshot (payplus-admin.sh support-bundle) | PayPlus support escalation (Severity 1: phone escalation available 24/7) |
| FedLine / Fedwire connectivity (3xxx codes) | Your Federal Reserve Bank district's FedLine support line | Federal Reserve Bank district relationship manager |
| FedNow connectivity (5030–5031) | Federal Reserve FedNow support line (provided in FedNow Service Agreement) | Federal Reserve Bank district relationship manager |
| TCH RTP connectivity (5001–5020) | TCH RTP participant support desk (requires TCH member institution credentials) | TCH account relationship team |
| SWIFTNet / SAA issues (4xxx codes) | SWIFT Customer Support (24/7 for connectivity issues) | SWIFT relationship manager |
| OFAC / compliance questions | Internal BSA/AML Compliance Officer | OFAC hotline: 1-800-540-6322 (for urgent sanctions questions) |
Support Bundle
Before contacting PayPlus Technical Support, generate a support bundle:
$PAYPLUS_HOME/bin/payplus-admin.sh support-bundle. This captures logs, configuration (with passwords masked), thread dumps, and system information in a single archive. Attach the bundle to your support ticket to accelerate resolution.