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.

Sign up for the beta version here.

This guide will cover the following topics:

Implementation
Separate authorization and capture
Subscriptions
Refunds

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

📘
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.

Separate authorization and capture

You might choose to separate the card authorization and capture steps for a variety of reasons, such as 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.
taxReference - The tax quote reference number.

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",
  "taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
  "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.

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",
  "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

📘
Tax reporting

📘
Invoices

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

📘Tax reporting

📘Invoices

Separate authorization and capture

📘

Subscriptions

Create a subscription with tax

Update a subscription that includes tax

Refunds

👍Storing tax amounts

📘
Tax reporting

📘
Invoices

👍
Storing tax amounts