Calculate tax in your custom payment flowsPublic preview

Learn how to integrate taxes with the Stripe Tax and Payment Intents APIs.

The Stripe Tax API enables you to calculate tax in your custom payment flows. If you use the Payment Intents API, Stripe can submit tax transactions in the payment lifecycle.

Using tax calculations with the Payment Intents API requires the beta SDK versions. Update your SDK before using this feature.

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.

Link tax calculation to the PaymentIntent

Create or modify a PaymentIntent to include the Tax Calculation ID and set the amount to the Calculation amount_total.

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

Stripe won’t:

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.

OptionalRetrieve automatically committed tax transactions

Use the /v1/tax/associations/find endpoint to retrieve information about the tax transactions that Stripe created (or failed to create) for a PaymentIntent. This allows you to verify that your integration works as intended, handle card dispute cases, or review what was created automatically.

If your PaymentIntent succeeds and is refunded afterwards, you might receive the following response.

Caution

The Tax reversals are only recorded and appear in the Tax Association object after several minutes.

// TaxAssociation find response
{
  "id": "taxa_1PXmsbE5ebw4kUHWxtSTF08x",
  "object": "tax.association",
  "calculation": "taxcalc_1PXmsRE5ebw4kUHW9SOln70o",
  "payment_intent": "pi_1PXmsSE5ebw4kUHWK7FIhQlS",
  "tax_transaction_attempts": [
    {
      "source": "pi_1PXmsSE5ebw4kUHWK7FIhQlS",
      "status": "committed",
      "committed": {
        "transaction": "tax_1PXmsRE5ebw4kUHWLyVEiMis",
      }
    },
    {
      "source": "re_1PXmsSE5ebw4kUHWK7FIhQlS",
      "status": "committed",
      "committed": {
        "transaction": "tax_1PXmsgE5ebw4kUHW7Gg8jvpX",
      }
    }
  ]
}