Transaction Amount Calculation

Calculate accurate transaction totals including taxes, fees, surcharges, discounts, and shipping before submitting your transaction. This API handles complex fee programs, processor-specific calculations, and ensures your transaction amounts are correct.

Request Method: POST
URL Endpoint: /api/calculate/amounts

Basic

You must provide one of the following for amount input: amount, line_items, or products. If line_items and products are both empty/null, then subtotal is also required.

Name	Type	Default	Required	Description
amount	uint	null	if line_items or products not present	Base amount in cents (e.g., 1000 = $10.00). Required if not using products or line_items
subtotal	uint	null	if line_items and products are empty	Subtotal amount in cents. Required if line_items and products are both empty/null
processor_id	string			Processor to use for calculation
currency	string			ISO 4217 currency code (e.g., "USD")
payment_method	string			Payment method: card, ach, etc.
transaction_type	string			Transaction type: verification, auth, sale, void, refund, credit
customer_id	string			Customer ID (if using stored customer data)
payment_method_id	string		Conditional*	Payment method ID. Required if customer_id and payment_method are both set
token	string			Payment token (alternative to customer_id)
cc_bin	string			Card number digits for surcharge/fee calculation. Minimum 6 digits required. For most accurate results pass the full card number
country	string			Country code for tax calculation
state	string			State code for tax calculation
source	string			Source identifier for tracking

Card Number for cc_bin

The cc_bin field requires a minimum of 6 digits, but for the most accurate results—especially when determining if a card is surchargeable—you should pass the full card number. The system will extract the necessary BIN information while using the complete number for precise fee and surcharge calculations.

Conditional Requirements

• Required: You must provide one of: amount, line_items, or products
• If line_items and products are both empty/null, then subtotal is also required
• If customer_id is set AND payment_method is set, then payment_method_id is required
• If customer_id is set AND payment_method_id is set, then payment_method is required

Credit Card with BIN

Calculate amounts for a credit card transaction with BIN for surcharge calculation:

Customer with Payment Method ID

Calculate amounts using a stored customer and specific payment method:

Using Customer ID

When using customer_id, the endpoint automatically:

• Retrieves the customer's default payment method (if payment_method_id is not provided)
• Sets the payment method type (card or ach)
• Extracts BIN from stored card (if applicable)
• Uses customer's default billing address for tax calculation (country and state)

Products

Use products array to calculate amounts from product definitions. Alternative to providing amount directly.

Name	Type	Default	Required	Description
products	array	null	if amount or line_items not present	Array of product objects
products[].id	string		Required	Product ID
products[].name	string		Required	Product name
products[].price	string		Required	Product price
products[].description	string			Product description
products[].local_tax	string			Local tax amount
products[].national_tax	string			National tax amount
products[].fixed_amount	bool	false		Whether amount is fixed
products[].fixed_qty	bool	false		Whether quantity is fixed
products[].unit_of_measure	string	null		Unit of measure (e.g., "each", "lb")

Line Items

Use line items for Level 3 data transactions with detailed item information.

Name	Type	Default	Required	Description
line_items	array	null	if amount or products not present	Array of line item objects
line_items[].id	string		Required	Line item identifier
line_items[].status	string		Required	Status: paid, pending, rejected
line_items[].type	string		Required	Type: flat or percentage
line_items[].name	string		Required	Item name
line_items[].description	string			Item description
line_items[].unit_price	int		Required	Unit price in cents
line_items[].quantity	float64		Required	Quantity
line_items[].quantity_shipped	float64			Quantity shipped
line_items[].product_code	string			Product code
line_items[].commodity_code	string			Commodity code
line_items[].unit_of_measure	string			Unit of measure
line_items[].alternate_tax_identifier	string			Alternate tax identifier
line_items[].taxable	bool	false		Whether item is taxable
line_items[].local_tax_rate	string			Local tax rate (format: 10.25)
line_items[].national_tax_rate	string			National tax rate (format: 10.25)
line_items[].tax_rate	string			Tax rate (format: 10.25)
line_items[].discount_amount	uint			Discount amount in cents
line_items[].freight_amount	uint			Freight amount in cents
line_items[].discount_rate	string			Discount rate

Taxes

Configure tax amounts. All tax objects support type (flat or percentage), value, and include (adds to total).

Name	Type	Default	Required	Description
tax_amount	object	null		General tax amount
national_tax_amount	object	null		National tax amount
local_tax_amount	object	null		Local tax amount

Tax Object Fields:

• type (string, required): flat or percentage
• value (uint, required): Amount in cents (flat) or rate (percentage, e.g., 10000 = 10.000%)
• include (bool, default: false): If true, adds calculated amount to total

Fees

Configure service fees, surcharges, and payment adjustments.

Name	Type	Default	Required	Description
service_fee	object	null		Service fee amount
surcharge	object	null		Surcharge amount
processor_payment_adjustment	object	null		Processor-specific payment adjustment

Fee Object Fields:

• type (string, required): flat or percentage
• value (uint, required): Amount in cents (flat) or rate (percentage, e.g., 10000 = 10.000%)
• include (bool, default: false): If true, adds calculated amount to total

Shipping & Other Amounts

Configure shipping, discounts, add-ons, duty, tips, and additional amounts.

Name	Type	Default	Required	Description
shipping_amount	object	null		Shipping cost
discount_amount	array	null		Discount amounts
addon_amount	array	null		Add-on amounts
duty_amount	object	null		Duty amount
tip_amount	object	null		Tip amount
additional_amounts	array	null		Additional custom amounts

Amount Object Fields:

• type (string, required): flat or percentage
• value (uint, required): Amount in cents (flat) or rate (percentage, e.g., 10000 = 10.000%)
• include (bool, default: false): If true, adds calculated amount to total

Payment Details

Fields for payment method identification and location-based calculations.

Name	Type	Default	Required	Description
cc_bin	string			First 6-11 digits of card number (BIN) for surcharge/fee calculation
country	string			Country code for tax calculation
state	string			State code for tax calculation
cc_type	string			Card type (e.g., "visa", "mastercard")

Flags

Control calculation behavior and fee program processing.

Name	Type	Default	Required	Description
flags.skip_cash_discount	bool	false		Skip cash discount calculation
flags.skip_surcharge	bool	false		Skip surcharge calculation
flags.skip_service_fee	bool	false		Skip service fee calculation
flags.skip_consumer_choice	bool	false		Skip consumer choice calculation
flags.include_default_tax_to_total	bool	null		Include merchant's default tax in total if tax not overridden
flags.tax_exempt	bool	null		Set all tax amounts to 0
flags.processor_surcharge_fallback	bool	false		Enable processor's surcharge fallback
flags.add_tax_to_total	bool	null		Add tax to total amount

Use the data object from the response in your transaction request's amounts field.

Fee Calculation

DEPRECATED - Use Amount Calculation

Details

Using this endpoint will calculate any applicable fees that should be applied to the transaction. This includes Surcharge, Cash Discount Fees and Payment Adjustment, if applicable.

Request Method: POST

URL Endpoint: /api/lookup/fees

Name	Type	Required	Description
type	string	yes	Type of request, "integrations"
state	string	no	Billing address state
bin	string	no	6 - 19 digits of a card
customer_id	string	no	Customer ID
payment_id	string	no	Payment method ID for a customer
payment_method	string	yes	The method of payment, i.e 'card' or 'ach'
base_amount	uint	yes	Amount in lowest form of currency. $1.00 = 100

➜  ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
        "type": "integrations",
        "type_id":"",
        "state": "IL",
        "bin": "517246700",
        "payment_method": "card",
        "base_amount": 1000
}' { https://sandbox.gosparrowone.com }/api/api/lookup/fees

{
  "status": "success",
  "msg": "success",
  "data": {
    "service_fee": 0,
    "payment_adjustment": {
      "value": 0,
      "type": ""
    },
    "requested_amount": 1350,
    "discount_amount": null,
    "surcharge": 350
  }
}