Migrate to the latest flexible payment scenarios

Adapt your beta advanced payment scenarios to the general release.

Stripe now supports several flexible payment scenarios for non-card-present transactions. If you’ve already integrated the private beta version of any of these features, this guide provides details to upgrade to the general release. For new integrations, use the following guides for the features that interest you:

• Increment an Authorization
• Capture more than the Authorized Amount
• Place an Extended Hold on an Online Card Payment
• Capture a Payment Multiple Times

We’ve incorporated the following feedback-driven improvements to these features:

• Detailed control over the features at the PaymentIntent level.
• Clearer expectations regarding feature availability and usage after a confirmation phase.

Each of the flexible payment features has different requirements from its private beta integration. Choose the feature you need to upgrade and refer to the note at the top for changes and requirements specific to that feature.

Changes from beta

The first step of this integration is now mandatory.

Request incremental authorization

Your PaymentIntent must include a request for incremental authorization before confirmation.

Warning

This formerly optional step is now mandatory.

Before

After

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

The response now returns the status of the incremental authorization request in the payment_method_details.card.incremental_authorization.status property of the latest_charge. The status values is available or unavailable depending on the customer’s payment method.

Before

After

// 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_supported": true // or false
 }
 }
 ...
 }
 }
}

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

Incrementally modify the authorized amount

No changes have been made to this step in comparison to the beta version.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Choose how to capture more than initially authorized amount

Two of the flexible payment features allow you to capture an amount larger than initially authorized:

• Over capture up to a certain limit ( Capture more than the authorized amount on a payment )
• Increment the existing authorization and then capture the newly authorized amount ( Increment an authorization )

The example below showcases how these features can complement each other in the generally available version.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

// PaymentIntent Response
{
 "object": "payment_intent",
 "amount": 1000,
 ...
 // if latest_charge is expanded
 {
 "latest_charge": {
 "payment_method_details": {
 "card": {
 "incremental_authorization": {
 "status": "available" // or "unavailable"
 },
 "overcapture": {
 "status": "available", // or "unavailable"
 "maximum_amount_capturable": 1200
 }
 }
 }
 ...
 }
 }
}

Upon confirmation of the PaymentIntent, if both features are available, you have options on the next steps to capture a larger amount than initially authorized:

1. Overcapture if the desired amount is equal or below the maximum _ amount _ capturable .
2. Perform an incremental authorization to the desired amount, then capture.