Incremental authorization

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

Authorize the payment with intent set to authorize, for the amount you estimate. Set is_amount_estimated to true on connectors that require it.
Increase the authorization when the final amount is known. Call increment authorization with the amount to add.
Capture the payment for up to the new authorized amount using 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. The examples leave out the payment method and other fields for brevity.

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

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

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());
        }
    }
}

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
}

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)

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();

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. 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.

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

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

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());
        }
    }
}

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
}

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)

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();

The response reports the outcome and returns the updated transaction.

{
  "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.

Treat pending as not yet approved. Don’t capture the increased amount until the authorized_amount on the transaction reflects it.

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.

Supported connectors

Connector	Requires `is_amount_estimated`	Notes
Chase Orbital	Yes
Checkout.com	Yes
Cybersource	No	Not supported on American Express. An increase on an American Express card fails with the `unsupported_scheme` code.
Shift4	Yes	Availability varies by payment method and region. See the Shift4 page for details.
Card simulator	No	Sandbox only. See 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. Each increase is recorded on the transaction’s history in the dashboard and in 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 uses the increase amount to simulate each outcome:

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

Get started

Integration guides

Best Practices

Resources

Features

Other

Incremental authorization