Transaction Amount Calculation

This page covers transaction amount calculation endpoints, including the Amount Calculation API and the deprecated Fee Calculation endpoint.

Amount Calculation

Request Method: POST

URL Endpoint: /api/calculate/amounts

Name	Type	Required	Default	Description
processor_id	string	true
subtotal	uint	true	null
amount	uint	if line_items or products not present	null
currency	string	true
payment_method	string	true		Can be 'card' or 'ach'
transaction_type	string	true		Can be 'verification', 'auth', 'sale', 'void', 'refund', 'credit'
products	array	if amount or line_items not present	null
products[].id	string	true
products[].name	string	true
products[].description	string	false
products[].price	string	true
products[].local_tax	string	false
products[].national_tax	string	false
products[].fixed_amount	bool	false	false
products[].fixed_qty	bool	false	false
products[].unit_of_measure	string	false	null
line_items	array	if amount or products not present	null
line_items[].id	string	true
line_items[].status	string	true		Can be 'paid', 'pending', 'rejected'
line_items[].type	string	true		Can be 'flat' or 'percentage'
line_items[].name	string	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
line_items[].description	string	false	false	If true, the calculated amount will be added to the total amount
line_items[].unit_price	int	true
line_items[].quantity	float64	true
line_items[].quantity_shipped	float64	false
line_items[].product_code	string	false
line_items[].commodity_code	string	false
line_items[].unit_of_measure	string	false
line_items[].alternate_tax_identifier	string	false
line_items[].taxable	bool	false	false
line_items[].local_tax_rate	string	false		Format is `10.25`
line_items[].national_tax_rate	string	false		Format is `10.25`
line_items[].tax_rate	string	false		Format is `10.25`
line_items[].discount_amount	uint	false
line_items[].freight_amount	uint	false
line_items[].discount_rate	string	false
processor_payment_adjustment	object	false	null
processor_payment_adjustment.type	string	true		Can be 'flat' or 'percentage'
processor_payment_adjustment.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
processor_payment_adjustment.include	bool	false	false	If true, the calculated amount will be added to the total amount
shipping_amount	object	false	null
shipping_amount.type	string	true		Can be 'flat' or 'percentage'
shipping_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
shipping_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
addon_amount	array	false	null
addon_amount[].type	string	true		Can be 'flat' or 'percentage'
addon_amount[].value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
addon_amount[].include	bool	false	false	If true, the calculated amount will be added to the total amount
discount_amount	array	false	null
discount_amount[].type	string	true		Can be 'flat' or 'percentage'
discount_amount[].value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
discount_amount[].include	bool	false	false	If true, the calculated amount will be added to the total amount
duty_amount	object	false	null
duty_amount.type	string	true		Can be 'flat' or 'percentage'
duty_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
duty_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
tip_amount	object	false	null
tip_amount.type	string	true		Can be 'flat' or 'percentage'
tip_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
tip_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
additional_amounts	array	false	null
additional_amounts[].type	string	true		Can be 'flat' or 'percentage'
additional_amounts[].value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
additional_amounts[].include	bool	false	false	If true, the calculated amount will be added to the total amount
tax_amount	object	false	null
tax_amount.type	string	true		Can be 'flat' or 'percentage'
tax_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
tax_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
national_tax_amount	object	false	null
national_tax_amount.type	string	true		Can be 'flat' or 'percentage'
national_tax_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
national_tax_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
local_tax_amount	object	false	null
local_tax_amount.type	string	true		Can be 'flat' or 'percentage'
local_tax_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
local_tax_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
service_fee	object	false	null
service_fee.type	string	true		Can be 'flat' or 'percentage'
service_fee.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
service_fee.include	bool	false	false	If true, the calculated amount will be added to the total amount
surcharge	object	false	null
surcharge.type	string	true		Can be 'flat' or 'percentage'
surcharge.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
surcharge.include	bool	false	false	If true, the calculated amount will be added to the total amount
cc_bin	string	if surcharge allowed	null
country	string	if surcharge allowed	null
state	string	if surcharge allowed	null
flags	object	false
flags.skip_cash_discount	bool	false	false	If true, skips the cash discount calculation
flags.skip_surcharge	bool	false	false	If true, skips the cash surcharge calculation
flags.skip_service_fee	bool	false	false	If true, skips the cash service fee calculation
flags.skip_consumer_choice	bool	false	false	If true, skips the cash consumer choice calculation
flags.include_default_tax_to_total	bool	false	null	If true, and tax has not been overridden, the merchant's default tax amount will be added to the total amount
flags.tax_exempt	bool	false	null	If true, sets the national, local and tax amount fields to 0
flags.processor_surcharge_fallback	bool	false	false	If true, processor's surcharge fallback will be available
flags.add_tax_to_total	bool	false	null	If true, the tax will be added to the total amount
source	string	false

Workflow:

Call the Amount calculation endpoint with the properly filled request
Take the response of the Amount calculation and place it into the Transaction Request into the amounts field and fill the other fields of the request
Submit the transaction with the pre-calculated amounts

➜  ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
    "processor_id": "<processor id>",
    "amount" : 1000,
    "subtotal" : 1000,
    "currency": "USD",
    "payment_method": "card",
    "transaction_type": "sale"
}' { https://sandbox.koipay.io }/api/calculate/amounts

{
  "status": "success",
  "msg": "success",
  "data": {
    "line_items": null,
    "shipping_amount": null,
    "discount_amount": null,
    "freight_amount": null,
    "addon_amount": null,
    "duty_amount": null,
    "tip_amount": null,
    "additional_amounts": null,
    "tax_amount": 180,
    "national_tax_amount": null,
    "local_tax_amount": null,
    "service_fee": 350,
    "surcharge": null,
    "processor_id": "<processor id>",
    "payment_method": "card",
    "included_amounts": {
      "shipping_amount": null,
      "discount_amount": null,
      "duty_amount": null,
      "tip_amount": null,
      "tax_amount": 180,
      "national_tax_amount": null,
      "local_tax_amount": null,
      "service_fee": 350,
      "surcharge": null
    },
    "subtotal": 1000,
    "amount": 1000,
    "additional_total": 0,
    "total": 1530,
    "features": {
      "surcharge": false,
      "cash_discount": false,
      "dual_pricing": false,
      "dual_pricing_v2": false
    },
    "display": {
      "subtotal": {
        "value": 1000,
        "display": true
      },
      "amount": {
        "value": 1000,
        "display": true
      },
      "shipping": {
        "value": 0,
        "display": false
      },
      "freight": {
        "value": 0,
        "display": false
      },
      "duty": {
        "value": 0,
        "display": false
      },
      "discount": {
        "value": 0,
        "display": false
      },
      "service_fee": {
        "value": 350,
        "display": true
      },
      "surcharge": {
        "value": 0,
        "display": false
      },
      "tax": {
        "value": 180,
        "display": true
      },
      "national_tax": {
        "value": 0,
        "display": false
      },
      "local_tax": {
        "value": 0,
        "display": false
      },
      "tip": {
        "value": 0,
        "display": false
      },
      "total": {
        "value": 1530,
        "display": true
      },
      "consumer_choice": {
        "card": 0,
        "ach": 0,
        "display": false
      }
    },
    "disclaimer": {
      "text": "",
      "html": "",
      "display": false
    }
  }
}

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

json

➜  ~ 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.koipay.io }/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
  }
}

Transaction Amount Calculation ​

Amount Calculation ​

Fee Calculation ​

Transaction Amount Calculation

Amount Calculation

Fee Calculation