Taxamo

The Taxamo Developer Hub

Welcome to the Taxamo developer hub. You'll find comprehensive guides and documentation to help you start working with Taxamo as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Stripe Webhooks

When using Taxamo Checkout Form

One-time payments

When a sale is made through the Taxamo Checkout Form, it is possible to subscribe to Stripe's charge events as usual.

Taxamo transactions will be referenced through the metadata.taxamo_key field in the charge object.

When verifying the sale details, Taxamo's API endpoint, as described earlier, should be used as the transaction details and the invoice url would be available on the Taxamo account transaction.

Subscriptions

The Taxamo Checkout Form will launch a subscription with Stripe on the merchant's Stripe account as usual. The Taxamo Checkout will set the tax_rate and application_fee_percent and create a subscription placeholder in Taxamo. This will be done either with a Taxamo account, if the sale is done through Taxamo, or directly with the merchant account in all other cases.

For the initial and recurring changes, Taxamo will use Stripe's webhook events:

  • invoice.created - to update tax_rate if the invoice is not closed and an appropriate setting is enabled for this subscription
  • invoice.payment_succeeded - to create and confirm an appropriate transaction in Taxamo. In the case of a sale done through Taxamo, an additional back-to-back transaction will be created in Taxamo.

When the invoice.payment_succeeded event is processed properly by Taxamo it will update the invoice and charge object metadata in Stripe with the taxamo_keyentry. This references the actual transaction representing the sale to the customer (either on the merchant's account, or on the Taxamo account).

This transaction key can be used to reference an invoice, or sale information, in merchant software. Be aware that the transaction key might not be available until Taxamo finishes processing the invoice.payment_succeeded event type.

Therefore, it might be most suitable to subscribe for the invoice.updated event type with Stripe, and wait for an update that will have the invoice closed and metadata updated with the Taxamo transaction key.

Refunds

Taxamo will handle refunds triggered in Stripe automatically, issuing appropriate credit notes for all necessary transactions.

This means that in case of a sale facilitated by Taxamo, two credit notes will be issued: one to the customer, and the other to Taxamo (on the merchant's behalf).

Stripe Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.