Partial authorisation

Learn how to allow partial payments for card transactions.

Use partial authorisations to request approval for a portion of the originally requested amount for a card transaction when the available balance is insufficient to cover the full amount. This allows your customers to use the available balance on their card (such as a debit card), then use an alternative payment method to pay the remaining balance.

Before you begin

First, decide how you want to handle the portion of the originally requested amount that isn’t covered by the partial authorisation. You can create a separate PaymentIntent for another form of payment, cancel the entire PaymentIntent, or capture only up to the partially authorised amount. Make sure you clearly communicate with your customer about how you’re proceeding with the transaction and any potential impact on them.

Compliance

You’re responsible for your compliance with all applicable laws, regulations, and network rules when using partial authorisation. Consult the rules for the card networks that you want to use this feature with to make sure your sales comply with all applicable rules, which vary by network. For example, as of May 2024, American Express restricts usage of the feature to only debit and prepaid and doesn’t permit its use with recurring or cross-border transactions, while Visa requires you to use the feature across card types. 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 a professional if you’re unsure about your obligations.

Availability

IC+ feature

You can access partial authorisations on IC+ pricing. Contact your sales representative or support to enable this feature.

Partial authorisations have the following restrictions:

You can only use partial authorisations for online card payments.
Only Visa, Mastercard, Discover, and Amex support partial authorisations.
The issuer and card type determine whether they’re supported.
Due to network restrictions, you can’t capture more than the authorised amount using overcapture if a transaction amount has been partially authorised.
If you process charges on behalf of your Connect account using a transfer_amount, Stripe limits it to the partially authorised amount when the transfer_amount is greater than the partially authorised amount.
Stripe enforces a minimum charge amount on partially authorised charges, declining any PaymentIntent that falls short.

Use manual capture to create and confirm PaymentIntents

To enable partial authorisation for specific PaymentIntents, set if_available to the request_partial_authorization parameter.

Verify partial authorisation status

Review the payment_method_details field on the latest_charge in the PaymentIntent confirmation response to determine whether the networks applied partial authorisation for the payment:

partial_authorization.status: Displays one of the following authorisation statuses: partially_authorized, fully_authorized, declined, or not_requested.
amount_requested: Confirms your originally specified request amount.
amount_authorized: Determines the authorised amount.

The example response below shows that the transaction is partially authorised for 70 USD, which is less than the originally requested 100 USD.

Example PaymentIntent confirmation response
{
  "id": "pi_foo",
  "amount": 7000,
  "amount_capturable": 7000,
  "amount_received": 0,
  "capture_method": "manual",
  ...
  // if latest_charge is expanded
  "latest_charge": {
    "id": "ch_foo",
    "object": "charge",
    "amount": 7000,
    "captured": false,
    "payment_method_details": {
      "card": {
        "amount_authorized": 7000,
        "amount_requested": 10000,
        "partial_authorization": {
          "status": "partially_authorized",
        }
      }
    }
  },
  ...
  "status": "requires_capture"
}

If the card issuer declines the authorisation, this response returns a card_declined error.

Capture the partially authorised PaymentIntent

You can capture an authorised PaymentIntent up to the amount (or amount_capturable) that’s returned in the confirmation response.

A successful capture returns the PaymentIntent object with updated fields:

Successful capture response
{
  "id": "pi_foo",
  "amount": 7000,
  "amount_capturable": 0,
  "amount_received": 7000,
  "capture_method": "manual",
  "latest_charge": "ch_foo",
  ...
  "status": "succeeded",
}

OptionalUse auto-capture to confirm and capture a PaymentIntent

We recommend using partial authorisation with manual capture because it allows you to evaluate the partially authorised amount and decide whether to proceed with the capture. However, you can also use partial authorisation with auto-capture. If you decide to use this option, proceed with caution; it’s possible that you might capture an insufficient amount.

You can enable partial authorisation with auto-capture functionality by setting:

request_partial_authorization to if_available
capture method to automatic (or leave it blank)

In the auto-capture flow, your transaction is automatically captured even if it’s partially authorised. The following example response indicates that the transaction is partially authorised and captured for 70 USD, less than the full 100 USD requested.

Successful capture response
{
  "id": "pi_foo",
  "amount": 7000,
  "amount_capturable": 0,
  "amount_received": 7000,
  "capture_method": "automatic",
  ...
  // if latest_charge is expanded
  "latest_charge": {
    "id": "ch_foo",
    "object": "charge",
    "amount": 7000,
    "amount_captured": 7000,
    "captured": true,
    "payment_method_details": {
      "card": {
        "amount_authorized": 7000,
        "amount_requested": 10000,
        "partial_authorization": {
          "status": "partially_authorized",
        }
      }
    }
  },
  ...
  "status": "succeeded"
}

OptionalIncrement with partial authorisation

You can request partial authorisation in the PaymentIntent increment authorisation call to get approval for a portion of the requested increment amount when the available balance isn’t enough to cover the full amount.

Create and confirm a PaymentIntent

Create and confirm a PaymentIntent with incremental authorisation enabled using the request_incremental_authorization parameter. This enables the incremental authorisation feature on the PaymentIntent. See incremental authorization to learn more.

The following example response shows that the transaction is fully authorised for 100 USD:

Example PaymentIntent confirmation response
{
  "id": "pi_foo",
  "amount": 10000,
  "amount_capturable": 10000,
  "amount_received": 0,
  "capture_method": "manual",
  ...
  // if latest_charge is expanded
  "latest_charge": {
    "id": "ch_foo",
    "object": "charge",
    "amount": 10000,
    "captured": false,
    "payment_method_details": {
      "card": {
        "amount_authorized": 10000,
        "amount_requested": 10000,
        "partial_authorization": {
          "status": "not_requested",
        },
        "incremental_authorization": {
          "status": "available"
        }
      }
    }
  },
  ...
  "status": "requires_capture"
}

Enable partial authorisation on increment

To enable partial authorisation on increments, set request_partial_authorization to if_available:

By default, Stripe retains the opt-in parameter for request_partial_authorization that you pass during PaymentIntent confirmation for increments. To disable partial authorisations for increments on a PaymentIntent that has opted for partial authorisation, set payment_method_options[card][request_partial_authorization] to never.

The example requests attempts to increment the PaymentIntent amount to 150 USD from 100 USD, but it’s partially authorised to 135 USD.

Command Line
curl https://api.stripe.com/v1/payment_intents/pi_foo/increment_authorization \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=15000 \
  -d "payment_method_options[card][request_partial_authorization]"="if_available" \
  -d "expand[]"="latest_charge"

The example response below shows the most recent Charge object associated with the partially authorised PaymentIntent object:

Successful increment response
{
  "id": "pi_foo",
  "amount": 13500,
  "amount_capturable": 13500,
  "amount_received": 0,
  "capture_method": "manual",
  ...
  // if latest_charge is expanded
  "latest_charge": {
    "id": "ch_foo",
    "object": "charge",
    "amount": 13500,
    "captured": false,
    "payment_method_details": {
      "card": {
        "amount_authorized": 13500,
        "amount_requested": 15000,
        "partial_authorization": {
          "status": "partially_authorized",
        }
      }
    }
  },
  ...
  "status": "requires_capture"
}

Test your integration

To trigger a partial authorisation while testing, use the partial authorisation Stripe test card with any CVC, postal code, and future expiry date. Make sure you set request_partial_authorization to if_available to trigger partial authorisation with the test card.

Test card number	Payment method	Description
	`pm_card_debit_partialAuthorization`	This card authorises 70% of the amount specified in the confirmation request rounded down to the nearest unit (for example, cents) with partial authorisation requested. Otherwise, it declines it with an insufficient funds error code.
	`pm_card_debit_partialIncrement`	This card fully authorises the initial authorisation. For subsequent increments, this card authorises 70% of the amount specified in the increment request rounded down to the nearest unit (for example, cents) with partial authorisation requested. Otherwise, it returns insufficient funds.