Callbacks are optional, server-side, HTTPS webhook notifications sent by PayNearMe to inform clients of specific events that can occur during a transaction's lifecycle. Callbacks work with any integration method and provide notifications about transaction events and give you the ability to control payment remittance to support regulatory and business processes. Use callbacks with any payment type to securely communicate transaction events and efficiently process payments. PayNearMe offers the following callback services.

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.

Available Customizations

Clients can customize the behavior of their callbacks to improve the performance thresholds of their backend systems. High-volume clients may want to skip callbacks for certain transactions (e.g., like recurring autopay payments), limit the number of allowable callback errors or retries, or institute a Hold Window for callbacks for their end-of-day reconciliation.

Skipping Callbacks for Certain Transactions

Clients can opt to skip callbacks for certain types of transactions. These transactions include payments that originate from an API call, recurring autopay payments, and scheduled, one-time payments. All scheduled payments (both recurring and one-time) are staged at 12:00AM PST and then run before the start of business on the payment date.

🎯

Best Practice

PayNearMe recommends skipping callbacks (especially the Authorization and Confirmation callbacks) for both recurring autopay payments and scheduled, one-time payments to avoid server performance issues when PayNearMe stages and runs all scheduled payments in the early morning of the payment date.

The following chart displays which callbacks can be skipped for API or scheduled transactions:

Customizing Error and Retry Counts

All callbacks must receive a response within 10 seconds; otherwise, PayNearMe retries the callback once per minute until we receive an acknowledgment from the client. After 40 callback failures/errors in Production or 100 callback failures/errors in Sandbox, PayNearMe suspends the callback. Clients have the option of raising or lowering the error count threshold to make callback troubleshooting easier to manage. PayNearMe recommends not raising the error count threshold to over 100 as higher values can lead to callback problems going unnoticed.

All callbacks, including retries, must be acknowledged by the client after failures and/or unsuspension. For high-volume clients who do end-of-day processing, these acknowledgments can slow down performance and create duplicate payment records that then need to be manually reconciled. To prevent this, clients can limit the number of retry attempts for a callback without suspending the callback all together. This gives their server time and processing power to respond to callback retry attempts and prevent the possibility of duplicate payment records.

The following chart displays which callbacks can have custom error and retry counts:

Setting Up a Hold Window

Another option for high-volume clients like ISVs doing end-of-day processing is instituting a callback hold window. During a hold window callbacks are queued and only sent after the window ends. While callbacks are in a pending state during the hold window, they do not count toward auto-suspend thresholds. Only after they are sent by PayNearMe do they begin to count toward auto-suspend logic.

The hold window can be configured to end at either the scheduled end time each day or via a successful callback to a Ping endpoint set up on the ISV's server. Ping callbacks are used to verify the availability of the ISV's server to handle a large volume of callbacks. At this time, a ping callback configuration is required for an ISV client to use the hold window feature.

Your PayNearMe Technical Account Manager can configure your hold window, which is run each day. You will need to define:

• The start time of the hold window
• The end time of the hold window
• The delay (after the start time) in minutes at which PayNearMe should begin pinging your server to verify its availability
• The unique URL of the ping endpoint for each child site under the ISV parent site

Hold windows can be set up for the following callbacks: