Top of Section
BasicsPayment APIEmbedded PaymentsMarketplaceReportingToolsSupport Guides

Surcharges Guide

Learn how to work with surcharges in BlueSnap's API

A surcharge is an additional fee you can add to a transaction when your customer uses their card to complete a sale. BlueSnap's Surcharge API allows you to calculate this surcharge amount based on your configured rate and location, then optionally prorate the fee proportionally across partial captures if needed. Refer to Surcharges for more information about the requirements and implementation.

If you want to enable surcharging to pass those costs to your customers, please contact your account manager or merchant support.

❗️

If you decide surcharging is right for your business, you must adhere to strict card brand, country, and state laws. You are responsible for any fines, penalties, or losses that may occur due to your failure to adhere to surcharging requirements.

Surcharge Tokens

Once the surcharge feature is enabled on your account, you must call the Calculate Surcharge API for every transaction that has an amount greater than $0. The response from this API will determine applicability of the surcharge and provide you with a token that you need to store. Even if the transaction is not eligible for surcharge, this token will be required in the auth and/or capture request.

Be aware that this token can only be used once for Auth Only or Auth Capture calls and will expire after 24 hours. It does not expire for Capture calls. The validated surcharge amount cannot be used across different card payment methods.

Hosted Payment Fields with Surcharge

When using Hosted Payment Fields, you will call the Calculate Surcharge API after the shopper enters their credit card information and before payment is submitted. The Hosted Payment Field token (pfToken), which represents the card information, must be provided in the request to get the appropriate surcharge amount.

As part of compliance requirements, you must display the surcharge fee as a separate line item on the checkout page and update the total payment amount to include the surcharge fee before the shopper submits their payment information to complete the sale.

Hosted Payment Fields with 3-D Secure and Surcharge

If you're using 3-D Secure with Hosted Payment Fields, you must include the surcharge fee in the amount of your 3-D Secure object.

Secured Payment Collector with Surcharge

When using Secured Payment Collector, you will call the Calculate Surcharge API after first initializing the Secured Payment Collector and submitting the shopper's data to BlueSnap (Steps #4 and #5 in the linked guide). Once the surcharge information is obtained, you will once again initialize the Secured Payment Collector and re-submit the data with surcharge.

As part of compliance requirements, you must display the surcharge fee as a separate line item on the checkout page and update the total payment amount to include the surcharge fee before completing the sale.

Secured Payment Collector with 3-D Secure and Surcharge

If you're using 3-D Secure with Secured Payment Collector, you will first initialize the Secured Payment Collector and submit the shopper's data to BlueSnap without 3-DS. Then, call the Calculate Surcharge API and obtain the surcharge information before initializing the Secured Payment Collector with 3-DS and re-submitting the data (that includes surcharge) with 3-DS.

3-D Secure with Returning Shoppers and Surcharge

When using 3-D Secure for a returning (vaulted) shopper, you can call the Calculate Surcharge API from the checkout page at any time before you submit the payment for processing. Ensure that you display the surcharge fee as a separate line item and update the total payment amount to include the surcharge before the shopper submits their payment information.

3-D Secure with Plain Text Cards and Surcharge

When using 3-D Secure with plain text cards, you can call the Calculate Surcharge API from the checkout page at any time before you submit the payment for processing. Ensure that you display the surcharge fee as a separate line item and update the total payment amount to include the surcharge before the shopper submits their payment information.

Plain Payment Details and Surcharge

If you store payment card information yourself, you will include the card details in a Calculate Surcharge request after the shopper provides them. Ensure that you display the surcharge fee as a separate line item on the checkout page and update the total payment amount to include the surcharge before the shopper submits their payment information.

Surcharge API Process

Follow these steps for most surcharge scenarios. If you are processing transactions with Apple Pay, refer to Surcharge with Apple Pay .

📘

Note

Be aware that while testing in the Sandbox environment, all surcharge scenarios will be treated as if the merchant is located in the US with a 3% rate applied. This means that credit cards are surcharged at 3%, while debit and prepaid cards are excluded from surcharging in accordance with US card brand requirements.

Step One: Calculate Surcharge

Send the amount, currency, and payment or shopper information to Calculate Surcharge. Include the fields shown in the below examples depending on whether you're using Hosted Payment Fields, 3-D Secure, or plain payment details.

curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": "210.0",
    "currency": "EUR",
    "paymentMethod": "CC",
    "pfToken": "abcde12345**********"
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": "100.00",
    "currency": "USD",
    "vaultedShopperId": 19669044,
    "creditCard": {}
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": "100.00",
    "currency": "USD",
    "vaultedShopperId": 19669078,
    "creditCard": {
        "cardLastFourDigits": "0009",
        "cardType": "VISA"
    }
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": "100.00",
    "currency": "USD",
    "creditCard": {
      "cardNumber": "4263982640269299",
      "securityCode": "123",
      "expirationMonth": "12",
      "expirationYear": "2026"
    }
}'

BlueSnap will validate surcharge eligibility and return the appropriate surcharge amount and token. If a transaction is eligible for surcharge, the response will have a nonzero amount and a description of "Surcharge calculated successfully."

If not eligible, the amount will be $0 and a description of "Transaction is not eligible for surcharge."

{
    "amount": "30.12",
    "currency": "USD",  
    "payerDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "country": "US",
        "state": "NJ",
        "personalIdentificationNumber":"53033315550"
    },
   "paymentMethod": "CC",
   "creditCard": {
        "cardLastFourDigits": "9299",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "binCategory": "CONSUMER"
    },
   "surchargeInfo": {
        "surchargeReference": 103,
        "surchargeAmount": 3.00,
        "surchargeRate": 2.40,
        "description": "Surcharge calculated successfully",
        "surchargeToken": "eyJhbGciOiJI**********"
   }
}

(Optional) Step Two: Prorate the Surcharge

You can optionally call the Calculate Prorated Surcharge API to calculate a prorated surcharge amount for partial captures. BlueSnap recommends always doing so, as sending a partial capture request without prorating first will result in the system automatically allocating the surcharge amount based on the total capture amount passed.

Call Calculate Prorated Surcharge with the partial amount you intend to capture for the transaction and the surcharge token. For example:

curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate-prorated \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
   "amount": "40.00",
   "surchargeInfo": {
       "surchargeToken": "eyJhbGciOiJI**********"
     }
}'

This will update the token and return the prorated amount.

{
    "amount": "20.00",
    "currency": "USD",
    "surchargeInfo": {
        "surchargeReference": 103,
        "surchargeAmount": 1.20,
        "surchargeRate": 2.40,
        "description": "Surcharge calculated successfully",
        "surchargeToken": "eyJhbGciOiJI**********"
    }
}

The sum of prorated surcharge amounts across all captures will never exceed the initially calculated surcharge fee.

Step Three: Make Payment Call

Make your Auth Only, Auth Capture, or Capture requests with the surcharge token (even if the transaction wasn't eligible) and updated amount (the subtotal + surcharge). For example:

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": "DescTest",
  "amount": "11.00",
  "currency": "USD",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name",
    "zip": "02453"
  },
  "creditCard": {
    "cardNumber": "4263982640269299",
    "securityCode": "837",
    "expirationMonth": "02",
    "expirationYear": "2026"
  },
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJI**********"
  }
}'
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 '
{
  "amount": 11,
  "softDescriptor": "DescTest",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name",
    "zip": "02453"
  },
  "currency": "USD",
  "cardTransactionType": "AUTH_CAPTURE",
  "pfToken": "abcde12345**********",
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJIUzUxMiJ9**********"
  }
}'
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",
  "merchantTransactionId": "merchant-transaction-id-151200",
  "recurringTransaction": "ECOMMERCE",
  "softDescriptor": "Visa",
  "amount": "7.12",
  "currency": "CAD",
  "vaultedShopperId": "97008309",
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJI**********"
  }
}'
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 '
{
  "amount": 256,
  "surchargeInfo": {
    "surchargeAmount": 25,
    "surchargeReference": 106709,
    "description": "Surcharge calculated successfully",
    "surchargeToken": "eyJhbGciOiJI**********"
  },
  "recurringTransaction": "ECOMMERCE",
  "currency": "CAD",
  "cardTransactionType": "AUTH_CAPTURE",
  "pfToken": "abcde12345**********"
}'
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": "DescTest",
  "amount": "11.00",
  "currency": "USD",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name",
    "zip": "02453"
  },
  "creditCard": {
    "cardNumber": "4263982640269299",
    "securityCode": "837",
    "expirationMonth": "02",
    "expirationYear": "2030"
  },
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJI**********"
  }
}'
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 '
{
  "amount": 11,
  "softDescriptor": "DescTest",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name",
    "zip": "02453"
  },
  "currency": "USD",
  "cardTransactionType": "AUTH_ONLY",
  "pfToken": "abcde12345**********",
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJIUzUxMiJ9**********"
  }
}'
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 '
{
    "amount": 11,
    "vaultedShopperId": 20781033,
    "softDescriptor": "DescTest",
    "currency": "USD",
    "cardTransactionType": "AUTH_ONLY"
    "surchargeInfo": {
      "surchargeToken": "eyJhbGciOiJI**********"
    }
}'
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 '
{
  "amount": 51,
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJI**********"
  },
  "vendorInfo": {
    "vendorId": 5003075,
    "commissionPercent": 10
  },
  "cardTransactionType": "CAPTURE",
  "transactionId": 1164362851
}'

Example responses:

{
  "cardTransactionType": "AUTH_CAPTURE",
  "transactionId": "1035511869",
  "softDescriptor": "BLS*DescTest",
  "amount": 11,
  "usdAmount": 11,
  "currency": "USD",
  "transactionApprovalDate": "09/29/2020",
  "transactionApprovalTime": "13:08:47",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name",
    "zip": "02453"
  },
  "vaultedShopperId": 28855193,
  "creditCard": {
    "cardLastFourDigits": "9299",
    "cardType": "VISA",
    "cardSubType": "CREDIT",
    "cardCategory": "PLATINUM",
    "binCategory": "CONSUMER",
    "cardRegulated": "N",
    "issuingBank": "ALLIED IRISH BANKS PLC",
    "issuingCountryCode": "ie"
  },
  "surchargeInfo": {
    "surchargeReference": 403,
    "surchargeAmount": 0.26,
    "surchargeRate": 2.40,
    "description": "Surcharge successfully applied on transaction"
  },
  "processingInfo": {
    "processingStatus": "success",
    "cvvResponseCode": "MA",
    "authorizationCode": "123456",
    "avsResponseCodeZip": "U",
    "avsResponseCodeAddress": "U",
    "avsResponseCodeName": "U",
    "transactionRegion": "US"
  },
  "fraudResultInfo": {}
}
{
    "amount": 210.0,
    "currency": "EUR",
    "payerDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "country": "CA",
        "state": "QC"
    },
    "paymentMethod": "CC",
    "creditCard": {
        "cardLastFourDigits": "4445",
        "cardType": "MASTERCARD",
        "cardSubType": "CREDIT",
        "cardCategory": "STANDARD",
        "expirationMonth": "10",
        "expirationYear": "2029"
    },
    "surchargeInfo": {
        "surchargeReference": 113078,
        "surchargeAmount": 6.30,
        "surchargeRate": 2.40,
        "description": "Surcharge calculated successfully",
        "surchargeToken": "eyJhbGciOiJI**********"
    }
}
{
  "cardTransactionType": "AUTH_CAPTURE",
  "merchantTransactionId": "merchant-transaction-id-151200",
  "transactionId": "1164315839",
  "recurringTransaction": "ECOMMERCE",
  "softDescriptor": "Visa",
  "amount": "7.12",
  "usdAmount": "5.00",
  "currency": "CAD",
  "avsResponseCode": "X",
  "transactionApprovalDate": "01/12/2026",
  "transactionApprovalTime": "16:12:49",
  "vaultedShopperId": "97008309",
  "creditCard": {
    "cardLastFourDigits": "0267",
    "cardType": "MASTERCARD",
    "cardSubType": "CREDIT",
    "binCategory": "CONSUMER",
    "binNumber": "520424",
    "cardRegulated": "Y",
    "expirationMonth": "11",
    "expirationYear": "2029",
    "issuingCountryCode": "us"
  },
  "networkTransactionInfo": {
    "originalNetworkTransactionId": "MCC1199641430112",
    "networkTransactionId": "MCC1199641430112"
  },
  "surchargeInfo": {
    "surchargeReference": "107807",
    "surchargeAmount": 0.12,
    "surchargeRate": 2.40,
    "description": "Surcharge successfully applied on transaction"
  },
  "processingInfo": {
    "processingStatus": "success",
    "cvvResponseCode": "ND",
    "authorizationCode": "OK7330",
    "avsResponseCodeZip": "M",
    "avsResponseCodeAddress": "M",
    "avsResponseCodeName": "U",
    "networkTransactionId": "MCC1199641430112",
    "transactionRegion": "CA"
  },
  "fraudResultInfo": {
    "deviceDataCollector": "N"
  }
}
{
    "cardTransactionType": "AUTH_CAPTURE",
    "transactionId": "1164309345",
    "recurringTransaction": "ECOMMERCE",
    "softDescriptor": "onboardingDefault",
    "amount": 256.00,
    "usdAmount": 187.90,
    "currency": "CAD",
    "avsResponseCode": "Y",
    "transactionApprovalDate": "01/12/2026",
    "transactionApprovalTime": "15:49:22",
    "cardHolderInfo": {
        "firstName": "Fname",
        "lastName": "Lname",
        "email": "[email protected]",
        "country": "CA",
        "address": "Pervomayskaya 32",
        "city": "Moscow",
        "zip": "45546"
    },
    "vaultedShopperId": 97877349,
    "creditCard": {
        "cardLastFourDigits": "0004",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "BUSINESS",
        "binCategory": "COMMERCIAL",
        "binNumber": "400551",
        "cardRegulated": "Y",
        "issuingBank": "LATIN AMERICA AND CARIBBEAN REGION",
        "expirationMonth": "10",
        "expirationYear": "2034",
        "issuingCountryCode": "us"
    },
    "threeDSecure": {
        "authenticationResult": "AUTHENTICATION_UNAVAILABLE"
    },
    "networkTransactionInfo": {
        "originalNetworkTransactionId": "016012009462384",
        "networkTransactionId": "016012009462384"
    },
    "surchargeInfo": {
        "surchargeReference": 106709,
        "surchargeAmount": 6,
        "surchargeRate": 2.40,
        "description": "Surcharge successfully applied on transaction"
    },
    "processingInfo": {
        "processingStatus": "success",
        "cvvResponseCode": "ND",
        "authorizationCode": "OK7790",
        "avsResponseCodeZip": "M",
        "avsResponseCodeAddress": "M",
        "avsResponseCodeName": "U",
        "networkTransactionId": "016012009462384",
        "transactionRegion": "CA"
    },
    "fraudResultInfo": {
        "deviceDataCollector": "N"
    }
}
{
    "amount": 11,
    "vaultedShopperId": 1234,
    "processingInfo": {
        "avsResponseCodeAddress": "M",
        "processingStatus": "success",
        "cvvResponseCode": "MA",
        "avsResponseCodeName": "U",
        "avsResponseCodeZip": "M",
        "transactionRegion": "MA",
        "supportsMultiPartialCapture": true
    },
    "surchargeInfo": {
      "surchargeReference": 403,
      "surchargeAmount": 0.26,
      "surchargeRate": 2.40,
      "description": "Surcharge successfully applied on transaction"
    },
    "softDescriptor": "BLS*DescTest",
    "cardHolderInfo": {
        "firstName": "test first name",
        "lastName": "test last name",
        "zip": "02453"
    },
    "currency": "USD",
    "fraudResultInfo": {"deviceDataCollector": "Y"},
    "creditCard": {
        "cardLastFourDigits": 9299,
        "cardSubType": "CREDIT",
        "cardType": "VISA",
        "cardCategory": "CLASSIC"
    },
    "cardTransactionType": "AUTH_ONLY",
    "transactionId": 38488222,
}
{
    "amount": 11,
    "vaultedShopperId": 1234,
    "processingInfo": {
        "avsResponseCodeAddress": "M",
        "processingStatus": "success",
        "cvvResponseCode": "MA",
        "avsResponseCodeName": "U",
        "avsResponseCodeZip": "M",
        "supportsMultiPartialCapture": true
    },
    "softDescriptor": "BLS*DescTest",
    "cardHolderInfo": {
        "firstName": "test first name",
        "lastName": "test last name",
        "zip": "02453"
    },
    "currency": "USD",
    "creditCard": {
        "cardLastFourDigits": 9299,
        "cardSubType": "CREDIT",
        "cardType": "VISA",
        "cardCategory": "CLASSIC"
    },
    "cardTransactionType": "AUTH_ONLY",
    "transactionId": 38486450,
    "surchargeInfo": {
        "surchargeReference": 113078,
        "surchargeAmount": 6.30,
        "surchargeRate": 2.40,
        "description": "Surcharge calculated successfully",
        "surchargeToken": "eyJhbGciOiJI**********"
    }
}
{
    "cardTransactionType": "AUTH_ONLY",
    "transactionId": "1012751945",
    "softDescriptor": "BLS*DescTest",
    "amount": 11,
    "currency": "USD",
    "vaultedShopperId": 20769005,
    "creditCard": {
        "cardLastFourDigits": "9299",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "CLASSIC"
    },
    "surchargeInfo": {
      "surchargeReference": "107807",
      "surchargeAmount": 0.12,
      "surchargeRate": 2.40,
      "description": "Surcharge successfully applied on transaction"
    },
    "processingInfo": {
        "processingStatus": "success",
        "avsResponseCodeZip": "U",
        "avsResponseCodeAddress": "U",
        "avsResponseCodeName": "U",
        "supportsMultiPartialCapture": true
    }
}
{
    "cardTransactionType": "CAPTURE",
    "vendorInfo": {
        "vendorId": 5003075,
        "commissionPercent": 10
    },
    "vendorsInfo": {
        "vendorsInfoProcessingStatus": "COMPLETED",
        "vendorInfo": [
            {
                "vendorId": 5003075,
                "commissionPercent": 10
            }
        ]
    },
    "transactionId": "1164362851",
    "recurringTransaction": "ECOMMERCE",
    "softDescriptor": "BLS*MARKETPLACE",
    "amount": 51,
    "usdAmount": 51.00,
    "openToCapture": 50.00,
    "currency": "USD",
    "cardHolderInfo": {
        "firstName": "Igubbxey",
        "lastName": "Pkegkrri",
        "country": "us",
        "state": "CA",
        "address": "blue lane 21",
        "city": "london",
        "zip": "123456",
        "phone": "1800808080"
    },
    "vaultedShopperId": 97904159,
    "creditCard": {
        "cardLastFourDigits": "0009",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "CLASSIC",
        "binCategory": "CONSUMER",
        "binNumber": "445701",
        "cardRegulated": "N",
        "issuingBank": "CARD SERVICES FOR CREDIT UNIONS, INC.",
        "expirationMonth": "10",
        "expirationYear": "2029",
        "issuingCountryCode": "us"
    },
    "networkTransactionInfo": {
        "originalNetworkTransactionId": "894728115404290",
        "networkTransactionId": "894728115404290"
    },
    "productDescription": "N/A N/A",
    "surchargeInfo": {
        "surchargeReference": 112952,
        "surchargeAmount": 0.5,
        "surchargeRate": 2.40,
        "description": "Surcharge successfully applied on transaction"
    },
    "processingInfo": {
        "processingStatus": "SUCCESS",
        "cvvResponseCode": "MA",
        "authorizationCode": "11111 ",
        "avsResponseCodeZip": "N",
        "avsResponseCodeAddress": "N",
        "avsResponseCodeName": "U",
        "networkTransactionId": "894728115404290",
        "transactionRegion": "US",
        "supportsMultiPartialCapture": false
    },
    "fraudResultInfo": {
        "deviceDataCollector": "N"
    }
}

(Optional) Step Four: Perform a Refund

If needed, call the Refund API to perform a full or partial refund. Both types of refunds always include the surcharge.

When performing a partial refund, it is recommended to call the Prorate Surcharge API again so the system will calculate the surcharge portion and return the correct total refund. You must provide the surcharge token for those partial refunds.

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": 20.48,    
  "reason": "Refund for order #1039287997",
  "surchargeInfo": {
      "surchargeToken": "eyJhbGciOiJIUzUxMiJ9"
  }
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287689 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "reason": "Refund for order #1039287689"
}'

Example responses:

{
  "refundTransactionId": 1039287997,
  "amount": 20.48,
  "reason": "Refund for order #1039287997",
  "refundStatus": "SUCCESS"
}
{
  "refundTransactionId": 1039287689,
  "reason": "Refund for order #1039287689",
  "refundStatus": "SUCCESS"
}

Surcharge with Tax

If you are using Avalara, surcharge will be included when calculating the tax. After calculating the surcharge, call the Tax Quote API with the total amount (subtotal + surcharge).

curl -v -X POST https://sandbox.bluesnap.com/services/2/tax-quote \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "currency": "CAD",
  "shipTo": {
    "address": "123 Example Place",
    "city": "Toronto",
    "zip": "10001",
    "country": "CA"
  },
  "lines": [
    {
      "quantity": 1,
      "amount": 120,
      "taxCode": "PS081282",
      "itemCode": "Y0001",
      "description": "t-shirt"
    },
    {
      "quantity": 1,
      "amount": 2.88,
      "taxCode": "OF060001",
      "itemCode": "Y0002",
      "description": "Surcharge"
    }
  ]
}'

This will return the totalTax that you can add to the full amount for capture. Be sure to provide the tax reference and surcharge token, such as in this example Auth Capture call:

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 '
{
    "taxReference": "a5f6c85d-5e76-4fec-b938-a688a5b6f9c2",
    "amount": 110.47,
    "surchargeInfo": {
        "surchargeAmount": 1,
        "surchargeToken": "eyJhbGciOi*************"
    },
    "merchantTransactionId": "merchant-transaction-id-557434",
    "softDescriptor": "",
    "cardHolderInfo": {
        "zip": 95124,
        "country": "US",
        "firstName": "John",
        "lastName": "Doe",
        "address": "123 Street",
        "phone": 1800808080,
        "city": "London",
        "state": "CA",
        "email": "[email protected]"
    },
    "currency": "USD",
    "creditCard": {
        "expirationYear": 2029,
        "cardType": "VISA",
        "securityCode": 349,
        "expirationMonth": 11,
        "cardNumber": 4457010000000009
    },
    "cardTransactionType": "AUTH_CAPTURE"
}'
{
    "cardTransactionType": "AUTH_CAPTURE",
    "merchantTransactionId": "merchant-transaction-id-557434",
    "transactionId": "1164399629",
    "softDescriptor": "BLS*network",
    "descriptorPhoneNumber": "18777546871",
    "amount": 110.47,
    "usdAmount": 110.47,
    "currency": "USD",
    "avsResponseCode": "N",
    "transactionApprovalDate": "01/13/2026",
    "transactionApprovalTime": "14:29:25",
    "cardHolderInfo": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "country": "US",
        "state": "CA",
        "address": "123 Street",
        "city": "London",
        "zip": "95124",
        "phone": "1800808080"
    },
    "vaultedShopperId": 97920339,
    "creditCard": {
        "cardLastFourDigits": "0009",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "CLASSIC",
        "binCategory": "CONSUMER",
        "binNumber": "445701",
        "cardRegulated": "N",
        "issuingBank": "CARD SERVICES FOR CREDIT UNIONS, INC.",
        "expirationMonth": "11",
        "expirationYear": "2029",
        "issuingCountryCode": "us"
    },
    "networkTransactionInfo": {
        "originalNetworkTransactionId": "394822839733757",
        "networkTransactionId": "394822839733757"
    },
    "taxReference": "a5f6c85d-5e76-4fec-b938-a688a5b6f9c2",
    "surchargeInfo": {
        "surchargeReference": 113462,
        "surchargeAmount": 1,
        "surchargeRate": 2.40,
        "description": "Surcharge successfully applied on transaction"
    },
    "processingInfo": {
        "processingStatus": "success",
        "cvvResponseCode": "MA",
        "authorizationCode": "11111 ",
        "avsResponseCodeZip": "N",
        "avsResponseCodeAddress": "N",
        "avsResponseCodeName": "U",
        "networkTransactionId": "394822839733757",
        "transactionRegion": "US"
    },
    "fraudResultInfo": {
        "deviceDataCollector": "N"
    }
}

Surcharge with Wallets

The Calculate Surcharge API and surcharge token should also be used when processing Apple Pay and Google Pay transactions, even if the transaction is not eligible for surcharge.

Apple Pay

When using Apple Pay, you will call the Calculate Surcharge API after retrieving card type information from Apple Pay's payment method selected event.

Step 1: Payment Method Selected

Listen to the ApplePayJS.ApplePayPaymentMethodSelectedEvent. This fires when the shopper selects a payment card and returns the ApplePayPaymentMethod object.

Data should be mapped between Apple Pay and BlueSnap as:

  • network (Apple Pay) to cardType (BlueSnap)
  • ApplePayPaymentMethodType (Apple Pay) to cardSubType (BlueSnap)

This cardType and cardSubType will be used to calculate the surcharge.

📘

For privacy reasons, only the type property is provided in most cases before the shopper authorizes the transaction. Its possible values are "debit", "credit", "prepaid", or "store".

Step 2: Calculate Surcharge

After receiving the event information, call Calculate Surcharge with the cardType and cardSubType as shown below. BlueSnap recommends providing as many details as possible to receive the best calculation, including the card type and subtype, whenever available. If you have the billing information for the transaction, you should provide that in the request as well.

curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "wallet": {
    "walletType": "APPLE_PAY",
    "tokenizedCard": {
      "cardType": "MASTERCARD",
      "cardSubType": "CREDIT"
    },
    "billingContactInfo": {
      "country": "us"
    }
  },
  "amount": "20.00",
  "currency": "USD"
}'

This API will return the surcharge amount and surcharge token. If the response indicates that this transaction is not eligible for surcharge, the surcharge amount will be 0.

Step 3: Complete Selection with Apple Pay

Call completePaymentMethodSelection with the updated amount (the subtotal + surcharge amount) and line items to complete the selection.

When you create the Apple Pay session, the type should be "pending" as shown below. If set to "final", the completePaymentMethodSelection() request will fail.

total: { label: 'Your Label', amount: '10.00', type: 'pending' },

You can then proceed to process the transaction with the updated amount. Recall that you will need to provide the surcharge token when you call BlueSnap's Payment API, such as in this example Auth Capture call:

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": "DescTest",
  "amount": 11,
  "currency": "USD",
  "wallet": {
    "walletType": "APPLE_PAY",
    "encodedPaymentToken": "ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd"
  },
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJI**********"
  }
}'

Google Pay

Although surcharging is not supported with Google Pay, you must still call Calculate Surcharge before completing the transaction and include the surcharge token in your Payment API calls. The surcharge amount will always be 0.

curl -v -X POST https://sandbox.bluesnap.com/services/2/surcharge/calculate \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "wallet": {
    "walletType": "GOOGLE_PAY",
    "tokenizedCard": {
      "cardType": "MASTERCARD",
      "cardSubType": "CREDIT"
    },
    "billingContactInfo": {
      "country": "us"
    }
  },
  "amount": "210.00",
  "currency": "USD"
}'
{
    "amount": 210.00,
    "currency": "USD",
    "paymentMethod": "GOOGLE_PAY",
    "surchargeInfo": {
        "surchargeReference": 809,
        "surchargeAmount": 0,
        "surchargeRate": 0,
        "description": "Transaction is not eligible for surcharge",
        "surchargeToken": "eyJhbGciOiJIUzUxMiJ9****"
    },
    "wallet": {
        "walletType": "GOOGLE_PAY",
        "encodedPaymentToken": "eyJwYXltZW50TWV0aG9kRGF0YSI6eyJkZXNj..."
    }
}
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": "DescTest",
  "amount": 210,
  "currency": "USD",
  "productDescription": "example",
  "wallet": {
    "walletType": "GOOGLE_PAY",
    "encodedPaymentToken": "ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd"
  },
  "surchargeInfo": {
    "surchargeToken": "eyJhbGciOiJI**********"
  }
}'

Updated 19 days ago

Updated 19 days ago