API integration overview

Table of contents
  1. Tax estimates
  2. Transaction finalization
  3. Voids
  4. Refunds
    1. Option 1: Update the original transaction with new transaction details.
    2. Option 2: Create a negative transaction for each refund. Do not modify the original transaction.
    3. Option 3: Negate the original transaction and create a new transaction with the new balance.

Tax estimates

Before collecting payment, it’s common to show a preview of the tax amount that will be added to the transaction. Anrok’s createEphemeral endpoint can be used to generate this tax preview. This endpoint accepts the details of your transaction and returns the tax amount to collect.

To calculate tax, you first need to collect:

  • The customer’s taxable address (billing or shipping address).
  • The product(s) that the customer is purchasing.
  • Any exemption certificates or tax identifiers (if necessary).

It’s common to show a preview of the tax amount on a checkout page before the customer completes their order. This tax amount can be estimated using Anrok’s createEphemeral endpoint and should be refreshed any time the customer changes something that might impact the calculation.

Here are some common actions that should trigger a tax calculation:

  • The customer modifies the products in their cart.
  • The customer applies a discount/coupon code.
  • The customer updates their address.
  • The customer provides a tax ID or exemption certificate.

Transaction finalization

When a transaction is ready to be finalized, the Anrok createOrUpdate endpoint can be used to generate the final tax calculation and create a transaction in Anrok. This endpoint accepts the same transaction details as createEphemeral, but instead of just returning the tax amount to collect, this endpoint also saves the transaction in Anrok and associates it with the appropriate tax return.

Voids

If a transaction needs to be removed from a tax return after it has been finalized, void can be used to remove the transaction from an Anrok tax return. Void can be used in cases where a customer transaction payment was unsuccessful or when the invoice needs to be canceled for any other reason. Void will only work if a transaction has not been included on a filed tax return already, otherwise Anrok will return transactionFrozenForFiling.

Refunds

Option 1: Update the original transaction with new transaction details.

This option is best when the transaction has been created recently and has not yet been added to a finalized tax return. If the transaction has been frozen for filing and can no longer be updated, this endpoint will return the response transactionFrozenForFiling.

Option 2: Create a negative transaction for each refund. Do not modify the original transaction.

  • Use createOrUpdate endpoint to create a negative transaction representing the refund.

This option is best when you prefer to see refunds represented as separate transactions in Anrok. Each time a refund is created, you can create a new negative transaction. This behavior matches the credit-note behavior of many billing systems.

Option 3: Negate the original transaction and create a new transaction with the new balance.

  • Use createNegation endpoint to negate the original transaction.
  • Use createOrUpdate endpoint to create a new version of the partially refunded transaction.

This option is best when you prefer to associate refunds with the original transaction instead of creating separate transactions for each refund as described in Option 2. When creating new transaction versions, you’ll need to append a suffix to the transaction ID to preserve ID uniqueness in Anrok. For example, many Anrok integrations append the suffix :s2 or :s3 to the transaction ID for 2nd and 3rd transaction versions.