Stripe Webhooks

The Stripe webhooks can be used with the Checkout Form.

One-time payments

When a sale is made through the 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, the service'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.


The Checkout Form will launch a subscription with Stripe on the merchant's Stripe account as usual. The Checkout Form will set the tax_rate and application_fee_percent and create a subscription placeholder in the service. 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, the service uses 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 the service.

When the invoice.payment_succeeded event is processed by the service, it will update the invoice and charge object metadata in Stripe with the taxamo_key entry. 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 the service 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.


The service 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).