End-to-End Authorization Flow

Cardholder to Merchant:
The cardholder initiates a payment transaction through a website, mobile application, point-of-sale system, or digital wallet.
Merchant to
Cybersource
:
The merchant submits the authorization request to
Cybersource
for routing and processing.
Processor routing:
Cybersource
forwards the transaction to the appropriate processor.
Card network routing:
The processor routes the request through the applicable payment network.
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:

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.

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:
Retry the authorization after a delay of approximately 30 seconds to allow any internal transient issue to resolve.
If the error persists, place the authorization in a delayed resubmission queue if possible.
Monitor for recovery by confirming successful processing of subsequent transactions or notification that the service issue is resolved.
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:
Retry the authorization.
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.
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.
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:

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.

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"
    }
  }
}

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.

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"
}

Business Center

Sign in to the
Business Center
using your credentials.
Select
Transaction Search
>
Transaction Details
.
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.
Review the returned status, reason code, and timestamp to confirm the actual status.
Apply the result exactly as an API response would be applied. Record the status, and resubmit only if no record exists.

Figure:

Figure:

Searching by request ID returns both the failed authorization and the successful automatic timeout authorization reversal for the processor timeout scenario.

Figure:

Searching by merchant reference number, when no request ID is available, returns the successful authorization and

Decision Manager

result.

Automated Payment Status Notifications

Enroll in the payment events service and create a webhook subscription.
Provide a secure URL that is capable of receiving inbound POST notifications in real time.
Acknowledge receipt of the notification immediately and process the event data asynchronously.

You submit a transaction and the synchronous response is delayed or lost.
The transaction completes on the
Cybersource
side, and
Cybersource
publishes the transaction status as a payment event.
Your webhook endpoint receives the notification, including the transaction ID, merchant reference code, and final transaction status.
Reconcile the event payload against your own records.

Merchant Reference Code and Duplicate Transaction Detection

Enabling Block Duplicate Merchant Reference Numbers

Log in to the
Business Center
.
Go to Template Management or Manage Merchants.
Locate the
Block Duplicate Merchant Reference Number
setting.
Set
enableDuplicateMerchantReferenceNumberBlocking
to
true
.
Save and apply the configuration to the merchant profile.

Transaction ID for Timeout Recovery and Lifecycle Management

Authorization
Credit
Refund
Sale

Client Retry Backoff

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.

Select the Correct Recovery Method

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

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

Determine whether the original transaction was processed.
Confirm the current transaction status.
Execute the appropriate recovery action.
Verify that the recovery action completed successfully.

Cybersource

Automatic Authorization Reversal

When the Status of an Authorization Reversal or Void Request Is Unknown

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.

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

Initiate an automated late recovery action where permitted.
Route unresolved cases to an operational review queue for manual investigation and resolution.

Recommended Approach

Cybersource

Controls

Your Controls

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

Rate limit recovery operations.
Control retry traffic independently from new transaction traffic.
Bound background recovery queue throughput.
Prioritize correctness over speed in recovery processing.