The Calculate Surcharge request allows you to determine a transaction's eligibility for surcharge as well as its full surcharge amount, if applicable.

When surcharging is enabled, this request must be made before each transaction that has an amount greater than $0. It will return the surcharge amount, surcharge reference, description, and token. You are required to display the surcharge amount as a separate line item on the checkout page before submitting payment.

Surcharge Token

You must include the surcharge token in all auth and/or capture requests that have an auth amount greater than $0, even those not eligible for surcharge.

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.

Surcharge Eligibility

If a transaction is eligible for surcharge, this API response will have a nonzero surcharge amount and the description will say "Surcharge calculated successfully."

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

Request Content

Send a surchargeCalculation object, with the following:

Property	Type	Required
`currency`	string	required
`amount`	string	required
`pfToken`	string	required if using Hosted Payment Fields
`wallet`	container	required if using Apple Pay; (see wallet)
`vaultedShopperId`	integer	optional
`paymentMethod`	string	optional; inferred automatically if `creditCard` is provided
`creditCard`	container	required if you are not using Hosted Payment Fields or a vaulted shopper; (see creditCard)

Response Details

If successful, the response HTTP status code is 200 OK.
The response contains the surchargeCalculation object.

Examples

Request Examples

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": "eyJhbGciOiJIUzI1NiJ9**********"
}'

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"
    }
}'

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"
}'

Response Example

{
    "amount": "30.12",
    "currency": "USD",  
    "payerDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "johnDoe@test.com",
        "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": "eyJhbGciOiJIUzUxMiJ9**********"
   }
}

API Explorer