Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment methods
Payment UIs
Payment scenarios
In-person payments
Other Stripe products

Capture a payment multiple times

Capture a PaymentIntent multiple times, up to the authorized amount.

Multicapture allows you to capture a PaymentIntent created during the confirmation step of a CheckoutSession multiple times for a single transaction, up to the full amount of the PaymentIntent. You can use it when you have orders with multiple shipments, and want to capture funds as you fulfill parts of the order.

IC+ feature

Multicapture is part of the functionality we offer to users on IC+ pricing. If you’re on blended Stripe pricing and want access to this feature, contact Stripe Support.

Availability

When using multicapture, be aware of the following restrictions:

Best practices

When sending separate shipments for one order, proactively notify your end customer with the details of each shipment. Doing so avoids inquiries and chargebacks from customers because of confusion with seeing multiple transactions on their bank statement. Use the following best practices when notifying customers:

  • Inform them of the estimated delivery date and transaction amount for each shipment at the time of checkout, before purchase.
  • Notify them upon each shipment, along with the transaction amount.
  • Disclose your full refund and cancellation policy.

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 multicapture. 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, most card networks restrict multicapture usage to card-not-present transactions for the sale of goods that ship separately. Certain card networks permit multicapture for businesses based on their industry (for example, travel), while some don’t permit multicapture for installment or deposit workflows.

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 Checkout Session

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

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:

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_multicapture as if_available to enable the multicapture feature.

# This example sets up an endpoint using the Sinatra framework.
# Watch this video to get started: https://youtu.be/8aA9Enb8NVc.

require 'json'
require 'sinatra'
require 'stripe'

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'


post '/create-checkout-session' do
  session = Stripe::Checkout::Session.create({
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'T-shirt',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    payment_method_options: {
      card: {
        request_multicapture: 'if_available',
      },
    },
    mode: 'payment',
    # These placeholder URLs will be replaced in a following step.
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
  })

  redirect session.url, 303
end

Payment methods

By default, Stripe enables cards and other common payment methods. You can turn individual payment methods on or off in the Stripe Dashboard. In Checkout, Stripe evaluates the currency and any restrictions, then dynamically presents the supported payment methods to the customer.

To see how your payment methods appear to customers, enter a transaction ID or set an order amount and currency in the Dashboard.

You can enable Apple Pay and Google Pay in your payment methods settings. By default, Apple Pay is enabled and Google Pay is disabled. However, in some cases Stripe filters them out even when they’re enabled. We filter Google Pay if you enable automatic tax without collecting a shipping address.

Checkout’s Stripe-hosted pages don’t need integration changes to enable Apple Pay or Google Pay. Stripe handles these payments the same way as other card payments.

Capture the PaymentIntent

For a PaymentIntent in a requires_capture state where multicapture is available, specifying the optional final_capture parameter to be false tells Stripe not to release the remaining uncaptured funds when calling the capture API. For example, if you confirm a 10 USD payment intent, capturing 7 USD with final_capture=false keeps the remaining 3 USD authorized.

Command Line
curl https://api.stripe.com/v1/payment_intents/pi_xxx/capture \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount_to_capture=700 \
  -d final_capture=false \
  -d "expand[]"=latest_charge

In the PI capture response, the amount_capturable and amount_received fields update accordingly.

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 300, // 1000 - 700 = 300
  "amount_received": 700,
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 700,
      "amount_refunded": 0,
      ...
    }
  ...
}

Final capture

The PaymentIntent remains in a requires_capture state until you do one of the following:

  • Set final_capture to true.
  • Make a capture without the final_capture parameter (because final_capture defaults to true).
  • The authorization window expires.

At this point, Stripe releases any remaining funds and transitions the PaymentIntent to a succeeded state.

Command Line
curl https://api.stripe.com/v1/payment_intents/pi_xxx/capture \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount_to_capture=200 \
  -d final_capture=true \
  -d "expand[]"=latest_charge

In the PI capture response, the amount_capturable and amount_received fields will be updated accordingly.

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 0, // not 100 due to final_capture=true
  "amount_received": 900, // 700 + 200 = 900
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 900,
      "amount_refunded": 0,
      ...
    }
  ...
}

Uncaptured PaymentIntents transition to canceled, while partially captured PaymentIntents transition to succeeded.

Test your integration

Use a Stripe test card with any CVC, postal code, and future expiration date to test multicapture payments.

NumberPayment MethodDescription
pm_card_visaThis test card supports multicapture.
pm_card_visa_cartesBancairesCartes Bancaires or Visa test card that supports multicapture.

Refunds

For a PaymentIntent in requires_capture state, you can refund any number of times up to the total captured amount minus the total refunded amount, which is the amount_received—amount_refunded. The charge.refunded field transitions to true only when the final capture has been performed and the entire amount_received is refunded.

Stripe doesn’t support partial refunds with refund_application_fee=true or reverse_transfer=true. Instead, you can perform partial fee refunds by manually performing partial fee refunds and transfer reversals using the application fee refund and transfer reversal endpoints. After using the application fee refund or transfer reversal endpoints, Stripe doesn’t support any further refunds with refund_application_fee=true or reverse_transfer=true respectively.

Connect

Multicapture supports all Connect use cases, with the exception of Separate Charges and Transfers with the source_transaction parameter. The application_fee_amount and transfer_data[amount] parameters have some additional validations. Consider the following validations when implementing multicapture with Connect:

  • Setting application_fee_amount or transfer_data[amount] on the first capture makes it required for all subsequent captures. Each application_fee_amount and transfer_data[amount] passed at capture time overrides the values passed in on PaymentIntent creation, confirmation, and update.
  • Stripe doesn’t support partial refunds on multicapture payments with refund_application_fee=true or reverse_transfer=true. You can perform partial fee refunds or transfer reversals using the application fee refund and transfer reversal endpoints.

Webhooks

Charge updated webhooks

We send a charge.updated webhook each time you capture a payment.

For example, on the first capture of a destination charge multicapture payment with an application_fee_amount, we update these fields from empty to non-empty values.

// charge.updated
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "amount": 1000,
    "balance_transaction": "txn_xxx", // applicable to all charges
    "transfer": "tr_xxx",             // applicable to destination charges only
    "application_fee": "fee_xxx",     // applicable to Connect only
    ...
  },
  "previous_attributes": {
    "balance_transaction": null, // applicable to all charges
    "transfer": null,            // applicable to destination charges only
    "application_fee": null,     // applicable to Connect only
  }
}

payment_intent.amount_capturable_updated

We send payment_intent.amount_capturable_updated on every capture, regardless of amount_to_capture and final_capture values.

For example, if we capture 1 USD from a PaymentIntent with an amount of 10 USD, the PaymentIntent’s amount_capturable field updates to 9 USD.

// payment_intent.amount_capturable_updated
{
  "data": {
    "id": "pi_xxx",
    "object": "payment_intent",
    "amount": 1000,
    "amount_capturable": 900 // 1000 - 100 = 900
     ...
  },
  "previous_attributes": {
    "amount_capturable": 1000
  }
}

Charge captured events

We send a charge.captured event for final captures or at the end of the authorization window to reverse the authorization of the uncaptured amount. The captured field for a charge only becomes true after a final capture or authorization reversal.

For example, if we do a capture with amount=0 and final_capture=true, the captured attribute on the charge changes from false to true.

// charge.captured
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "captured": true
        ...
  },
  "previous_attributes": {
    "captured": false
  }
}

Refund webhooks

Multicapture refund webhooks are no different than non-multicapture refund webhooks.

During each partial refund, we’ll send a refund.created event. For connected accounts, we’ll additionally send application_fee.refunded events when we refund application fees and transfer.reversed events when we reverse transfers.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc