Increment an authorization

You can use the request_incremental_authorization parameter to specify the PaymentIntents you plan to increment.

Use the if_available or never parameters to determine when to start incrementing a PaymentIntent:

• if_available: The created PaymentIntent allows for future increments based on incremental authorization support availability.

• never: The created PaymentIntent doesn’t allow for future increments.

You can only perform incremental authorizations on uncaptured payments after PaymentIntent confirmation. To adjust the amount of a payment before confirmation, use update method instead.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d payment_method=pm_card_debit_incrementalAuthAuthorized \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]"=latest_charge \
  -d "payment_method_options[card][request_incremental_authorization]"=if_available

In the PaymentIntent confirmation response, the payment_method_details field on the latest_charge 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 in your PaymentIntent confirmation request, it will be unavailable.)

// PaymentIntent Response
{
  "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"
            }
          }
        }
        ...
      }
  }

}

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.

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/increment_authorization \
  -u 
sk_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) or +500% of the previously authorized amount (whichever is higher) for each individual increment.

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.

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u 
sk_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.

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

1. First create the PaymentIntent using the test card in the create and confirm PaymentIntent step above.

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