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 updatetax_rate
if the invoice is not closed and an appropriate setting is enabled for this subscriptioninvoice.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_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 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).
Updated almost 3 years ago