Basic Stripe Tax API
Use the basic Stripe Tax integration with PaymentIntents for automatic tax transaction management.
The basic Stripe Tax API integration lets you calculate tax and link calculations to PaymentIntents. Stripe automatically manages tax transactions and reversals in the payment lifecycle. This is the recommended approach for most PaymentIntents use cases.
Stripe Tax offers more than one way to integrate with PaymentIntents, depending on how much control you need.
Choose the right tax integration
Stripe offers two ways to handle tax with PaymentIntents. Choose your method based on how much control you need:
- Use this basic integration if you want Stripe to handle tax transactions and reversals automatically. Refund reversals use flat-amount distribution.
- Use the custom Stripe Tax API if you need line-item level control over tax reversals, or control over when transactions are recorded.
Stripe only calculates tax in jurisdictions where you have an active tax registration. Without a registration in the customer’s location, the calculation returns zero tax. To learn more, see Understand zero tax amounts.
Calculate tax
Calculating tax typically requires your customer’s location. You can:
- Use the Address Element to take advantage of autocomplete and localization features to collect your customer’s full address. This helps ensure the most accurate tax calculation.
- Estimate tax based on the customer’s IP address .
- Collect address details using your own custom form.
Pass the transaction details and customer address information to the calculate tax API to get a new Tax Calculation object.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
The response includes the total amount and a tax breakdown. See the Tax Calculation object for the full response structure.
// Tax Calculation response (minimized)
{
"id": "taxcalc_1234567890",
"amount_total": 1082,
"tax_amount_exclusive": 82,
"tax_amount_inclusive": 0,
...
}
Link tax calculation to the PaymentIntent
Create or modify a PaymentIntent to include the Tax Calculation ID and set the amount to tax_calculation.amount_total from the Tax Calculation response.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Supported endpoints
The following endpoints support setting a calculation on a PaymentIntent.
- Create: /v1/payment_intents
- Update: /v1/payment_intents/:id
- Confirm: /v1/payment_intents/:id/confirm
- Capture: /v1/payment_intents/:id/capture
Limitations
- You can only link new calculations to a PaymentIntent until it transitions to a succeeded state.
- A tax calculation can transition to only one tax Transaction . If multiple PaymentIntents transition to a succeeded state with the same linked calculation, accounting reflects only the first one.
Resulting Stripe actions
If the PaymentIntent is correctly linked to the Tax Calculation object, Stripe automatically:
- Creates a tax transaction from the calculation after the PaymentIntent transitions to a succeeded state
- Performs a flat amount tax reversal of a tax transaction for any refunds (created with API or Dashboard) for the PaymentIntent
- Creates a tax reversal for a reversal, if a refund has failed
- Includes the total tax information in PaymentIntent receipts
Tax transaction reporting
Tax transactions that Stripe automatically records for this integration have a source_type of external in the Stripe Data schema because Stripe creates them from the linked Tax Calculation, not directly from the PaymentIntent. The id column in tax reports contains the ID number of the associated PaymentIntent.
The payment_intent source type is deprecated and might appear in historical data.
Stripe won’t:
- Recalculate tax based on PaymentIntent changes
- Change the PaymentIntent amount based on the linked tax calculation
- Alter the tax transaction amount based on the PaymentIntent captured amount
- Automatically create a tax reversal for disputes
Integrate taxes for your Connect platform with the Stripe Tax and Payment Intents APIs
The Payment Intents API works with connected accounts on your Connect platform. This means that if you calculate tax using a connected account, you can link the tax calculation to a PaymentIntent created using that connected account.
Caution
This integration doesn’t support destination charges when you create a tax calculation on a connected account and a PaymentIntent on the platform account. Using on_behalf_of doesn’t change the account requirement. If automatic_tax[liability] assigns liability to the connected account, create the tax calculation and PaymentIntent on the connected account. If the platform is liable, create both on the platform account. To use a destination charge with connected-account tax liability, use the custom integration.