Surcharge Sandbox Simulation

Sandbox ONLY – This page outlines the surcharge calculation scenarios in the Sandbox environment, for testing purposes.

The surcharges object simulates the surcharge for a credit card sale or refund based on factors such as card brand, billing location, card network rules, and applicable caps. Provide the card BIN, billing postal code, region, and country to simulate the applicable surcharge accurately.

View On Postman

POST Calculate a Surcharge (Sale)

				
					{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/surcharges

In sandbox, percentages at which surcharge will be calculated are set based on the “region”.

Card Brand

subtotal_amount

Region

% at which surcharge is calculated (only applicable to SB Simulation)

response_desc

HTTPS Status_code

MasterCard / VISA

Any amount other than $1.99

Any US state other then CO, NV, NY, CT, ME, MA, and PR

3.00%

Get Successful

200k

American Express / Discover

Any amount other than $1.99

Any US state other then CO, NV, NY, CT, ME, MA, and PR

2.00%

Get Successful

200k

All Card Brands

Any amount other than $1.99

CO

2.00%

Get Successful

200k

All Card Brands

Any amount other than $1.99

NV

1.50%

Get Successful

200k

All Card Brands

Any amount other than $1.99

NY

3.00%

Get Successful

200k

All Card Brands

Any amount other than $1.99

CT, ME, MA, and PR

0%

NOTE: Surcharge is not applicable in these US states

Get Successful

200k

All Card Brands

$1.99

Any US state

INTERNAL ERROR

400 bad request

All Card Brands

Any amount other than $1.99

If region is not a US state

UNSUPPORTED REGION

400 bad request

Example Request

				
					{ 
    "subtotal_amount": 100, 
    "account_number": "40320341", 
    "region": "TX", 
    "postal_code": "88501",
    "country": "US" 
}

Example Response

				
					{ 
    "surcharge_reference_id": "sur_bcc378c8-e66f-46a8-b365-f8f662c9da97", 
    "surcharge_fee_amount": 3.00, 
    "response": 
    { 
        "environment": "sandbox", 
        "response_desc": "Get Successful." 
    } 
}

POST Calculate a Surcharge (Refund)

				
					{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/surcharges

Sandbox Simulation for Full Refund

To do a full refund on sandbox:  Call the Surcharges endpoint for a Sale with the following parameters: 

  • region = “TX” 
  • card brand = “visa” or “master”  
  • subtotal_total = 50.00 
    • This will return a surcharge_fee_amount of $1.50

Example Request: Calculate  a Surcharge (Sale) 

				
					{ 
    "subtotal_amount": 50, 
    "account_number": "42424242", 
    "region": "TX", 
    "postal_code": "88501",
    "country": "US" 
}

Example Response

				
					{ 
    "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f",
    "surcharge_fee_amount": 1.50, 
    "response": 
    { 
        "environment": "sandbox",
        "response_desc": "Get Successful." 
    } 
}

Perform a sale transaction with: 

  • "authorization_amount"= 51.50
  • "surcharge_fee_amount"= 1.50
  • "surcharge_reference_id"= Provide the "surcharge_reference_id" returned in the Surcharges call

Example Request: Sale transaction with Surcharge 

				
					{ 
    "action":"sale", 
    "authorization_amount": 51.5, 
    "surcharge_fee_amount":1.50,
    "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
    "billing_address":
    { 
        "first_name": "Jennifer",
        "last_name": "McFly" 
    }, 
    "card":
    { 
        "card_type": "visa", 
        "name_on_card": "Jennifer McFly", 
        "account_number": "4242424242424242,
        "expire_month": "12", 
        "expire_year": "2030",
        "card_verification_value":"123"
    } 
}

Example Response: 

				
					{ 
    "transaction_id": "trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93", 
    "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
    "location_id": "loc_115161", 
    "action": "sale",
    "authorization_amount": 51.50,
    "surcharge_fee_amount": 1.50,
    "subtotal_amount": 50,
    "authorization_code": "995972",
    "entered_by": "8dbd1adc927b5d85b3a745a2c334fc12",
    "billing_address": 
    { 
        "first_name": "Jennifer",
        "last_name": "McFly"
    }, 
    "card": 
    { 
        "name_on_card": "Jennifer McFly", 
        "last_4_account_number": "1111",
        "masked_account_number": "****1111",
        "expire_month": 12,
        "expire_year": 2030,
        "card_type": "visa" 
    }, 
        "response": 
        {
            "environment": " sandbox ",
            "response_type": "A",
            "response_code": "A01",
            "response_desc": "APPROVED",
            "authorization_code": "995972", 
            "avs_result": "Y",
            "cvv_result": "M" 
  }, 
  "links": 
  { 
    "disputes": "https://api.forte.net/v3/transactions/trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93/disputes", 
    "settlements": "https://api.forte.net/v3/transactions/trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93/settlements", 
    "self": "https://api.forte.net/v3/transactions/trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93/" 
  } 
}

Call the Surcharges endpoint for a Refund with the following parameters: 

  • "subtotal_total"= $50.00
  • "original_transaction_id"= Provide the "transaction_id" from the sale transaction
    • This will return a"surcharge_fee_amount" of $1.50

Example Request: Calculation Surcharge for Refund : 

				
					{ 
"subtotal_amount": 50, 
"original_transaction_id": " trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93" 
}

Example Response:

				
					{ 
"surcharge_reference_id": “sur_a6d9001e-a791-4133-91ed-b10357f0266f",
"surcharge_fee_amount": 1.50,
"response": 
    { 
    "environment": "sandbox",
    "response_desc": "Get Successful." 
    } 
}

Perform a reverse(refund) transaction with: 

  • "authorization_amount"= 51.50
  • "surcharge_fee_amount_total"= 1.50
  • "surcharge_reference_id"= Provide the"surcharge_reference_id retruned in the Surcharges call
  • "original_transaction_id"= Provide the "transaction_id" from the Refund transaction

Example Request: Reverse transaction with surcharge 

				
					{ 
    "action": "reverse", 
    "authorization_amount": 51.50, 
    "subtotal_amount": 50.00, 
    "surcharge_fee_amount": 1.50, 
   "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
    "original_transaction_id": "trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93", 
    "authorization_code": "995972" 
}

Example Response:

				
					{ 
  "transaction_id": "trn_f786965e-7fbf-4950-b815-db3c3eba16cd", 
  "location_id": "loc_115161",
  "original_transaction_id": "trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93", 
  "action": "credit", 
  "authorization_amount": 51.50, 
  "subtotal_amount": 50, 
  "authorization_code": "995972", 
  "entered_by": "8dbd1adc927b5d85b3a745a2c334fc12", 
  "surcharge_reference_id": “sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
  "billing_address": 
    { 
        "first_name": "Jennifer", 
        "last_name": "McFly" 
    }, 
    "surcharge_fee_amount": 1.50, 
    "response": 
    { 
        "environment": " sandbox ", 
        "response_type": "A", 
        "response_code": "A01", 
        "response_desc": "APPROVED",
        "authorization_code": "993966",
        "avs_result": "Y", 
        "cvv_result": "M" 
  }, 
  "links": 
  { 
    "disputes": "https://api.forte.net/v3/transactions/trn_ f786965e-7fbf-4950-b815-db3c3eba16cd /disputes", 
    "settlements": "https://api.forte.net/v3/transactions/trn_ f786965e-7fbf-4950-b815-db3c3eba16cd /settlements", 
    "self": "https://api.forte.net/v3/transactions/trn_ f786965e-7fbf-4950-b815-db3c3eba16cd /" 
  } 
}

Sandbox Simulation for Partial Refund

To do a partial refund on sandbox: 

Call the Surcharges endpoint for a Sale with the following parameters:

  • region = “TX”
  • card brand = “visa” or “master”
  • "subtotal_total"= 100.00
    • This will return a "surcharge_fee_amopunt" of $3.00

Example Request: Calculate Surcharge Refund 

				
					{ 
    "subtotal_amount": 100, 
    "account_number": "42424242", 
    "region": "TX",
    "postal_code": "88501",
    "country": "US" 
}

Example Response:

				
					{ 
    "surcharge_reference_id": “sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
    "surcharge_fee_amount": 3.00, 
    "response": 
    { 
        "environment": " sandbox ", 
        "response_desc": "Get Successful." 
    } 
}

Perform a sale transaction with: 

  • "authorization_amount"= 103.00
  • "surcharge_fee_amount_total"= 3.00
  • "surcharge_reference_id"= Provide the"surcharge_reference_id returned in the Surcharges call

Example Request:

				
					{ 
    "action":"sale", 
    "authorization_amount":103.00, 
    "surcharge_fee_amount":3.00,
    "surcharge_reference_id": “sur_a6d9001e-a791-4133-91ed-b10357f0266f ",
    "billing_address":
    { 
        "first_name": "Jennifer",
        "last_name": "McFly" 
    }, 
        "card":
        { 
            "card_type": "visa",
            "name_on_card": "Jennifer McFly",
            "account_number": "4242424242424242",
            "expire_month": "12",
            "expire_year": "2030",
            "card_verification_value":"123" 
  } 
}

Example Response:

				
					{ 
  "transaction_id": "trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93", 
 "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
  "location_id": "loc_115161",
  "action": "sale",
  "authorization_amount":103.00,
  "surcharge_fee_amount": 3.00,
  "subtotal_amount": 100.00, 
  "authorization_code": "995972", 
  "entered_by": "8dbd1adc927b5d85b3a745a2c334fc12",
  "billing_address": 
  { 
    "first_name": "Jennifer", 
    "last_name": "McFly" 
  }, 
    "card": 
    { 
        "name_on_card": "Jennifer McFly", 
        "last_4_account_number": "1111",
        "masked_account_number": "****1111", 
        "expire_month": 12,
        "expire_year": 2030,
        "card_type": "visa" 
  }, 
    "response": 
    { 
        "environment": " sandbox ",
        "response_type": "A",
        "response_code": "A01",
        "response_desc": "APPROVED", 
        "authorization_code": "995972",
        "avs_result": "Y",
        "cvv_result": "M" 
    }, 
    "links": 
    { 
        "disputes": "https://api.forte.net/v3/transactions/trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93/disputes", 
        "settlements": "https://api.forte.net/v3/transactions/trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93/settlements",
        "self": "https://api.forte.net/v3/transactions/trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93/" 
  } 
}

Call the Surcharges endpoint for a Refund with the following parameters: 

  • "subtotal_total"= $50.00
  • "original_transaction_id"= Provide the "transaction_id"from the Sale transaction
  • This will return a the"surcharge_fee_amount" of $1.50

Example Request: Calculation Surcharge for Refund 

				
					{ 
"subtotal_amount": 50.00, 
"original_transaction_id": "trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93" 
}

Example Response:

				
					{ 
"surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
"surcharge_fee_amount": 1.50, 
"response": 
    { 
    "environment": " sandbox",
    "response_desc": "Get Successful." 
    } 
}

Perform a Refund transaction with: 

  • "authorization_amount"= 51.50
  • "surcharge_fee_amount"= 1.50
  • "surcharge_reference_id"= Provide the"surcharge_reference_id returned in the Surcharges call
  • "original_transaction_id"= Provide the"transaction_id from the Sale transaction

Example Request:

				
					{ 
    "action": "reverse", 
    "authorization_amount": 51.50, 
    "subtotal_amount": 50.00, 
    "surcharge_fee_amount": 1.50, 
   "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
    "original_transaction_id": " trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93", 
    "authorization_code": "995972" 
}

Example Response:

				
					{ 

  "transaction_id": "trn_f786965e-7fbf-4950-b815-db3c3eba16cd", 
  "location_id": "loc_115161",
  "original_transaction_id": "trn_4982e390-c6b8-49d6-b8f9-dcbf1098dd93", 
  "action": "credit", 
  "authorization_amount": 51.50, 
  "subtotal_amount": 50, 
  "authorization_code": "995972", 
  "entered_by": "8dbd1adc927b5d85b3a745a2c334fc12", 
  "surcharge_reference_id": "sur_a6d9001e-a791-4133-91ed-b10357f0266f", 
  "billing_address": 
  { 
    "first_name": "Jennifer", 
    "last_name": "McFly"
    }, 
    "surcharge_fee_amount": 1.50, 
    "response": 
        {
        "environment": " sandbox ", 
        "response_type": "A", 
        "response_code": "A01", 
        "response_desc": "APPROVED", 
        "authorization_code": "993966", 
        "avs_result": "Y", 
        "cvv_result": "M" 
  }, 
  "links": 
  { 
    "disputes": "https://api.forte.net/v3/transactions/trn_ f786965e-7fbf-4950-b815-db3c3eba16cd /disputes", 
    "settlements": "https://api.forte.net/v3/transactions/trn_ f786965e-7fbf-4950-b815-db3c3eba16cd /settlements", 
    "self": "https://api.forte.net/v3/transactions/trn_ f786965e-7fbf-4950-b815-db3c3eba16cd /" 
  } 
  }
On this page