Increment an authorisation

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 authorisation support availability.

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

You can only perform incremental authorisations 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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 authorisation or not. (If you didn’t request incremental authorisation 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 authorised amount on a PaymentIntent, use the increment_authorization endpoint and provide the updated total authorisation amount to increment to, which must be greater than the original authorised amount. This attempts to authorise for a higher amount on your customer’s card. A single PaymentIntent can call this endpoint multiple times to further increase the authorised amount.

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

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

If the incremental authorisation succeeds, it returns the PaymentIntent object with the updated amount. If the authorisation fails, it returns a card_declined error instead. The PaymentIntent object remains capturable for the previously authorised 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 authorisation fails.

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

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

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

If the incremental authorisation succeeds, it returns the captured PaymentIntent object with the updated amount. If the authorisation fails, it returns a card_declined error instead. The PaymentIntent isn’t captured, but it remains capturable for the previously authorised 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 authorisation fails.

Use the incremental authorisation Stripe test card with any CVC, postal code, and future expiry to trigger incremental authorisations while testing:

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

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