Use Taxamo to calculate taxes in Stripe Relay apps

Merchants who use the Stripe Relay API in their applications can use Taxamo to calculate taxes for all Stripe orders created via the Stripe Relay API.

When this feature is enabled each Stripe order will trigger a corresponding Taxamo transaction. The Stripe order will then be updated with the value of the relevant tax calculated by Taxamo.

The Taxamo transactions that are created are identical to all other transactions in the Taxamo dashboard. You can, for example, use them to calculate a tax settlement at the end of a tax period.

Setup

This section of the manual describes how to configure Taxamo as a Stripe tax provider in TEST or LIVE mode.

Please note that the screenshots used below show the configuration process in TEST mode only.

1. Enable Stripe tax provider functionality in the Taxamo dashboard

  • Login to the Taxamo dashboard and go to Home > Payment Service Providers > Stripe section.

  • Push the Generate Stripe Tax Provider URL in TEST mode or Generate Stripe Tax Provider URL in LIVE mode button:

  • A new url should be generated:

Copy this url. You will have to use it to finish this setup in the Stripe dasboard.

Note: To turn off this functionality you can push the Remove Stripe Tax Provider URL in TEST mode or Remove Stripe Tax Provider URL in LIVE mode button at any time.

2. Select Taxamo as a tax provider in the Stripe dashboard

  • Login to the Stripe dashboard.

  • Go to Your account > Account Settings > Orders.

  • Select Show Test mode settings or Show Live mode settings:

  • Push the Change tax… button:

Select settings as per the screenshot above. Paste the url that has been copied from the Taxamo dashboard to the Taxamo URL input field.

  • Push the Update button and you are all set.

3. Testing

  • Create a Stripe order and verify that a corresponding transaction has been created in the Taxamo dashboard. The calculated tax should be the same in both dashboards.

  • Pay for the Stripe order. Its status should then change to Paid. The status of a Taxamo transaction should be changed to confirmed.

  • Make a refund of a Stripe order (we support both full and partial refunds). An identical refund should be created for a Taxamo transaction. The values of the calculated tax should change in both panels.

Metadata

During the creation of a Stripe order two additional fields can be provided in metadata object. Their values will be used as additional data for transaction location evidence:

  • buyer_ip - IP address of the buyer in dotted decimal (IPv4) or text format (IPv6)

  • billing_country_code - Billing two letter ISO country code. If this value is not set then Taxamo will use value of country field from Shipping Address object for a location evidence.

Example:

curl https://api.stripe.com/v1/orders \
-u STRIPE_API_KEY: \
-d items[][type]=sku \
-d items[][parent]=sku_90ZPG5KKoR2PFj \
-d items[][quantity]=3 \
-d currency=eur \
-d shipping[name]="Joshua Johnson" \
-d shipping[address][line1]="1234 Main Street" \
-d shipping[address][city]="San Francisco" \
-d shipping[address][country]=FR \
-d shipping[address][postal_code]=94111 \
-d email="test@mailinator.com" \
-d metadata[buyer_ip]="1.2.3.4"\
-d metadata[billing_country_code]="IE"

Unsupported operations

Refunding charges

Taxamo does not receive a notification from Stripe when a payment for a Stripe order is refunded:

In such a situation an expected refund of a Taxamo transaction will not be created.

Please note that returns of Stripe orders (not refunds on charges related to them) are supported.

Charge disputes

In addition, Taxamo does not receive a notication when a charge is disputed by a customer. Any resulting changes to a Stripe order will not be reflected in the Taxamo dashboard.

Coupons

Taxamo will not receive a notification when a coupon is added to an already created Stripe order. In such a case the value of the calculated tax will be the same in both panels but total amounts will be different.

When a Stripe order is created with a coupon then both the calculated tax and the total amount will have the correct values in both panels.

Refunding Taxamo transactions

Refunds made in the Taxamo dashboard will not be propagated to Stripe. As a result, the value of the calculated tax will differ between a Taxamo transaction and a corresponding Stripe order.