Transaction Timeout Guidance {#timeouts-intro} ============================================== This topic provides guidance for handling scenarios in which a payment request submitted to `Cybersource` does not return a definitive status because of a timeout or other communication failure. It focuses on the most common timeout scenarios and describes the supported mechanisms for determining the final transaction status. This guidance helps you minimize the operational and financial risks associated with an uncertain transaction status. It addresses two common risks: how to treat an unknown status as a failed transaction, which can result in false declines, and retrying a transaction without first validating its status, which can lead to duplicate authorizations or duplicate charges. A timeout represents an unknown transaction status, which is not necessarily a transaction failure. Related payment services: * [Authorization Reversal](/docs/cybs/en-us/payments/developer/barclays/rest/payments/payments-processing-basic-intro/payments-processing-basic-auth-reversal-intro.md "") Incorrect Timeout Handling Risks {#payments-timeout-risks} ========================================================== Each payment timeout creates a moment of uncertainty. How your team handles that moment determines whether it becomes a non-event, a customer complaint, a chargeback, or a lost sale. This table describes what goes wrong, the customer experience, and your business risk. | What Goes Wrong | Customer Experience | Business Risk | |-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | The timeout is misread as a failure. You retry the transaction immediately, and it is processed twice. | Customer sees two charges on their statement. | Chargeback, refund cost, trust damage, and potential dispute fees. | | The timeout is misread as a failure. You present a payment-failed message, and the customer abandons checkout. | Customer believes the card was declined. The customer tries another payment method or abandons the purchase. | Lost revenue. The original payment might still be authorized on the card. | | No unique transaction ID is present. As a result, duplicate detection fails and multiple authorizations occur. | Multiple holds or charges appear on the same card for one order. | Disputes, regulatory risk, and manual reconciliation overhead. | | You configure the client timeout too short. As a result, you drop the connection and the transaction status is unknown. | A spinner suddenly disappears with no clear result. | Unknown order status, manual intervention, and customer contact with support. | [Timeout Situations] IMPORTANT You must systematically resolve an unknown transaction status before you take additional payment actions. Each recommendation transforms an uncertain transaction status into an additional action. Transaction Flow and Failure Taxonomy {#payments-timeout-flow-taxonomy} ======================================================================= A single payment authorization transaction traverses multiple independent participants within the payment ecosystem. Each connection point can experience latency, communication failures, or timeout conditions. End-to-End Authorization Flow ----------------------------- The transaction passes through these participants: 1. **Cardholder to Merchant:** The cardholder initiates a payment transaction through a website, mobile application, point-of-sale system, or digital wallet. 2. **Merchant to `Cybersource`:** The merchant submits the authorization request to `Cybersource` for routing and processing. 3. **Processor routing:** `Cybersource` forwards the transaction to the appropriate processor. 4. **Card network routing:** The processor routes the request through the applicable payment network. 5. **Issuer decision:** The card issuer evaluates the transaction and returns an authorization decision. The transaction must follow the same path in reverse to be successful. Any break in that return path leaves the transaction status unknown to the merchant. This image shows the end-to-end authorization flow: ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/payments-timeouts-800x200.svg/jcr:content/renditions/original) These are the reason codes most relevant to timeout handling: * **`ESYSTEM`:** General system error or server-side failure. The transaction status is unknown. Do not treat as a definitive failure. Perform a status check before any retry or an authorization reversal. * **`ETIMEOUT`:** Server-side timeout. `Cybersource` received the request but could not return a response within the processing window. The transaction status is unknown. Reconcile before retrying. * **`DUPLICATE_REQUEST`:** Duplicate request declined. `Cybersource` identified the authorization as a duplicate of a previous request with the same merchant reference. Do not retry with the same reference, because the original transaction might have succeeded. Perform a status check first. Timeout Scenarios and Recommended Actions {#payments-timeout-scenarios} ======================================================================= These are the four distinct timeout scenarios. Scenario: Request Never Reached `Cybersource` --------------------------------------------- * **Duplicate risk:** none * **Condition:** The request never reached `Cybersource` because of a connection issue. As a result, you received no acknowledgment or response from `Cybersource`. * **Recommended Action:** After a few seconds, perform a transaction status lookup using the clientReferenceInformation.code field before you resubmit the authorization. If the lookup returns no transaction record, resubmit the original authorization request. Scenario: `Cybersource` Internal Failure ---------------------------------------- * **Duplicate risk:** low * **Condition:** `Cybersource` receives the request but cannot continue processing because a required internal service is timing out, for example Decision Manager, Token Management Service (TMS), Payer Authentication, or internal routing. Because the transaction never progresses into the downstream payment ecosystem, `Cybersource` does not submit an authorization to the processor, card network, or issuer. **Example: Internal Failure Response** HTTP Status Code: `502` ``` { "id": "7871896614436518804807", "submitTimeUtc": "2026-08-20T01:34:21Z", "status": "SERVER_ERROR", "reason": "SERVICE_TIMEOUT", "message": "The request was received, but a service did not finish running in time" } ``` * **Recommended Actions:** 1. Retry the authorization after a delay of approximately 30 seconds to allow any internal transient issue to resolve. 2. If the error persists, place the authorization in a delayed resubmission queue if possible. 3. Monitor for recovery by confirming successful processing of subsequent transactions or notification that the service issue is resolved. 4. Once recovery is confirmed, resubmit the original authorization request from the delayed resubmission queue. Scenario: Request Received, Processor Response Took Too Long ------------------------------------------------------------ * **Duplicate risk:** high * **Condition:** `Cybersource` accepted the request and invoked the authorization request to the processor, but did not get the response within the timeout period. As a result, the transaction might already have been approved even though the final status was not returned to you. **Example: Processor Timeout Response** HTTP Status Code: `502` ``` { "id": "7871927193766252604807", "submitTimeUtc": "2026-08-20T02:25:49Z", "status": "SERVER_ERROR", "reason": "SERVER_TIMEOUT", "message": "Error - The request was received but there was a server timeout. This error does not include timeouts between the client and the server." } ``` * **Recommended Actions:** 1. Retry the authorization. 2. For the first transaction since a timeout occurred, `Cybersource` proactively initiates an automatic authorization reversal as a protective measure in case the original authorization was approved but the final status could not be confirmed. 3. Perform a status lookup using the generated request id returned in the first authorization response after some time, and verify the final status of the automatic authorization reversal. 4. If the authorization reversal status cannot be confirmed, check with the processor or contact `Cybersource` customer support. Scenario: Approved, but Confirmation Never Received --------------------------------------------------- * **Duplicate risk:** highest * **Condition:** The authorization was approved, but you did not receive the response because of a connectivity or network issue, or because you use a short timeout window. This is the highest-risk scenario for duplicate charges. * **Recommended Actions:** 1. If you use a short timeout and plan to retry the authorization, wait up to 60 seconds before you take further action. Perform a transaction status lookup using the original clientReferenceInformation.code to determine the status of the original authorization request. If the transaction is found and approved, record the result. 2. If you perform a second authorization before verifying the status of the original authorization, you must reverse the original authorization. Use the merchant ID in the clientReferenceInformation.transactionId field from the original authorization request to submit an authorization reversal. Alternatively, use merchant reference code in the clientReferenceInformation.code field in transaction search to get the request ID and process the authorization reversal. **Example: Reversal Using the Transaction ID** ``` Endpoint: POST /pts/v2/reversals { "clientReferenceInformation": { "transactionId": "987654321" }, "reversalInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "ABC" } } } ``` Verifying a Transaction Status {#payments-timeout-verify-status} ================================================================ There are three methods for determining the accurate status of a transaction before you act on a timeout. Transaction Search API ---------------------- * When a timeout or communication failure occurs, use the REST API transaction search to determine whether the original authorization request was successfully processed. * Query using the request ID whenever available. * If the request ID is not available, query using the REST merchant reference code clientReferenceInformation.code field. **Transaction Search Best Practices** * Use the minimum date range required to locate a transaction. Avoid broad date-range searches when checking transaction status unless there is a specific business need. * Do not use transaction search for high-volume or frequent status checks. This can result in rate limiting. * For ongoing transaction status monitoring, use the payment status API where appropriate. * Include only the search criteria necessary to identify the transaction. * When searching for multiple request IDs, use the dedicated request ID filter instead of free-text search fields. **Example: Transaction Search Request** ``` Endpoint: POST /tss/v2/searches { "save": "false", "name": "Transaction Recovery Search", "timezone": "America/Chicago", "query": "clientReferenceInformation.code:{merchant_reference_code} AND submitTimeUtc:[NOW-1HOUR TO NOW/DAY+1DAY]", "offset": 0, "limit": 100, "sort": "id:asc,submitTimeUtc:asc" } ``` For the full request and response schema and a list of supported search fields, see the [Transaction Search API reference](https://developer.cybersource.com/api-reference-assets/index.md#transaction-search_search-transactions_create-a-search-request ""). `Business Center` ----------------- Use the `Business Center` when API-based verification is unavailable, or when a timeout requires closer manual review, for example investigating a customer-reported duplicate charge. > IMPORTANT Transaction search results might not be available immediately after a transaction is submitted, because data propagation takes a few seconds. 1. Sign in to the `Business Center` using your credentials. 2. Select Transaction Search \> Transaction Details. 3. Search using the ID returned in the `Cybersource` response for the internal-failure and processor- timeout scenarios. For other scenarios, when there is no response from `Cybersource`, search using the merchant reference number, known as the *merchant reference code* in the API. 4. Review the returned status, reason code, and timestamp to confirm the actual status. 5. Apply the result exactly as an API response would be applied. Record the status, and resubmit only if no record exists. #### Figure: Searching by Request ID for a Failed Authorization ![Searching by request ID returns the failed authorization for the internal-failure scenario (Card Payments, Authorization, Failed).](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/payments-timeout-bc-search-scenario-4-2.png/jcr:content/renditions/original) #### Figure: Searching by Request ID for a Failed Authorization and Its Automatic Authorization Reversal Searching by request ID returns both the failed authorization and the successful automatic timeout authorization reversal for the processor timeout scenario. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/payments-timeout-bc-search-scenario-4-3.png/jcr:content/renditions/original) #### Figure: Searching by Merchant Reference Number Searching by merchant reference number, when no request ID is available, returns the successful authorization and `Decision Manager` result. ![](/content/dam/documentation/cybs/en-us/topics/payments-processing/card-processing/payments/images/payments-timeout-bc-search-mrn.png/jcr:content/renditions/original) Automated Payment Status Notifications -------------------------------------- The payment events service uses a webhook to publish automated notifications for transaction statuses to your endpoint. This reduces reliance on the original synchronous response. This is a safety net that complements, and does not replace, the transaction status verifications described in this section. **Setup** 1. Enroll in the payment events service and create a webhook subscription. 2. Provide a secure URL that is capable of receiving inbound POST notifications in real time. 3. Acknowledge receipt of the notification immediately and process the event data asynchronously. **Behavior** 1. You submit a transaction and the synchronous response is delayed or lost. 2. The transaction completes on the `Cybersource` side, and `Cybersource` publishes the transaction status as a payment event. 3. Your webhook endpoint receives the notification, including the transaction ID, merchant reference code, and final transaction status. 4. Reconcile the event payload against your own records. For more information about the webhooks service, see [*Webhooks Developer Guide*](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.md "") . Layered Timeout Model {#payments-timeout-model} =============================================== `Cybersource` follows a layered timeout model based on a monotonic timeout hierarchy, where each outer layer waits slightly longer than the layer it depends on. This ensures that when an inner component times out first, `Cybersource` receives a clear timeout response and can take appropriate action. If you reverse the timeout order, you might abandon a request that is still being processed. This creates the risk that you incorrectly treat a completed transaction as a failure and retry it. `Cybersource` determines timeout values based on observed production latency, processor performance characteristics, and operational behavior, and periodically adjusts them. This table describes each timeout layer, typical wait times, and rationale for the each time setting. | Layer or Control | Typical Wait Time | Rationale | |--------------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Merchant to `Cybersource` | 60 seconds or more | Your timeout should be longer than the `Cybersource` processing timeout to ensure that `Cybersource` can return a definitive response before you abandon the request. | | `Cybersource` internal service | 5 to 10 seconds | The Payment Orchestrator uses these timeouts to call internal services such as Decision Manager and Token Management Service. | | `Cybersource` to processor | 30 seconds | `Cybersource` implements a fail-fast strategy for processor communications. `Cybersource` establishes timeout thresholds on a per-processor basis and evaluates them using processor response times, timeout rates, transaction volumes, and processor-specific operational characteristics. This approach aligns with processor guidance and enables `Cybersource` to quickly identify unreachable endpoints while minimizing unnecessary processing delays. | Retry and Duplicate Transaction Prevention {#payments-timeout-retry-duplicate} ============================================================================== Payment timeouts and communication failures can create uncertainty about the status of a transaction. You might receive a timeout response even though the transaction was successfully processed by `Cybersource`, the processor, or the issuer. In these situations, immediately resubmitting the original request can result in duplicate authorizations, captures, or charges. Implementing retry mechanisms are therefore essential to balance transaction recovery with duplicate prevention. Before retrying a payment operation, determine the transaction status whenever possible and apply controlled retry practices to minimize the risk of duplicate processing. To reduce this risk, use these methods: * Merchant reference codes to support authorization duplicate detection. * Transaction IDs to support timeout recovery, transaction lookups, authorization reversals, voids, and reconciliation. Merchant Reference Code and Duplicate Transaction Detection ----------------------------------------------------------- For authorization processing, `Cybersource` uses the clientReferenceInformation.code field that you provided to identify duplicate authorization requests. A duplicate authorization might be declined with reason code `104`. For the API field description, see [API Fields: Merchant Reference Code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md ""). Enabling Block Duplicate Merchant Reference Numbers --------------------------------------------------- Where the capability is supported for your configuration, you can enable your account to block duplicate merchant reference codes, also known as merchant reference numbers, rather than submitting a customer support request. This prevents duplicate authorization requests with the same merchant reference code submitted within 15 minutes of the original authorization. Follow these configuration steps in the `Business Center`: 1. Log in to the `Business Center`. 2. Go to Template Management or Manage Merchants. 3. Locate the **Block Duplicate Merchant Reference Number** setting. 4. Set enableDuplicateMerchantReferenceNumberBlocking to `true`. 5. Save and apply the configuration to the merchant profile. You can also manage this capability programmatically through the Merchant Boarding API. For more information, see [*Merchant Boarding Developer Guide*](https://developer.cybersource.com/docs/cybs/en-us/boarding/developer/all/rest/boarding/boarding-intro-overview.md "") Transaction ID for Timeout Recovery and Lifecycle Management ------------------------------------------------------------ The transaction ID in the clientReferenceInformation.transactionId field restricts duplicate transaction processing, locates transactions after a timeout, supports authorization reversal and void requests, and assists with reconciliation and operational investigations. Unlike the merchant reference code, which is used primarily for authorization duplicate detection, the transaction ID remains associated with the transaction throughout its lifecycle and recovery processes. The transaction ID applies to: * Authorization * Credit * Refund * Sale For the API field description, see [`Cybersource` API Fields reference: Transaction ID](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-transaction-id.md ""). > IMPORTANT > This capability is broadly available across most payment processors, except these processors: > > * ` AIBMS ` > * ` Barclays ` > * ` LloydsTSB Cardnet ` > * ` Cielo ` > * ` Elavon ` > * ` Comercio Latino ` > * ` FDC Compass ` > * ` FDC Nashville Global ` > * ` Fiserv RapidConnect ` > * ` HSBC ` > * ` Moneris ` > * ` Lloyds-OmniPay ` > * ` Rede ` > * ` Worldpay VAP ` Client Retry Backoff -------------------- When a request fails because of a temporary network or service issue, avoid immediately resubmitting the same request multiple times. Instead, space retry attempts with progressively longer delays between each attempt. This approach helps reduce pressure on downstream systems during periods of degraded performance, allows them time to recover, and helps prevent additional load that could worsen the disruption. A typical retry backoff strategy includes: * **Initial delay:** Wait a short period before the first retry attempt. * **Increasing delays:** Increase the wait time between successive retries rather than retrying at a fixed interval. * **Maximum delay:** Limit the maximum wait time between retries to avoid excessively long delays. * **Randomized timing (jitter):** Introduce small random variations in retry timing to prevent large numbers of clients from retrying simultaneously. * **Retry limits:** Cap the number of retry attempts or the overall retry duration before escalating to status validation, reconciliation, or operational review. Use retry backoff only for transient failures where a subsequent attempt might succeed. When the status of a payment transaction is unknown, determine the final transaction status before submitting another payment request. Reversal Strategy and Recovery Failure Handling {#payments-timeout-reversal-strategy} ===================================================================================== When the status of a payment transaction cannot be fully determined, the objective is to prevent duplicate charges while ensuring that the final transaction status is accurately resolved. This happens in two stages: first, choosing and executing the correct recovery action for the original transaction; second, recognizing that the recovery action itself is a network operation subject to the same failures, and handling that possibility the same way. Select the Correct Recovery Method ---------------------------------- Each recovery method applies to a specific point in the transaction lifecycle: * **Authorization reversal** releases an approved authorization that has not yet been captured. * **Void** cancels a transaction that exists but has not yet been submitted for settlement. * **Refund** returns funds for a transaction that has already been captured or settled. Consider the Transaction Lifecycle ---------------------------------- Base your recovery choice on the current transaction lifecycle stage: * If the transaction is authorized but not captured, an authorization reversal is typically appropriate. * If the transaction is captured but not yet settled, a void might be supported. * If the transaction has been settled, a refund is required. Confirm Transaction Status Before Reversing ------------------------------------------- Follow these steps before you reverse a transaction: 1. Determine whether the original transaction was processed. 2. Confirm the current transaction status. 3. Execute the appropriate recovery action. 4. Verify that the recovery action completed successfully. `Cybersource` Automatic Authorization Reversal ---------------------------------------------- For supported processor integrations, `Cybersource` might automatically submit an authorization reversal when the authorization status cannot be determined because of issuer, network, or processor communication failures. > IMPORTANT > When a timeout occurs, ` Cybersource ` designs recovery mechanisms to preserve Level II and Level III and currency-related transaction data, reducing the risk of interchange impacts caused by incomplete or lost transaction attributes. You must include Level II and Level III fields on the original authorization request so that this data is available in case of an automatic authorization reversal. When the Status of an Authorization Reversal or Void Request Is Unknown ----------------------------------------------------------------------- When the status of a recovery operation is unknown because of a timeout or communication failure, validate the transaction status using the original transaction ID and merchant reference code before taking additional action. This lookup is read-only against `Cybersource` transaction records and does not require resubmission of the original payment request. **Authorization Reversal or Void** `Cybersource` permits only one successful authorization reversal or void per transaction, so a retried request produces one of these results: * If `Cybersource` accepts a retried authorization reversal or void request, it did not successfully process the original authorization or void. * If `Cybersource` rejects a retried authorization reversal or void request because the transaction has already been reversed or voided, it already successfully processed the original authorization reversal or void and correctly prevented the duplicate request. * In this scenario, no additional authorization reversal or void action is required. **Refund** Refund processing requires additional care to avoid supporting multiple refunds against the same captured transaction. Consider these points: * Unlike authorization reversals and voids, a successfully processed refund does not prevent a subsequent refund from being submitted. * Therefore, when the status of a refund request is unknown, validate the transaction status before submitting another refund. * Failure to perform a status check might result in an unintended duplicate refund. * If a duplicate refund is identified before settlement, you might be able to void the refund, subject to processor capabilities and settlement timing. Reconciliation Sweep -------------------- The reconciliation sweep process acts as the final safety net for transactions that cannot be conclusively resolved through online recovery mechanisms. Reconcile `Cybersource` records against authorization, capture, reversal, refund, and settlement records using available correlation data such as merchant reference number, transaction ID, amount, currency, and available payment reference values. Identify unresolved transactions, duplicate processing activity, and recovery operations in which the transaction status cannot be confirmed. Based on the transaction status and processor capabilities, perform one of these actions: * Initiate an automated late recovery action where permitted. * Route unresolved cases to an operational review queue for manual investigation and resolution. Reconciliation provides the final confirmation of transaction status and serves as the last line of defense against unresolved duplicates, failed recovery actions, and communication failures. Recommended Approach -------------------- `Cybersource` recommends pairing bounded, status-checked retries with an automated reconciliation sweep against settlement. This combination catches lost authorization s without requiring manual intervention. Retrying alone, without a reconciliation process behind it, leaves genuinely charged but unresolved cases unaddressed. Preventing Queue Cascades and System Overload {#payments-timeout-queue-cascades} ================================================================================ Correct handling of individual transaction timeouts is only part of a resilient payment architecture. Under sustained latency or downstream service degradation, requests can accumulate across multiple layers. `Cybersource` Controls ---------------------- `Cybersource` protects its system stability with bounded queues and connection pools, circuit breakers that pause traffic to a struggling downstream dependency and resume it only after recovery, and load shedding that returns `HTTP 429` or `HTTP 503` with `Retry-After` guidance rather than accepting more work than it can handle. Each response indicates whether an operation is safe to retry, and `Cybersource` is set up to avoid a request to hold a processing resource beyond its allocated timeout. Your Controls ------------- Apply these controls on your side: * Implement bounded queues and connection pools for all payment traffic. * Use circuit breakers to protect your applications from `Cybersource` slowdowns. * Respect `Retry-After` and other retry guidance. * Apply exponential backoff with jitter to all retry operations. * Cap concurrent in-flight requests during degraded operating conditions. * Move recovery workflows to asynchronous processing queues rather than user-facing request threads. Avoiding the Asymmetric Recovery Trap ------------------------------------- Apply these safeguards: * Rate limit recovery operations. * Control retry traffic independently from new transaction traffic. * Bound background recovery queue throughput. * Prioritize correctness over speed in recovery processing. IMPORTANT The objective is not to retry failed transactions indefinitely. The objective is to maintain system stability while enabling safe recovery through controlled retries, reconciliation, and recovery workflows. Exception Handling Recommendations {#payments-timeout-decision-tables} ====================================================================== These tables provide detailed, transaction-type-specific guidance for handling exceptions, timeouts, and recovery scenarios during authorization, capture, authorization reversal or void, and credit or refund processing. They are operational reference material intended for engineering, support, and operations teams who are resolving live exceptions. | Scenario | Expected Behavior | Recommended Actions | |--------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | The authorization request never reaches `Cybersource` because of a network, Domain Name System (DNS), or Transport Layer Security (TLS) failure. | No transaction record is created at `Cybersource`. No downstream authorization is submitted. | Confirm that the failure is client-side. Wait for connectivity. Perform a status lookup to confirm no record exists. Retry safely using the same transaction ID. | | A `Cybersource` internal dependency fails (`Decision Manager`, `Token Management Service`, or payer authentication). | A hard decline is returned immediately. The transaction never reaches the processor, network, or issuer. | No status check is needed, because the transaction status is known. Verify the failed dependency, then resubmit with the same transaction ID. | | A timeout occurs before the processor, network, or issuer responds. | `Cybersource` returns `151` or `ETIMEOUT`. The status is unknown. An automatic authorization reversal might be triggered. | Do not retry immediately. Wait for the `Cybersource` processing window. Perform a status lookup through the transaction search API. Reconcile if unresolved. | | The authorization is approved by the issuer, but the response is lost. | The authorization exists and is valid on the card, but you never received confirmation. The status is already known and approved. No automatic authorization reversal condition applies here because automatic authorization reversal addresses the case where the status is unknown to `Cybersource`. | Do not resubmit. Perform a status lookup using the original transaction ID. Record the result after you confirm it. | | The authorization is declined by the issuer, but the response is lost. | No charge exists. This is a safe end-state, but you are unaware. | Perform a status lookup to confirm the decline. Once confirmed, it is safe to request an alternate payment method. | | You submitted a duplicate authorization before the original is resolved. | Two authorizations might exist on the card simultaneously. | Verify the duplicate transaction using a transaction ID or merchant reference code match. Reverse the duplicate transaction, never the original. | | The automatic authorization reversal confirmation is lost. | The reversal might have succeeded or failed at the processor. The status is unknown to `Cybersource` and you. | Apply the recovery pattern described earlier in this topic: validate the transaction status on the reversal itself, then submit the transaction for reconciliation to determine its final status. | [Authorizations] | Scenario | Expected Behavior | Recommended Actions | |---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | The capture request never reaches `Cybersource`. | No capture record is created. The authorization remains open or uncaptured. | Confirm the client-side failure. Perform a status lookup. If no record exists, retry with the same transaction ID. | | The capture times out downstream. | The settlement status is unknown. The authorization might or might not have been captured. | Do not retry immediately. Perform a status lookup. Confirm using the settlement report if still unresolved. Reconcile. | | The capture succeeds, but confirmation is lost. | Funds are captured. Only the response is missing. | A status lookup confirms the captured state. Record the result. No retry or authorization reversal is needed. | | The capture fails because the authorization expired or the amount mismatched, and the response is lost. | A real decline occurred, but you see only a timeout. | A status lookup reveals the true decline reason. Address the root cause before you resubmit. | | The authorization is approved, but the capture timed out. | This is an ambiguous state. The authorization is valid, but the capture status is unconfirmed. | Treat as approved but unsettled. It might settle or reverse depending on the downstream status. Verify using the settlement report, then choose retry-capture or reverse-authorization. | | The capture is retried without a status check. | There is a risk of duplicate capture, or double billing, on the customer's card. | Always perform a status check before you retry. If a duplicate occurs, refund or void only the later capture. | | The capture succeeds, but the settlement report shows a later discrepancy. | The settlement record is different from the status you expected. | Route to the reconciliation sweep. Match on the merchant ID, amount, currency, and card reference. | [Captures] | Scenario | Expected Behavior | Recommended Actions | |-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | The reversal or void request never reaches `Cybersource`. | No reversal record is created. The original authorization remains active and open. | Confirm that the failure is client-side. Perform a status lookup on the reversal. If no record exists, resubmit the reversal using the same transaction IDs. | | The reversal times out downstream (processor, network, or issuer). | The status of the reversal is unknown. The original authorization might or might not have been released. | Do not retry immediately. Perform a status lookup through the transaction search API on the reversal itself. Reconcile, if unresolved. | | The reversal succeeds, but confirmation is lost. | The authorization was successfully released. Only the response is missing. | A status lookup confirms the release. Record the result. No further action is needed. | | The reversal fails because you already captured or settled the transaction, or the authorization expired, and the response is lost. | The reversal was rejected outright, a real decline of the reversal itself, but you see only a timeout. | A status lookup reveals the true rejection reason. If the transaction has since settled, use refund or credit instead of a reversal. | | You retry the reversal without a status check. | There is a risk of a duplicate reversal attempt against the same authorization. | Always perform a status check before you retry. | | An automatic authorization reversal is already in progress when you submitted a manual reversal. | Two reversal attempts, one automatic and one manual, might race against the same authorization. | Confirm the automatic authorization reversal status before you submit a manual reversal. Avoid duplicate reversal attempts on the same authorization. | | You cannot confirm the reversal status after the recovery window. | This is a genuinely unresolved state, with a risk that the authorization remains held on the cardholder's account indefinitely. | Submit the transaction for reconciliation to determine its final status. If still unresolved, route to a manual operational review. | [Authorization Reversals and Voids] | Scenario | Expected Behavior | Recommended Actions | |-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | The refund request never reaches `Cybersource`. | No refund record is created. The settled transaction remains unrefunded. | Confirm that the failure is client-side. Perform a status lookup. If no record exists, retry the refund using the same transaction ID. | | The refund times out downstream. | The refund status is unknown. It is unclear whether funds were returned to the cardholder. | Do not retry immediately. Perform a status lookup. Confirm using the settlement report if unresolved. Reconcile. | | The refund succeeds, but confirmation is lost. | Funds were returned. Only the response is missing. | A status lookup confirms the refunded state. Record the result. No further refund is needed. | | The refund fails because it was already refunded or the amount exceeds the captured amount, and the response is lost. | A real decline occurred, such as a duplicate or over-limit refund attempt, but you see only a timeout. | A status lookup reveals the true decline reason before you attempt any further recovery action. | | The refund is retried without a status check. | There is a risk of a duplicate refund, with funds returned to the cardholder twice. | Always perform a status check before you retry, using the same refund reference. | [Refunds] Your Integration Responsibilities {#payments-timeout-merchant-responsibilities} =============================================================================== This checklist defines your responsibilities for timeout handling. Use it as a verification checklist during implementation reviews, quality assurance sign-off, and go-live assessments: * Set the client read timeout to 60 seconds or more, allowing sufficient time for `Cybersource` to return a definitive response before you terminate the request. * Assign a unique merchant reference code in the clientReferenceInformation.code field to each transaction and use that reference consistently for transaction processing, status validation, recovery activities, and reconciliation to support end-to-end traceability. * On an unknown status, use the transaction search API and reporting or reconciliation data to determine the final transaction status before submitting another payment request. Avoid immediate resubmission and apply controlled retries with increased delays between attempts. Honor the `Retry-After` reason code and other retry guidance provided by `Cybersource`. * When a duplicate is identified, reverse the duplicate, not the original. Select void versus refund based on the current transaction lifecycle state. Confirm the charge exists before reversing. * Implement appropriate resiliency controls, such as bounded concurrency, request throttling, circuit breakers, or asynchronous recovery processing, to prevent recovery activities from affecting customer-facing transaction flows. * Treat reason codes `151`, `ETIMEOUT`, and `267` (deferred or pending timeout) as unknown, never as a definite failure or a definite success. Best Practices {#payments-timeout-best-practices} ================================================= Always verify the transaction status through the Transaction Search API or the Business Center before you retry, reverse, or communicate the transaction status to the customer. If you identify duplicate transactions, apply an authorization reversal to the duplicate transaction. * Timeout events can occur because different participants in the payment ecosystem use different timeout values. * Do not resubmit a transaction after a timeout without first searching or assessing the potential cause. * Perform a transaction search to determine the actual status. * Based on the search results, reverse duplicate transactions if you identify multiple successful transactions, and take no action if the transaction was completed successfully and no duplicate exists.