Increment an authorization

Increase an existing authorization on a confirmed PaymentIntent before you capture it.

Incremental authorization allows you to increase the authorized amount on a confirmed PaymentIntent before you capture it. Before capture, each incremental authorization appears on the credit card statement as an additional pending entry (for example, a 10 USD authorization incremented to 15 USD appears as separate 10 USD and 5 USD pending entries). After capture, the pending authorizations are removed, and the total captured amount appears as one final entry.

Availability

When using incremental authorizations, be aware of the following restrictions:

It’s not currently available if you and the cardholder are in a country with Strong Customer Authentication requirements or similar authentication requirements.
It’s only available with Visa, Mastercard, or Discover.
Certain card brands have merchant category restrictions (see below).

mode is set to payment and capture_method is set to manual on the CheckoutSession.

To learn more about incremental authorization and in-person payments made using Terminal, see Incremental Authorizations.

IC+ feature

We offer incremental authorizations to users on IC+ pricing. If you’re on standard Stripe pricing and want access to this feature, you can learn more at support.stripe.com.

Availability by card network and merchant category

Use incremental authorizations on payments that fulfill the criteria below. You can find your user category in the Dashboard.

Attempting to perform an incremental authorization on a payment that doesn’t fulfill the below criteria results in an error.

Card brand	Merchant country	Payment type	Merchant category
Visa	Global	All card payment types	All user categories
Mastercard	Global*	All card payment types	All user categories
Discover	Global	All card payment types	Car rental, hotels, local/suburban commuter, passenger transportation, including ferries, passenger railways, bus lines-charter, tour, steamship/cruise lines, boat rentals & lease, grocery stores and supermarkets, electric vehicle charging, eating places and restaurants, drinking places (alcoholic beverages), hotels, motels, resorts, trailer parks & campgrounds, equip/tool/furn/appl rental & leasing, automobile rental agency, truck and utility trailer rentals, motor home and rec vehicle rentals, parking lots, parking meters, and garages, amusement parks, circuses, fortune tell, recreation services (not classified)
Discover	Global	Card not present	Taxicabs and limousines

* Excludes MX users and JPY transactions for JP users

Networks with limited support (beta)

Best practices

When using incremental authorization, proactively notify your end customer with the details of any authorizations for estimated amounts, which might be followed by incremental authorizations that increase those amounts. Here are some best practices for doing so:

Disclose that an authorization is for an estimated amount and that subsequent authorization requests might follow at the time of checkout, before purchase.
Base estimated amounts on a genuine estimate of what the total transaction amount will be.

You can use the custom_text field when creating a new CheckoutSession to display additional text on the checkout page to help meet compliance requirements.

Compliance

You’re responsible for your compliance with all applicable laws, regulations, and network rules when using incremental authorization. Consult the network rules for the card networks that you plan to use this feature with to make sure your sales comply with applicable rules, which vary by network. For example, most card networks restrict how you can calculate estimated amounts included in the initial authorization, and prohibit the use of incremental authorizations for transactions where the transaction amount should be known at the time of authorization (for example, charges for recurring subscriptions).

The information provided on this page relating to your compliance with these requirements is for your general guidance, and isn’t legal, tax, accounting, or other professional advice. Consult with a professional if you’re unsure about your obligations.

Create a CheckoutSession

Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.

checkout.html
<html>
  <head>
    <title>Buy cool new product</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

A Checkout Session is the programmatic representation of what your customer sees when they’re redirected to the payment form. You can configure it with options such as:

Line items to charge
Currencies to use

You must populate success_url with the URL value of a page on your website that Checkout returns your customer to after they complete the payment. You can optionally also provide a cancel_url value of a page on your website that Checkout returns your customer to if they terminate the payment process before completion.

Note

Checkout Sessions expire 24 hours after creation by default.

After creating a Checkout Session, redirect your customer to the URL returned in the response.

Lastly, set request_incremental_authorization as if_available to enable the incremental authorization feature.

After the customer has completed checkout, the payment_method_details field on the latest_charge in the PaymentIntent contains available or unavailable based on the customer’s payment method and the availability criteria mentioned above, which determines whether a PaymentIntent is eligible for incremental authorization or not. (If you didn’t request incremental authorization when creating the CheckoutSession, it will be unavailable.)

{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 1000,
  "amount_received": 0,
  ...
  // if latest_charge is expanded
  {
    "latest_charge": {
        "amount": 1000,
        "payment_method_details": {
          "card": {
            "incremental_authorization": {
                "status": "available" // or "unavailable"
            }
          }
        }
        ...
      }
  }

}

Mount Checkout

Checkout is available as part of Stripe.js. Include the Stripe.js script on your page by adding it to the head of your HTML file. Next, create an empty DOM node (container) to use for mounting.

index.html
<head>
  <script src="https://js.stripe.com/v3/"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialize Stripe.js with your publishable API key.

Create an asynchronous fetchClientSecret function that makes a request to your server to create the Checkout Session and retrieve the client secret. Pass this function into options when you create the Checkout instance:

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Checkout renders in an iframe that securely sends payment information to Stripe over an HTTPS connection.

Common mistake

Avoid placing Checkout within another iframe because some payment methods require redirecting to another page for payment confirmation.

Customize appearance

Customize Checkout to match the design of your site by setting the background color, button color, border radius, and fonts in your account’s branding settings.

By default, Checkout renders with no external padding or margin. We recommend using a container element such as a div to apply your desired margin (for example, 16px on all sides).

Show a return page

After your customer attempts payment, Stripe redirects them to a return page that you host on your site. When you created the Checkout Session, you specified the URL of the return page in the return_url parameter. Read more about other options for customizing redirect behavior.

When rendering your return page, retrieve the Checkout Session status using the Checkout Session ID in the URL. Handle the result according to the session status as follows:

complete: The payment succeeded. Use the information from the Checkout Session to render a success page.
open: The payment failed or was canceled. Remount Checkout so that your customer can try again.

client.js
const session = await fetch(`/session_status?session_id=${session_id}`)
if (session.status == 'open') {
  // Remount embedded Checkout
} else if (session.status == 'complete') {
  // Show success page
  // Optionally use session.payment_status or session.customer_email
  // to customize the success page
}

Redirect-based payment methods

During payment, some payment methods redirect the customer to an intermediate page, such as a bank authorization page. When they complete that page, Stripe redirects them to your return page.

Learn more about redirect-based payment methods and redirect behavior.

Perform an incremental authorization

To increase the authorized amount on a PaymentIntent, use the increment_authorization endpoint and provide the updated total authorization amount to increment to, which must be greater than the original authorized amount. This attempts to authorize for a higher amount on your customer’s card. A single PaymentIntent can call this endpoint multiple times to further increase the authorized amount.

You have a maximum of 10 incremental authorization attempts per PaymentIntent.

Command Line
curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/increment_authorization \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1500

If the incremental authorization succeeds, it returns the PaymentIntent object with the updated amount. If the authorization fails, it returns a card_declined error instead. The PaymentIntent object remains capturable for the previously authorized amount. Any potential updates to other PaymentIntent fields (for example, application_fee_amount, transfer_data, metadata, description, and statement_descriptor) aren’t saved if the incremental authorization fails.

Incremental authorization has a maximum cap of either 500 USD (or local equivalent) over, or 500% over the previously authorized amount (whichever is higher) for each individual increment.

Capture the PaymentIntent

Whether you increase the authorized amount on a PaymentIntent with an incremental authorization or not, you need to capture the funds before the initial authorization expires–incremental authorizations don’t extend the validity period. To capture the authorized amount on a PaymentIntent with prior incremental authorizations, use the capture endpoint as usual.

Command Line
curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
:

If the incremental authorization succeeds, it returns the captured PaymentIntent object with the updated amount. If the authorization fails, it returns a card_declined error instead. The PaymentIntent isn’t captured, but it remains capturable for the previously authorized amount. Any potential updates to other PaymentIntent fields (for example, application_fee_amount, transfer_data, metadata, description and statement_descriptor) aren’t saved if the incremental authorization fails.

Test your integration

Use the incremental authorization Stripe test card with any CVC, postal code, and future expiration to trigger incremental authorization while in test mode:

First create the CheckoutSession using the test card in the create a CheckoutSession step above.

Perform the incremental authorization with the parameters specified in the perform an incremental authorization step above, and use the test card to trigger an incremental authorization.

Number	Payment Method	Description
	`pm_card_debit_incrementalAuthAuthorized`	This increases the authorization amount to the amount provided in the request.