Troubleshooting Callback Errors
To ensure you receive timely notifications about API and callback issues, PayNearMe has built a robust communications platform that emails you after every error, timeout, or status alert. Most of these notifications are initiated from one-off issues on the client side, such as server timeouts, DNS updates, or maintenance windows. These issues typically resolve on their own and can be ignored; however, some errors may require intervention by the you and/or PayNearMe to stop or prevent larger, more urgent problems that can interrupt your services.
This topic details the common alerts you may receive and what actions you can take to mitigate their impact.
Callback Error Notifications
Most callback error emails can be ignored when you receive them in low-volume batches (i.e., less than 5 per error). Most callbacks that error out are retried by PayNearMe until they receive a non-error response from your server. If you start receiving frequent callback error emails, you can access detailed callback logs in the PayNearMe Business Portal (Developer > Call Logs > [Callback Name]). Accessing the logs requires Admin permissions.
To view the details of a callback error or failure, click the row on which it displays.
If you start receiving high-volume callback failure messages, you will need to ensure your callback server is online and working; otherwise, PayNearMe will suspend that callback and you will need to manually reset it in the Business Portal.
Callback Retry Policies
All callbacks from PayNearMe must receive a response from the client’s server. This is especially true once the payment is complete, and funds have moved.
Clients must respond to callbacks within 10 seconds of receipt.
Customized Timeouts
Ten seconds is the default timeout, but can be changed for the your convenience.
If the acknowledgment response is not received within 10 seconds, PayNearMe retries the callback once per minute until one of the following occurs:
- PayNearMe receives a response for each callback it has issued—including retry duplicates.
- Forty minutes have elapsed with no response. After 40 consecutive failures of duplicate callbacks (inclusive of the original callback), PayNearMe suspends that callback's configuration for the site. Either you (via the Business Portal) or PayNearMe must then manually reset the callback to resume operations. PayNearMe will resend all the duplicate callbacks that did not receive a response. Clients must respond to these callbacks to avoid re-suspension.
Authorization Callbacks
Authorization Callbacks are not retried. If an error or timeout response is returned, the transaction is automatically canceled/declined and a receipt provided.
Sandbox Timeouts
The Sandbox environment allows for 100 consecutive failures (inclusive of the original callback) before callback suspension.
Callback Error Messages
Generally, the following errors will trigger callback retries:
| Error | Description | Fix |
|---|---|---|
| 400 Bad Request | This code occurs when the client request is invalid or cannot be understood by the server for issues such as malformed syntax or invalid message framing. | If you receive multiple 400 errors, try the following solutions:
|
| 401 Unauthorized | This error code occurs when the server requires authorized credentials to access the resource and the client has provided a bad/expired credential or token. | If you receive multiple 401 errors, try the following solutions:
|
| 403 Forbidden | The 403 error code occurs when your server fails to process a valid request from PayNearMe or any known client because you've restricted permissions to access the resource. | If you receive multiple 403 errors, try the following solutions:
|
| 404 Not Found | A 404 error code occurs when your server cannot find the resource requested by PayNearMe, such as a missing ID or Loan Number. The resource could have been removed from your server or its URL changed or malformed. | If you receive multiple 404 errors, try the following solutions:
|
| 500 Internal Server Error | 500 is a generic error code that indicates the server does not know how to manage a request. It can occur from any of the following issues:
| For persistent 500 errors, you should check your server logs for specific error messages to identify the root cause (e.g., an update has changed the character encoding of certain identifiers and now the server cannot convert them). If this doesn't work, you can take more advanced troubleshooting steps like the following:
|
| 502 Bad Gateway | 502 is another generic error that indicates your server received an invalid response from another server that was working as a gateway or proxy. It can occur for the following reasons:
| If you receive multiple 502 errors, you should begin troubleshooting by checking the server logs for specific error details. If you cannot identify the root cause from the server logs, try the following:
|
| Timeout: Execution Expired | This error occurs when PayNearMe sends a callback to your server and the request times out. | Multiple timeout errors indicates an issue that should be investigated by your IT Team. Start by checking your server logs to determine which actions are causing timeouts and then consider optimizing the underlying code or database queries that are taking too long to execute. You may also consider adjusting your timeout settings to give certain actions more time to execute. |
| XML Parsing Error; Response Error in XML | XML errors occur when your server encounters an issue interpreting the XML callback request from PayNearMe or sends an invalid XML response. These errors can be caused by invalid syntax, missing or incorrect tags, encoding issues (e.g., incorrect character encoding used), or incompatible document type definitions. | If you encounter multiple callback failures because of an XML parsing issue, you will need to work with your IT Team to investigate the root cause of the errors. This may include using XML validation tools and XML editors with syntax checking and debugging tools to help identify and fix parsing issues. |
| No Response | A 'No Response' error indicates that one or more servers are offline or non-operational. | Review your server URL to see if it’s up and operational. If your server is online and able to receive messages, contact PayNearMe Support to ensure the callback server is up and operational. |
| Suspended | A suspension email indicates that multiple callback errors have occurred and the services for that callback have been suspended. | Once a callback has been suspended, you will need to manually reset it in the Business Portal. Before resetting, verify that your callback services are online and have a valid SSL certificate. Once you reset the callback, PayNearMe will automatically re-send the callback and the queued callback retries. |
Resetting Suspended Callbacks
Suspended callbacks can be reset manually by an Admin in the Business Portal. To reset your callbacks, complete the following steps:
-
Log in to the Business Portal and select Configure.
-
Click the Configure and Status button under the Callbacks section.
-
Find the callbacks that have been suspended. A reset checkbox displays under each suspended callback. To view the callback errors, click Show Failures under the suspended callback.
-
Check the Reset Callback box and then click Update.
-
Once the callback has been successfully reset, the Configure page will display with a "Callbacks Updated" message to confirm the reset.
Updated 4 months ago