> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wizlopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Incremental authorization

> Increase the amount of an existing card authorization when the final order total turns out higher than the amount you first authorized.

Most card payments happen in two stages. First, an **authorization** reserves the funds with the customer's bank, but no money moves. Then, a **capture** requests those funds for settlement.

Sometimes the final amount isn't known when you authorize. Orders with variable-weight items, product substitutions, or extra services often end up higher than the estimate. Incremental authorization lets you ask the customer's bank to raise the existing authorization before you capture, so the higher amount is reserved and you can capture all of it.

## Incremental authorization compared to over capture

Over capture lets you capture more than the authorized amount without asking the bank again. Card schemes and acquirers cap how far over the authorized amount you can capture, often to a small percentage. Incremental authorization has no such fixed cap, because the bank approves each increase before you capture it.

| | Over capture | Incremental authorization |
| - | - | - |
| Asks the bank again | No | Yes, for each increase |
| How much you can add | Limited by the scheme and acquirer | Whatever the bank approves |
| Can be declined | Only at capture | When you request the increase |

## How it works

1. **Authorize the payment** with `intent` set to `authorize`, for the amount you estimate. Set `is_amount_estimated` to `true` on [connectors that require it](#supported-connectors).
2. **Increase the authorization** when the final amount is known. Call [increment authorization](/reference/transactions/increment-transaction-authorization) with the amount to add.
3. **Capture the payment** for up to the new authorized amount using [capture transaction](/reference/transactions/capture-transaction).

You can increase the same authorization more than once. Each request adds to the current authorized amount.

### Authorize with an estimated amount

Some payment services only accept an increase if the original authorization was flagged as an estimate. Set `is_amount_estimated` to `true` when you [create the transaction](/reference/transactions/new-transaction). The examples leave out the payment method and other fields for brevity.

<CodeGroup>
  ```csharp C# theme={"system"}
  using Gr4vy;
  using Gr4vy.Models.Components;

  var sdk = new Gr4vySDK(
      id: "example",
      server: SDKConfig.Server.Sandbox,
      bearerAuthSource: Auth.WithToken(privateKey),
      merchantAccountId: "default"
  );

  var res = await sdk.Transactions.CreateAsync(
      transactionCreate: new TransactionCreate() {
          Amount = 10000,
          Currency = "AUD",
          Intent = "authorize",
          IsAmountEstimated = true,
      }
  );

  // handle response
  ```

  ```go Go theme={"system"}
  package main

  import(
  	"context"
  	"os"
  	gr4vygo "github.com/gr4vy/gr4vy-go"
  	"github.com/gr4vy/gr4vy-go/models/components"
  	"log"
  )

  func main() {
      ctx := context.Background()

      s := gr4vy.New(
  		gr4vy.WithID("example"),
  		gr4vy.WithServer(gr4vy.ServerSandbox),
  		gr4vy.WithSecuritySource(withToken),
  		gr4vy.WithMerchantAccountID("default"),
  	)

      res, err := s.Transactions.Create(ctx, components.TransactionCreate{
          Amount: 10000,
          Currency: "AUD",
          Intent: components.TransactionIntentAuthorize.ToPointer(),
          IsAmountEstimated: gr4vy.Pointer(true),
      }, nil, nil, nil)
      if err != nil {
          log.Fatal(err)
      }
      if res != nil {
          // handle response
      }
  }
  ```

  ```java Java theme={"system"}
  package hello.world;

  import com.gr4vy.sdk.Gr4vy;
  import com.gr4vy.sdk.models.components.TransactionCreate;
  import com.gr4vy.sdk.models.components.TransactionIntent;
  import com.gr4vy.sdk.models.errors.*;
  import com.gr4vy.sdk.models.operations.CreateTransactionResponse;
  import java.lang.Exception;

  public class Application {

      public static void main(String[] args) throws Exception {

          Gr4vy sdk = Gr4vy.builder()
                  .id("example")
                  .server(AvailableServers.SANDBOX)
                  .merchantAccountId("default")
                  .securitySource(new BearerSecuritySource.Builder(privateKey).build())
              .build();

          CreateTransactionResponse res = sdk.transactions().create()
                  .transactionCreate(TransactionCreate.builder()
                      .amount(10000L)
                      .currency("AUD")
                      .intent(TransactionIntent.AUTHORIZE)
                      .isAmountEstimated(true)
                      .build())
                  .call();

          if (res.transaction().isPresent()) {
              System.out.println(res.transaction().get());
          }
      }
  }
  ```

  ```php PHP theme={"system"}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Gr4vy;

  $sdk = Gr4vy\SDK::builder()
      ->setId('example')
      ->setServer('sandbox')
      ->setSecuritySource(Auth::withToken($privateKey))
      ->setMerchantAccountId('default')
      ->build();

  $transactionCreate = new Gr4vy\TransactionCreate(
      amount: 10000,
      currency: 'AUD',
      intent: 'authorize',
      isAmountEstimated: true,
  );

  $response = $sdk->transactions->create(
      transactionCreate: $transactionCreate
  );

  if ($response->transaction !== null) {
      // handle response
  }
  ```

  ```python Python theme={"system"}
  from gr4vy import Gr4vy
  import os


  with Gr4vy(
      id="example",
      server="sandbox",
      merchant_account_id="default",
      bearer_auth=auth.with_token(open("./private_key.pem").read())
  ) as g_client:

      res = g_client.transactions.create(amount=10000, currency="AUD", intent="authorize", is_amount_estimated=True)

      # Handle response
      print(res)
  ```

  ```typescript TypeScript theme={"system"}
  import { Gr4vy, withToken } from "@gr4vy/sdk";
  import fs from "fs";

  const gr4vy = new Gr4vy({
      id: "example",
      server: "sandbox",
      merchantAccountId: "default",
      bearerAuth: withToken({
        privateKey: fs.readFileSync("private_key.pem", "utf8"),
      }),
  });

  async function run() {
    const result = await gr4vy.transactions.create({
      amount: 10000,
      currency: "AUD",
      intent: "authorize",
      isAmountEstimated: true,
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

The flag can carry a cost at some payment services, so only set it on transactions you might increase.

### Increase the authorization

Send the amount to add, in the smallest currency unit, to [increment authorization](/reference/transactions/increment-transaction-authorization). The `amount` is the increase, not the new total. An increase of `1299` on an authorization of `10000` asks the bank for `11299` in total.

<CodeGroup>
  ```csharp C# theme={"system"}
  using Gr4vy;
  using Gr4vy.Models.Components;

  var sdk = new Gr4vySDK(
      id: "example",
      server: SDKConfig.Server.Sandbox,
      bearerAuthSource: Auth.WithToken(privateKey),
      merchantAccountId: "default"
  );

  var res = await sdk.Transactions.IncrementAuthorizationAsync(
      transactionId: "7099948d-7286-47e4-aad8-b68f7eb44591",
      transactionAuthorizationIncrementCreate: new TransactionAuthorizationIncrementCreate() {
          Amount = 1299,
      }
  );

  // handle response
  ```

  ```go Go theme={"system"}
  package main

  import(
  	"context"
  	"os"
  	gr4vygo "github.com/gr4vy/gr4vy-go"
  	"github.com/gr4vy/gr4vy-go/models/components"
  	"log"
  )

  func main() {
      ctx := context.Background()

      s := gr4vy.New(
  		gr4vy.WithID("example"),
  		gr4vy.WithServer(gr4vy.ServerSandbox),
  		gr4vy.WithSecuritySource(withToken),
  		gr4vy.WithMerchantAccountID("default"),
  	)

      res, err := s.Transactions.IncrementAuthorization(ctx, "7099948d-7286-47e4-aad8-b68f7eb44591", components.TransactionAuthorizationIncrementCreate{
          Amount: 1299,
      }, nil, nil)
      if err != nil {
          log.Fatal(err)
      }
      if res != nil {
          // handle response
      }
  }
  ```

  ```java Java theme={"system"}
  package hello.world;

  import com.gr4vy.sdk.Gr4vy;
  import com.gr4vy.sdk.models.components.TransactionAuthorizationIncrementCreate;
  import com.gr4vy.sdk.models.errors.*;
  import com.gr4vy.sdk.models.operations.IncrementTransactionAuthorizationResponse;
  import java.lang.Exception;

  public class Application {

      public static void main(String[] args) throws Exception {

          Gr4vy sdk = Gr4vy.builder()
                  .id("example")
                  .server(AvailableServers.SANDBOX)
                  .merchantAccountId("default")
                  .securitySource(new BearerSecuritySource.Builder(privateKey).build())
              .build();

          IncrementTransactionAuthorizationResponse res = sdk.transactions().incrementAuthorization()
                  .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591")
                  .transactionAuthorizationIncrementCreate(TransactionAuthorizationIncrementCreate.builder()
                      .amount(1299L)
                      .build())
                  .call();

          if (res.transactionAuthorizationIncrement().isPresent()) {
              System.out.println(res.transactionAuthorizationIncrement().get());
          }
      }
  }
  ```

  ```php PHP theme={"system"}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Gr4vy;

  $sdk = Gr4vy\SDK::builder()
      ->setId('example')
      ->setServer('sandbox')
      ->setSecuritySource(Auth::withToken($privateKey))
      ->setMerchantAccountId('default')
      ->build();

  $transactionAuthorizationIncrementCreate = new Gr4vy\TransactionAuthorizationIncrementCreate(
      amount: 1299,
  );

  $response = $sdk->transactions->incrementAuthorization(
      transactionId: '7099948d-7286-47e4-aad8-b68f7eb44591',
      transactionAuthorizationIncrementCreate: $transactionAuthorizationIncrementCreate

  );

  if ($response->transactionAuthorizationIncrement !== null) {
      // handle response
  }
  ```

  ```python Python theme={"system"}
  from gr4vy import Gr4vy
  import os


  with Gr4vy(
      id="example",
      server="sandbox",
      merchant_account_id="default",
      bearer_auth=auth.with_token(open("./private_key.pem").read())
  ) as g_client:

      res = g_client.transactions.increment_authorization(transaction_id="7099948d-7286-47e4-aad8-b68f7eb44591", amount=1299)

      # Handle response
      print(res)
  ```

  ```typescript TypeScript theme={"system"}
  import { Gr4vy, withToken } from "@gr4vy/sdk";
  import fs from "fs";

  const gr4vy = new Gr4vy({
      id: "example",
      server: "sandbox",
      merchantAccountId: "default",
      bearerAuth: withToken({
        privateKey: fs.readFileSync("private_key.pem", "utf8"),
      }),
  });

  async function run() {
    const result = await gr4vy.transactions.incrementAuthorization({
      amount: 1299,
    }, "7099948d-7286-47e4-aad8-b68f7eb44591");

    console.log(result);
  }

  run();
  ```
</CodeGroup>

The response reports the outcome and returns the updated transaction.

```json theme={"system"}
{
  "type": "transaction-authorization-increment",
  "status": "succeeded",
  "code": null,
  "raw_response_code": null,
  "raw_response_description": null,
  "transaction": {
    "type": "transaction",
    "id": "7099948d-7286-47e4-aad8-b68f7eb44591",
    "status": "authorization_succeeded",
    "amount": 10000,
    "authorized_amount": 11299,
    "captured_amount": 0
  }
}
```

The transaction's `amount` stays at the original value. The `authorized_amount` reflects the new total, and you can capture up to that amount.

## Outcomes

The `status` in the response is one of the following:

| Status | Meaning | `authorized_amount` |
| - | - | - |
| `succeeded` | The bank approved the increase. | Raised to the new total. |
| `failed` | The bank declined the increase, or the payment service returned an error. `code`, `raw_response_code`, and `raw_response_description` explain why. | Unchanged. |
| `pending` | The payment service accepted the request, but the outcome isn't known yet. | Unchanged until the payment service confirms the increase. |

A failed or pending increase doesn't affect the original authorization. It stays valid, and you can still capture up to the previous authorized amount.

<Warning>
  Treat `pending` as not yet approved. Don't capture the increased amount until the `authorized_amount` on the transaction reflects it.
</Warning>

## Requirements

An increase is only sent to the payment service when all of the following are true:

* The transaction status is `authorization_succeeded`. A transaction that is captured, voided, or in any other status returns a `400` `bad_request` error with a detail of type `not_valid_status`.
* The transaction was processed by a payment service that supports incremental authorization. Any other payment service returns a `400` error saying the `incremental_authorization` feature is not supported.

3-D Secure is never performed on an increase.

The endpoint accepts an `Idempotency-Key` header, so you can retry a request safely. See [idempotent requests](/guides/api/idempotent-requests).

## Supported connectors

| Connector | Requires `is_amount_estimated` | Notes |
| - | - | - |
| [Chase Orbital](/connections/payments/chaseorbital-card) | Yes | |
| [Checkout.com](/connections/payments/checkoutcom-card) | Yes | |
| [Cybersource](/connections/payments/cybersource-card) | No | Not supported on American Express. An increase on an American Express card fails with the `unsupported_scheme` code. |
| [Shift4](/connections/payments/shift4-card) | Yes | Availability varies by payment method and region. See the Shift4 page for details. |
| [Card simulator](/connections/payments/mock-card) | No | Sandbox only. See [Testing](#testing). |

Each connector page lists incremental authorization under its capabilities.

## Webhooks and transaction events

When an increase succeeds, Gr4vy sends a `transaction.modified` webhook with the updated transaction. No webhook is sent for a failed or pending increase. See [webhook events](/guides/features/webhooks/events).

Each increase is recorded on the transaction's history in the dashboard and in [list transaction events](/reference/transactions/list-transaction-events):

* The increment request and response.
* The request Gr4vy sent to the payment service, and its response.
* An **authorization increment succeeded** event, with the previous and new authorized amounts, or an **authorization increment failed** event, with the error code and the payment service's response code and description.

When a pending increase is later confirmed by the payment service, the succeeded or failed event is added at that point.

## Testing

In sandbox, the [card simulator](/connections/payments/mock-card) uses the increase `amount` to simulate each outcome:

| Increase `amount` | Outcome |
| - | - |
| `200` | `succeeded` |
| `250` | `pending` |
| `300` | `failed`, declined |
| Any other amount | `failed`, service error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.