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

You can integrate the Tax API with a PaymentIntent by associating it with a Tax Calculation object. Use calculate tax to get a new Tax Calculation object with information about how much tax to collect.

Link tax calculation to the PaymentIntent

When creating or modifying a PaymentIntent, include the Tax Calculation ID and set the amount to the amount_total of the Tax Calculation object.

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 Payment Intent 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",
      }
    }
  ]
}