# Timeout Void

Cap how long the gateway waits on a processor response and auto-void ghost approvals that arrive after the timeout.

Source: https://developer.inoviopay.com/api/timeout-void.html  
Markdown: https://developer.inoviopay.com/api/timeout-void.md

The Timeout Void feature allows you to set a maximum duration for the gateway to wait for a processor's response on `CCAUTHORIZE` or `CCAUTHCAP` requests. If the gateway does not receive an end-state response within your specified window, it will return a decline to your system.

### Automated Resolution

Because the transaction may still be in-flight with the processor when the gateway times out, Inovio protects you from "ghost" approvals. If the processor eventually approves the transaction after the timeout period, the gateway will automatically submit a void request to ensure the cardholder is not charged for an abandoned transaction.

| Field Name | Description | Value Guideline |
|---|---|---|
| REQUEST_MAX_WAIT | Enables or disables the timeout functionality. | `1` (Enable) or `0` (Disable). |
| REQUEST_MAX_WAIT_TIMER | The number of seconds to wait before abandoning the request. | Required if enabled. Must be between `30` and `600` seconds. |

> **Global Portal Setting**
> Merchants can also set a global Timeout Void preference at the account level within the Inovio Portal. Any parameters sent within an individual API request will override the global portal settings.

**Request**

```
// Set a strict 60-second limit for this sale
REQUEST_ACTION=CCAUTHCAP
&REQUEST_MAX_WAIT=1
&REQUEST_MAX_WAIT_TIMER=60
&LI_VALUE_1=100.00...
```

**PHP**

```php
use Inovio\Gateway\{Credentials, InovioClient};
use Inovio\Gateway\Errors\GatewayTimeoutException;
use Inovio\Gateway\Model\{LineItem, Money, PaymentMethods};
use Inovio\Gateway\Refs\Refs;
use Inovio\Gateway\Request\TransactionRequest;

$client = new InovioClient(new Credentials('api_user', 'P@ssw0rd!', '12345'), 'SANDBOX');

$req = (new TransactionRequest(
    PaymentMethods::card('4111111111111111', '122026', '123'),
    [new LineItem('SKU-1', 1, Money::of('100.00', 'USD'))]
))->withIdempotency('ORDER-555');

try {
    $client->sale($req);
} catch (GatewayTimeoutException $e) {
    // The state is UNKNOWN, not failed — resolve it, don't retry blindly.
    $actual = $client->status(Refs::xtlOrder($e->xtlOrderId()));
    echo $actual->transactions === [] ? 'safe to retry' : 'already happened', "\n";
}
```

**Node**

```ts
import { InovioClient, Money, PaymentMethods, Refs, TimeoutError } from '@inovio/gateway-sdk';

const client = new InovioClient(
  { reqUsername: 'api_user', reqPassword: 'P@ssw0rd!', siteId: '12345' },
  { environment: 'SANDBOX' }
);

try {
  await client.sale({
    paymentMethod: PaymentMethods.card('4111111111111111', '122026', '123'),
    lineItems: [{ productId: 'SKU-1', count: 1, value: Money.of('100.00', 'USD') }],
    idempotency: { xtlOrderId: 'ORDER-555' },
  });
} catch (e) {
  if (!(e instanceof TimeoutError)) throw e;
  // The state is UNKNOWN, not failed — resolve it, don't retry blindly.
  const actual = await client.status(Refs.xtlOrder(e.xtlOrderId!));
  console.log(actual.transactions.length === 0 ? 'safe to retry' : 'already happened');
}
```

**Python**

```python
from inovio_gateway import Credentials, InovioClient, InovioTimeoutError, Money, PaymentMethods, Refs
from inovio_gateway.model import Idempotency, LineItem
from inovio_gateway.request import TransactionRequest

client = InovioClient(Credentials("api_user", "P@ssw0rd!", "12345"), environment="SANDBOX")

req = TransactionRequest(
    payment_method=PaymentMethods.card("4111111111111111", "122026", "123"),
    line_items=[LineItem("SKU-1", 1, Money.of("100.00", "USD"))],
    idempotency=Idempotency(xtl_order_id="ORDER-555"),
)

try:
    client.sale(req)
except InovioTimeoutError as e:
    # The state is UNKNOWN, not failed — resolve it, don't retry blindly.
    actual = client.status(Refs.xtl_order(e.xtl_order_id))
    print("safe to retry" if not actual.transactions else "already happened")
```

**Java**

```java
import com.inoviopay.gateway.errors.GatewayTimeoutException;
import com.inoviopay.gateway.refs.Refs;
import com.inoviopay.gateway.result.OrderStatus;

TransactionRequest req = new TransactionRequest(
    PaymentMethods.card("4111111111111111", "122026", "123"),
    new LineItem("SKU-1", 1, Money.of("100.00", "USD")))
    .idempotency("ORDER-555");

try {
    client.sale(req);
} catch (GatewayTimeoutException e) {
    // The state is UNKNOWN, not failed — resolve it, don't retry blindly.
    OrderStatus actual = client.status(Refs.xtlOrder(e.xtlOrderId()));
    System.out.println(actual.transactions().isEmpty() ? "safe to retry" : "already happened");
}
```

**Response**

```json
{
  "TRANS_STATUS_NAME": "DECLINED",
  "SERVICE_RESPONSE": "626",
  "SERVICE_ADVICE": "Authorization has been voided in accordance to timeout settings."
}
```