A timeout can occur when:

1. 1
   A payment processor takes too long to respond to a request.
2. 2
   A general request timeout occurs due to technical or unknown reasons within Primer's infrastructure.

In API ≤v2.3 processor timeouts were included within a more general error decision type of Application Error. This included processor timeouts, processor errors and on rare occasions, internal Primer timeouts.

Starting from API 2.4, processor timeouts will be split into their own error decision type of Gateway Timeout, and Application Error now only includes processor errors and on rare occasions, internal Primer timeouts.

Timeout Length

Starting from API 2.4, our payment API has a maximum timeout value of 90 seconds. Previously, when using API ≤v2.3, it was 25 seconds.

Why 90 Seconds?

90 seconds allows sufficient time for external processors with long response times to handle requests. For context, most processors have a maximum timeout allowance between 60 and 70 seconds. The additional buffer accommodates any internal Primer operations, minimizing synchronization issues when external processor timeouts occur.

If a request to a processor times out, the payment will retain its latest status. This means an authorization will remain PENDING, a capture request will stay AUTHORIZED, a refund request on a captured payment will stay SETTLED, and so on. This is to allow any potential recovery or updates, as a FAILED payment cannot be recovered.

How You Should Handle Processor Timeouts

1. 1

   Processor Timeouts (Gateway Timeout)

   A Gateway Timeout indicates that the processor did not respond in time. In this case, you may verify the status of the authorization directly with the processor (via their dashboard or API). Some processors provide search endpoints to check the status of an authorization using your reference IDs.

   Note: This behavior varies by processor. For instance, Stripe notes that processor timeouts rarely result in actual authorizations, but this is not guaranteed across all providers.

2. 2

   General Request Timeouts (Application Error)

   Timeouts internal to Primer can theoretically occur at any point in the payment flow. They are however very rare, and the vast majority of payments with an Application Error will be due to an issue on the payment processors side. In this situation you can review the processor Error Message for details on what has occurred.

What Happens Beyond 90 Seconds?

When a payment takes longer than 90 seconds to process, the request is terminated, and the result is considered a timeout. At this point:

• For processor timeouts, you can attempt to reconcile manually by checking the processor's system for the status of the authorization.