swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation taxes API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: taxes
description: tax calculation service
paths:
/vas/v2/tax:
post:
summary: Calculate Taxes
description: "The tax calculation service provides real-time sales tax and VAT calculations for orders placed with your business worldwide. \nIt enhances your ability to conduct business globally and enables you to avoid the risk and complexity of managing online tax calculation. \nThe service supports product-based tax rules and exemptions for goods and services. \nThe tax rates are updated twice a month and calculations include sub-level detail (rates per taxing jurisdiction, names and types of jurisdictions).\nImplementation guidance, list of supported countries, and information on tax reporting are in the [Tax User Guide](https://developer.cybersource.com/docs/cybs/en-us/tax-calculation/developer/all/rest/tax-calculation/tax-overview.html).\nThe availability of API features for a merchant can depend on the portfolio configuration and may need to be enabled at the portfolio level before they can be added to merchant accounts.\n"
operationId: calculateTax
x-devcenter-metaData:
categoryTag: Value_Added_Service
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/tax-calculation/developer/all/rest/tax-calculation/tax-overview.html
tags:
- taxes
parameters:
- name: taxRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 59
description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
partner:
type: object
properties:
developerId:
type: string
maxLength: 8
description: 'Identifier for the developer that helped integrate a partner solution to CyberSource.
Send this value in all requests that are sent through the partner solutions built by that developer.
CyberSource assigns the ID to the developer.
**Note** When you see a developer ID of 999 in reports, the developer ID that was submitted is incorrect.
'
solutionId:
type: string
maxLength: 8
description: 'Identifier for the partner that is integrated to CyberSource.
Send this value in all requests that are sent through the partner solution. CyberSource assigns the ID to the partner.
**Note** When you see a solutionId of 999 in reports, the solutionId that was submitted is incorrect.
'
comments:
type: string
description: Brief description of the order or any comment you wish to add to the order.
taxInformation:
type: object
properties:
reportingDate:
type: string
maxLength: 8
description: 'Reporting date of transaction. Format: YYYYMMDD. Defaults to current date if not specified.
Optional for U.S., Canadian, international tax, and value added taxes.
'
dateOverrideReason:
type: string
maxLength: 50
description: 'If a past or future date is specified in `orderInformation.invoiceDetails.invoiceDate`, then provide the reason for that for audit purposes.
Typical reasons include: ''Return'', ''Layaway'', ''Imported''.
Optional for U.S., Canadian, international tax, and value added taxes.
'
nexus:
description: 'Comma-separated list of states or provinces in which merchandise is taxable. Note merchandise may be still be non-taxable or tax exempt depending on the product taxability. Indicate the type of product you are selling in the product code field for product-level taxability rules to be applied. Do not use both the `taxInformation.nexus` and `taxInformation.noNexus` fields in your request. If you do not include this field in a tax calculation service request, the tax system makes its calculations as if you have nexus in every US state or Canadian province. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf).
If you indicate you do not have nexus in the destination state, jurisdiction level fields are left blank in the Tax Detail Report.
Optional field for U.S. and Canadian taxes only. Either this field or `taxInformation.noNexus` is required if you do not have nexus in every state or province.
Not applicable for international and value added taxes.
'
type: array
items:
type: string
maxLength: 2
noNexus:
description: 'Comma-separated list of states or provinces where you do not have nexus. Check with a tax advisor to determine where your business has nexus. Do not use both the `taxInformation.nexus` and `taxInformation.noNexus` fields in your request. If you do not include this field in a tax calculation service request, the tax system makes its calculations as if you have nexus in every US state or Canadian province.
Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf).
If you indicate you do not have nexus in the destination state, jurisdiction level fields are left blank in the Tax Detail Report.
Optional field for U.S. and Canadian taxes only. Either this field or `taxInformation.nexus` is required if you do not have nexus in every state or province.
Not applicable for international and value added taxes.
'
type: array
items:
type: string
maxLength: 2
showTaxPerLineItem:
type: string
description: 'Whether or not to display tax amounts for each line item. This field can contain one of the following values:
- `Yes` - Display tax amounts for each line item
- `No` (default) - Do not display tax amounts for each line item
Optional for U.S., Canadian, international tax, and value added taxes.
'
commitIndicator:
type: boolean
description: 'Indicates whether this is a committed tax transaction. For a committed tax transaction, the status in the Tax Detail Report is "Committed." For an uncommitted tax transaction, the status in the Tax Detail Report is "Uncommitted." Possible values:
- `true`: This is a committed tax transaction.
- `false` (default): This is not a committed tax transaction.
A committed tax request is a tax service request that sets the status field in the Tax Detail Report to committed.
The committed status indicates that the amount calculated by the tax service is included in the amount of a capture or credit.
Use a void service request to cancel a committed tax request or a committed refund tax request. The void transaction is included as a separate entry in the Tax Detail Report. The value of the status field is cancelled. The value of the link ID is the request ID of the committed tax request or refund tax request that was voided. You can use the value of the link ID to reconcile your orders.
Optional for U.S., Canadian, international tax, and value added taxes.
For more information on Tax Detail Report features refer the [Tax Service Guide](https://developer.cybersource.com/docs/cybs/en-us/tax-calculation/developer/all/rest/tax-calculation/tax-overview.html).
'
refundIndicator:
type: boolean
description: 'Indicates whether this is a refund tax transaction. For a refund tax transaction, amounts in the Tax Detail Report will be negative.
Possible values:
- `true`: This is a refund tax transaction.
- `false` (default): This is not a refund tax transaction.
A refund tax request is a tax service request that sets the transaction type field in the Tax Detail Report to refunded and makes the reported amount negative.
Tax amounts are returned as positive amounts in reply messages, but they are saved in reports as negative amounts which enables the reporting software to accurately calculate the aggregate amounts.
Optional for U.S., Canadian, international tax, and value added taxes.
For more information on Tax Detail Report features refer the [Tax Service Guide](https://developer.cybersource.com/docs/cybs/en-us/tax-calculation/developer/all/rest/tax-calculation/tax-overview.html).
'
orderInformation:
type: object
properties:
amountDetails:
type: object
properties:
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character [ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
#### Used by
**Authorization**
Required field.
**Authorization Reversal**
For an authorization reversal (`reversalInformation`) or a capture (`processingOptions.capture` is set to `true`), you must use the same currency that you used in your payment authorization request.
#### PIN Debit
Currency for the amount you requested for the PIN debit purchase. This value is returned for partial authorizations. The issuing bank can approve a partial amount if the balance on the debit card is less than the requested transaction amount. For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Returned by PIN debit purchase.
For PIN debit reversal requests, you must use the same currency that was used for the PIN debit purchase or PIN debit credit that you are reversing.
For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Required field for PIN Debit purchase and PIN Debit credit requests.
Optional field for PIN Debit reversal requests.
#### GPX
This field is optional for reversing an authorization or credit.
#### DCC for First Data
Your local currency.
#### Tax Calculation
Required for international tax and value added tax only.
Optional for U.S. and Canadian taxes.
Your local currency.
'
billTo:
type: object
properties:
address1:
type: string
maxLength: 60
description: 'First line of the billing street address.
#### Tax Calculation
Required for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
address2:
type: string
maxLength: 60
description: 'Second line of the billing street address.
#### Tax Calculation
Optional for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
locality:
type: string
maxLength: 50
description: 'Credit card billing city.
#### Tax Calculation
Required for U.S. and Canadian taxes only. Not applicable to international and value added taxes.
'
administrativeArea:
type: string
maxLength: 2
description: 'Credit card billing state or province.
#### Tax Calculation
Required for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
postalCode:
type: string
maxLength: 10
description: 'Postal code for the billing address. The postal code must consist of 5 to 9 digits.
If the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
**Example**: 12345-6789
If the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha] [numeric][alpha][numeric]
**Example**: A1B 2C3
#### Tax Calculation
Required for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
country:
type: string
maxLength: 2
description: 'Credit card billing country. Use the [ISO Standard Country Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf).
If `orderInformation.shipTo.country` is not provided, `orderInformation.billTo.country` is used in its place. If `orderInformation.billTo.country` is set to `US` or `CA`, then `orderInformation.billTo.postalCode` and `orderInformation.billTo.administrativeArea` are also required.
#### Tax Calculation
Required for U.S., Canadian, international and value added taxes.
'
shippingDetails:
type: object
properties:
shipFromLocality:
type: string
maxLength: 50
description: 'City where the product is shipped from.
This field is used only when the `orderInformation.shipTo.administrativeArea` and `orderInformation.shipTo.country` fields are present.
**NOTE** If this field appears in a `lineItems` object, then the value of this field in the `lineItems` object overrides the value of the corresponding field at the request-level or order-level object.
#### Tax Calculation
This field is used to determine tax rules and/or rates applied to the transaction based on sourcing.
Optional for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
shipFromCountry:
type: string
maxLength: 2
description: 'Country from which the order is shipped. This field is used only when `orderInformation.shippingDetails.shipFromLocality` and `orderInformation.shippingDetails.shipFromAdministrativeArea` are present. Use the [ISO Standard Country Codes](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf).
**NOTE** If this field appears in a `lineItems` object, then the value of this field in the `lineItems` object overrides the value of the corresponding field at the request-level or order-level object.
#### Tax Calculation
This field is used to determine tax rules and/ or rates applied to the transaction based on sourcing.
Optional for U.S., Canadian, international tax, and value added taxes.
'
shipFromPostalCode:
type: string
maxLength: 10
description: 'Postal code where the product is shipped from.
#### Tax Calculation
This field is used to determine tax rules and/or rates applied to the transaction based on sourcing.
Optional for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
shipFromAdministrativeArea:
type: string
maxLength: 2
description: 'State from which the order is shipped. This field is used only when `orderInformation.shippingDetails.shipFromLocality` and `orderInformation.shippingDetails.shipFromCountry` are present. Use the [State, Province, and Territory Codes for the United States and Canada](http://apps.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf).
**NOTE** If this field appears in a `lineItems` object, then the value of this field in the `lineItems` object overrides the value of the corresponding field at the request-level or order-level object.
#### Tax Calculation
This field is used to determine tax rules and/or rates applied to the transaction based on sourcing.
Optional for U.S. and Canadian taxes. Not applicable to international and value added taxes.
'
shipTo:
type: object
properties:
country:
type: string
description: 'Country of the shipping address. Use the two-character [ISO Standard Country Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf)
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
maxLength: 3
administrativeArea:
type: string
maxLength: 50
description: "State or province of the shipping address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf) (maximum length: 2) \n\nRequired field for authorization if any shipping address information is included in the request and shipping to the U.S.\nor Canada; otherwise, optional.\n\n#### Tax Calculation\nOptional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.\nBilling address objects will be used to determine the cardholder's location when shipTo objects are not present.\n"
locality:
type: string
maxLength: 50
description: 'City of the shipping address.
Required field for authorization if any shipping address information is included in the request and shipping to the U.S. or
Canada; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
postalCode:
type: string
maxLength: 32
description: 'Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
Required field for authorization if any shipping address information is included in the request and
shipping to the U.S. or Canada; otherwise, optional.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
Example A1B 2C3
#### American Express Direct
Before sending the postal code to the processor, all nonalphanumeric characters are removed and, if the
remaining value is longer than nine characters, the value is truncated starting from the right side.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address1:
type: string
maxLength: 60
description: 'First line of the shipping address.
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address2:
type: string
maxLength: 60
description: 'Second line of the shipping address.
Optional field.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address3:
type: string
maxLength: 60
description: 'Third line of the shipping address.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
lineItems:
type: array
items:
type: object
properties:
productSKU:
type: string
maxLength: 255
description: 'Product identifier code. Also known as the Stock Keeping Unit (SKU) code for the product.
For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`), this field is required when `orderInformation.lineItems[].productCode` is not set to **default** or one of the other values that are related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`), this field is
required when `orderInformation.lineItems[].productCode` is not `default` or one of the values related to shipping and/or handling.
'
productCode:
type: string
maxLength: 255
description: 'Type of product. The value for this field is used to identify the product category (electronic, handling, physical,
service, or shipping). The default value is `default`.
If you are performing an authorization transaction (`processingOptions.capture` is set to `false`), and you set
this field to a value other than `default` or one of the values related to shipping and/or handling, then
`orderInformation.lineItems[].quantity`, `orderInformation.lineItems[].productName`, and
`orderInformation.lineItems[].productSku` fields are required.
Optional field.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
The Product Codes for the tax service are located in the Cybersource Tax Codes guide. Contact Customer Support to request the guide. If you don''t send a tax service Product Code in your tax request, product-based rules or exemptions will not be applied and the transaction will default to fully taxable in the locations where you''ve indicated you need to collect tax [by way of nexus, no nexus, or seller registration number fields].
'
quantity:
type: integer
minimum: 1
maximum: 999999999
default: 1
description: 'Number of units for this order. Must be a non-negative integer.
The default is `1`. For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of the other values
related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
productName:
type: string
maxLength: 255
description: 'For an authorization or capture transaction (`processingOptions.capture` is `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of
the other values that are related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
unitPrice:
type: string
maxLength: 15
description: 'Per-item price of the product. This value for this field cannot be negative.
You must include either this field or the request-level field `orderInformation.amountDetails.totalAmount` in your request.
You can include a decimal point (.), but you cannot include any other special characters.
The value is truncated to the correct number of decimal places.
#### DCC with a Third-Party Provider
Set this field to the converted amount that was returned by the DCC provider. You must include either
the 1st line item in the order and this field, or the request-level field `orderInformation.amountDetails.totalAmount` in your request.
#### Tax Calculation
Required field for U.S., Canadian, international and value added taxes.
#### Zero Amount Authorizations
If your processor supports zero amount authorizations, you can set this field to 0 for the
authorization to check if the card is lost or stolen.
#### Maximum Field Lengths
For GPN and JCN Gateway: Decimal (10)
All other processors: Decimal (15)
'
taxAmount:
type: string
maxLength: 15
description: "Total tax to apply to the product. This value cannot be negative. The tax amount and the offer amount must\nbe in the same currency. The tax amount field is additive.\n\nThe following example uses a two-exponent currency such as USD:\n\n 1. You include each line item in your request.\n ..- 1st line item has amount=10.00, quantity=1, and taxAmount=0.80\n ..- 2nd line item has amount=20.00, quantity=1, and taxAmount=1.60\n 2. The total amount authorized will be 32.40, not 30.00 with 2.40 of tax included.\n\nOptional field.\n\n#### Airlines processing\nTax portion of the order amount. This value cannot exceed 99999999999999 (fourteen 9s).\nFormat: English characters only.\nOptional request field for a line item.\n\n#### Tax Calculation\nOptional field for U.S., Canadian, international tax, and value added taxes.\n\nNote if you send this field in your tax request, the value in the field will override the tax engine\n"
orderAcceptance:
type: object
description: The Order Acceptance address fields may be used by the tax service to determine the taxability of the order o
# --- truncated at 32 KB (102 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-taxes-api-openapi.yml