Taxes are complicated, so to simplify the process of calculating and charging tax to customers, BlueSnap has partnered with Avalara. Each of your products will have an associated tax code that is used in conjunction with your shopper's address and your business address to calculate the tax rate. BlueSnap makes it easy to create tax quotes and add taxes to transactions.

This guide will cover the following topics:

Implementation

Implementing BlueSnap's tax feature consists of these steps:

1. Map your products to tax codes

2. Create a tax quote

3. Process the transaction

1. Map your products to tax codes

Avalara needs to know how to categorize each of your products and services to calculate taxes. In some instances, various product types, such as clothes, food, and video games, need to be taxed at different rates. Tax codes provide a method to categorize goods and services so Avalara can handle these variations.

Map each of your products and services to its appropriate tax code. Refer to Avalara's website for a directory of tax codes. You will need to store the applicable tax codes on your side.

2. Create a tax quote

As part of the checkout process, you'll need to calculate and display the tax amount to your shopper. To calculate the tax, send a Create Tax Quote request to BlueSnap.

The response will include the tax for each item, the total tax, and the tax quote reference number (which allows you to reference the tax quote in the future), in addition to other details. At this point, you'll need to display the sales tax to the shopper.

Tax quote expiration

A tax quote will expire 24 hours after its creation unless you send the transaction to BlueSnap before then. If a tax quote expires before the transaction has been sent to BlueSnap, you'll need to create a new one.

3. Process the transaction

To process the transaction, include the total transaction amount (including the total tax) in the amount property and include the tax quote reference number in the taxReference property. Below is a basic Auth Capture request and response.

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \ 
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "cardTransactionType": "AUTH_CAPTURE",
  "softDescriptor": "Test transaction",
  "amount": 174.8,
  "currency": "USD",
  "taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
  "cardHolderInfo": {
    "firstName": "Jane",
    "lastName": "Smith",
    "zip": "92614",
    "country": "us"
  },
  "creditCard": {
    "cardNumber": "4263982640269299",
    "securityCode": "837",
    "expirationMonth": "02",
    "expirationYear": "2023"
  }
}'

{
  "cardTransactionType": "AUTH_CAPTURE",
  "transactionId": "38646818",
  "softDescriptor": "Test transaction",
  "amount": 174.8,
  "usdAmount": 174.8,
  "currency": "USD",
  "avsResponseCode": "N",
  "transactionApprovalDate": "08/26/2020",
  "transactionApprovalTime": "01:17:01",
  "cardHolderInfo": {
    "firstName": "Jane",
    "lastName": "Smith",
    "country": "us",
    "zip": "92614"
  },
  "vaultedShopperId": 19671044,
  "creditCard": {
    "cardLastFourDigits": "9299",
    "cardType": "VISA",
    "cardSubType": "CREDIT",
    "cardCategory": "PLATINUM",
    "binCategory": "CONSUMER",
    "issuingBank": "ALLIED IRISH BANKS PLC",
    "issuingCountryCode": "ie"
  },
  "processingInfo": {
    "processingStatus": "success",
    "cvvResponseCode": "NR",
    "authorizationCode": "587327",
    "avsResponseCodeZip": "N",
    "avsResponseCodeAddress": "N",
    "avsResponseCodeName": "U"
  },
  "fraudResultInfo": {
    "deviceDataCollector": "N"
  },
  "taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b"
}

The tax amount is finalized once the transaction has been sent to BlueSnap and the shopper's bank has authorized the purchase. This means the shopper will be charged the amount that was authorized, even if tax rates change in the span of time between the authorization and when their funds are captured.

If the shopper's payment method is declined, you can retry the purchase with another payment method using the same tax quote, as long as the tax quote is not expired (see Tax quote expiration).

📘
Notes
Tax reporting:
Avalara maintains a record of all taxes owed based on sales. They will work with you to ensure proper tax reporting.
Invoices:
Merchants who are using BlueSnap’s Payment API with Avalara and want to include tax data on their shoppers' invoices/receipts will need to generate these documents outside of BlueSnap.
Australian Shoppers
For shoppers located in Australia, shopping carts will display the text "ABN" instead of "VAT ID" wherever it is applicable.
Colorado Delivery Fee:
Colorado has a delivery fee for any merchant who has a product delivered to a shopper in Colorado. If the retail delivery fee applies, the existing invoice tax line will display "Tax & Delivery Fee". The amount displayed will be the combined amount of any applicable tax and the retail delivery fee. Please note that this fee is not refundable except for cancelled, voided, or certain chargeback transactions.

Separate authorization and capture

You might choose to separate the card authorization and capture steps for a variety of reasons; maybe you sell physical goods, or the product or service will not be ready to be delivered at the time of purchase. This section covers how to include taxes in this scenario.

Before beginning, make sure you've created a tax quote for the transaction. Once complete and you're ready to start processing the transaction, send an Auth Only request to BlueSnap. As part of the required properties, be sure to specify the following:

amount - The total transaction amount, including tax.

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \ 
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "cardTransactionType": "AUTH_ONLY",
  "softDescriptor": "Test transaction",
  "amount": 174.8,
  "currency": "USD",
  "cardHolderInfo": {
    "firstName": "Jane",
    "lastName": "Smith",
    "zip": "92614",
    "country": "us"
  },
  "creditCard": {
    "cardNumber": "4263982640269299",
    "securityCode": "837",
    "expirationMonth": "02",
    "expirationYear": "2023"
  }
}'

When the goods or services are ready to be delivered, send a Capture request to BlueSnap. The following example shows a Capture request for the full authorization amount. If you are using our Reseller Payment Model, the taxReference property included in the example below is required. Otherwise, it is optional.

curl -v -X PUT https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "cardTransactionType": "CAPTURE",
  "taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
  "transactionId": "1011671985"
}'

📘
Please note that partial captures are not supported at this time.

Subscriptions

If you're using BlueSnap's Subscription Engine, you might want to include tax with each subscription charge. This section covers how to accomplish this.

See:

Create a subscription with tax
Update a subscription that includes tax

Create a subscription with tax

Follow the below steps to create a subscription with tax.

Create a tax quote for the initial charge amount of the subscription. For example, you might offer a special discount on the first month of the subscription. Take note of the taxReference value from the API response.

Note: If the initial and recurring charge amounts are the same, then you only need to create one tax quote. You can skip the next step.
Create a tax quote for the recurring charge amount of the subscription. For example, if you offer a special discount for the first subscription charge, then subsequent charges will be the standard price. Take note of the taxReference value from the API response.
Send a Create Subscription request and include initialTaxReference (set to the value from step 1) and recurringTaxReference (set to the value from step 2).

Note: If the initial and recurring charge amounts are the same, you can simply pass one of initialTaxReference or recurringTaxReference set to the value from step 1.

curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/subscriptions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "payerInfo": {
    "zip": 92614,
    "firstName": "John",
    "lastName": "Doe",
    "phone": 1234567890
  },
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "expirationYear": 2023,
        "securityCode": 111,
        "expirationMonth": "07",
        "cardNumber": 4111111111111111
      }
    }
  },
  "planId": 2212064,
  "transactionFraudInfo": {"fraudSessionId": 1234},
  "initialTaxReference": "88abb3f8-d5bf-481f-8298-4a16e8cef94d",
  "recurringTaxReference": " a98d7dc5-d5f4-428a-8481-3fc131f0444b"
}'

Update a subscription that includes tax

If you need to update a subscription's plan or recurring charge amount, create a tax quote for the new charge amount. Then, send an Update Subscription request with recurringTaxReference.

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "overrideRecurringChargeAmount": 44,
  "planId": 2212064,
  "recurringTaxReference": "667195a5-2249-49b6-bb7e-724eb16b3508"
}'

Refunds

To refund a transaction that involves taxes, you'll send a Refund request to BlueSnap.

To issue a full refund, simply omit the amount property from the request body (A code sample for a full refund can be found here). The total transaction amount, including tax, will be refunded in full.

To issue a partial refund, include the following parameters in the request body.

taxAmount - The tax amount to be refunded.
amount - The total amount (including tax) to be refunded.

For example, suppose the original transaction total was $105 for a shirt and necklace. The shopper wants a refund for the shirt that costs $50 before tax. Suppose the tax amount for the shirt was $2.50. The total tax amount to be refunded would be $2.50 (specified by the taxAmount property) and the total refund amount would be $52.50 (specified by the amount property).

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 52.50,
  "taxAmount": 2.50
}'

👍
Storing tax amounts
You might already store details about transactions on your side, such as transaction ID, transaction total, items purchased, and the shopper's ID. In addition to these details, we recommend storing the tax amount for each item purchased.
This simplifies the refund process, as you will already have the transaction total and tax amounts stored in your database.

Taxes

Implementation

1. Map your products to tax codes

2. Create a tax quote

Tax quote expiration

3. Process the transaction

📘
Notes

Separate authorization and capture

📘

Subscriptions

Create a subscription with tax

Update a subscription that includes tax

Refunds

👍
Storing tax amounts

Implementation

1. Map your products to tax codes

2. Create a tax quote

Tax quote expiration

3. Process the transaction

📘Notes

Separate authorization and capture

📘

Subscriptions

Create a subscription with tax

Update a subscription that includes tax

Refunds

👍Storing tax amounts

📘
Notes

👍
Storing tax amounts