Navigate Pages

Loading....

Recently Changed

Loading....

Home / API Platform / Payment as a Service / Appendix - A

Appendix - A

Table of Contents [ Hide]

Tax.XML

A standard has been created for dealing with Country and State / Province selections as well as Tax and Shipping calculations. The following sections describe a methodology for incorporating a series of standard XML files when dealing with country, state, tax and shipping.

The XML files provided are for your convenience and the discussions are just suggestions for incorporating the XML’s in web applications.

Click to download the XML files used in the following sections: Standards.XML

For questions or comments about the standards please use the forums at: http://forums.clickandpledge.com

The following XML files are described below:

Countries.XML
ISO country codes
States.XML
Shipping.XML
Tax.XML

Countries.XML

The following two sample nodes are from the Countries.XML.

<Country Name="Afghanistan" Abbrev="AF" Code="004" visible="true">
</Country>

& with optional parameters:

<Country Name="United States" Abbrev="US" Code="840" visible="true">
<StatesFileName>"US_States.xml"</StatesFileName>
<Order>100</Order>
<ShippingZone>1</ShippingZone>
<TaxPolicy>1</TaxPolicy>
</Country>

Each node has the following mandatory attributes:

Name: Country name as it should appear in the country pull down menu.
Abbrev: Country name abbreviation as it may be used in the country pull down menu.
Code: ISO country code used by the API
Visible: If set to TRUE the country name appears in the country pull down menu, if set to FALSE the country name will not appear in the country pull down menu.

The visible node allows for customizing the pull down menu so only countries that are serviced appear in the Billing & Shipping country pull down menu.

Each node may have the following optional attributes using the additional XML files included in the Standars.XML file.

StatesFileName: The file path to the states or province names. If a selected country has a state file listed the Billing/Shipping states/province pull down menu will show the listed states. If no state/province file is used then a text box appears allowing the user to type the state or province. Currently only US_States.xml is offered in the Standars.xml file. We will add additional states as they become available. Please send us additional files for inclusion into the standards to: Support@ClickandPledge.com.
Order: The country name’s display order in the pull down menu. It is recommended that a separator be used to separate ordered countries with un-ordered countries. A country pull down menu shows the countries sorted numerically for those using the <Order> node and will list other countries alphabetically. A horizontal line separates the numerically ordered and alphabetically ordered countries.
ShippingZone: Shipping zone may be defined for a country. The shipping zone details are discussed in the Shipping section. Country shipping zone will be used if no zone is defined for a state.
TaxPolicy: Tax policy may be defined for a country. The tax policy details are discussed in the Tax section. Tax policy will be used if no tax policy is defined for a state.

ISO Code / Country

For an up-to-date list please refer to: http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm

004 Afghanistan

008 Albania

010 Antarctica

012 Algeria

016 American Samoa

020 Andorra

024 Angola

028 Antigua and Barbuda

031 Azerbaijan

032 Argentina

036 Australia

040 Austria

044 Bahamas

048 Bahrain

050 Bangladesh

051 Armenia

052 Barbados

056 Belgium

060 Bermuda

064 Bhutan

068 Bolivia

070 Bosnia and Herzegovina

072 Botswana

074 Bouvet Island

076 Brazil

084 Belize

086 British Indian Ocean Territory

090 Solomon Islands

092 Virgin Islands, British

096 Brunei Darussalam

100 Bulgaria

104 Myanmar

108 Burundi

112 Belarus

116 Cambodia

120 Cameroon

124 Canada

132 Cape Verde

136 Cayman Islands

140 Central African Republic

144 Sri Lanka

148 Chad

152 Chile

156 China

158 Taiwan, Province of China

162 Christmas Island

166 Cocos (Keeling) Islands

170 Colombia

174 Comoros

175 Mayotte

178 Congo

180 Congo, the Democratic Republic of the

184 Cook Islands

188 Costa Rica

191 Croatia

192 Cuba

196 Cyprus

203 Czech Republic

204 Benin

208 Denmark

212 Dominica

214 Dominican Republic

218 Ecuador

222 El Salvador

226 Equatorial Guinea

231 Ethiopia

232 Eritrea

233 Estonia

234 Faroe Islands

238 Falkland Islands (Malvinas)

239 South Georgia and the South Sandwich Islands

242 Fiji

246 Finland

248 Åland Islands

250 France

254 French Guiana

258 French Polynesia

260 French Southern Territories

262 Djibouti

266 Gabon

268 Georgia

270 Gambia

275 Palestinian Territory, Occupied

276 Germany

288 Ghana

292 Gibraltar

296 Kiribati

300 Greece

304 Greenland

308 Grenada

312 Guadeloupe

316 Guam

320 Guatemala

324 Guinea

328 Guyana

332 Haiti

334 Heard Island and McDonald Islands

336 Holy See (Vatican City State)

340 Honduras

344 Hong Kong

348 Hungary

352 Iceland

356 India

360 Indonesia

364 Iran, Islamic Republic of

368 Iraq

372 Ireland

376 Israel

380 Italy

384 Côte d'Ivoire

388 Jamaica

392 Japan

398 Kazakhstan

400 Jordan

404 Kenya

408 Korea, Democratic People's Republic of

410 Korea, Republic of

414 Kuwait

417 Kyrgyzstan

418 Lao People's Democratic Republic

422 Lebanon

426 Lesotho

428 Latvia

430 Liberia

434 Libyan Arab Jamahiriya

438 Liechtenstein

440 Lithuania

442 Luxembourg

446 Macao

450 Madagascar

454 Malawi

458 Malaysia

462 Maldives

466 Mali

470 Malta

474 Martinique

478 Mauritania

480 Mauritius

484 Mexico

492 Monaco

496 Mongolia

498 Moldova, Republic of

499 Montenegro

500 Montserrat

504 Morocco

508 Mozambique

512 Oman

516 Namibia

520 Nauru

524 Nepal

528 Netherlands

530 Netherlands Antilles

533 Aruba

540 New Caledonia

548 Vanuatu

554 New Zealand

558 Nicaragua

562 Niger

566 Nigeria

570 Niue

574 Norfolk Island

578 Norway

580 Northern Mariana Islands

581 United States Minor Outlying Islands

583 Micronesia, Federated States of

584 Marshall Islands

585 Palau

586 Pakistan

591 Panama

598 Papua New Guinea

600 Paraguay

604 Peru

608 Philippines

612 Pitcairn

616 Poland

620 Portugal

624 Guinea-Bissau

626 Timor-Leste

630 Puerto Rico

634 Qatar

638 Réunion

642 Romania

643 Russian Federation

646 Rwanda

652 Saint Barthélemy

654 Saint Helena

659 Saint Kitts and Nevis

660 Anguilla

662 Saint Lucia

663 Saint Martin (French part)

666 Saint Pierre and Miquelon

670 Saint Vincent and the Grenadines

674 San Marino

678 Sao Tome and Principe

682 Saudi Arabia

686 Senegal

688 Serbia

690 Seychelles

694 Sierra Leone

702 Singapore

703 Slovakia

704 Viet Nam

705 Slovenia

706 Somalia

710 South Africa

716 Zimbabwe

724 Spain

732 Western Sahara

736 Sudan

740 Suriname

744 Svalbard and Jan Mayen

748 Swaziland

752 Sweden

756 Switzerland

760 Syrian Arab Republic

762 Tajikistan

764 Thailand

768 Togo

772 Tokelau

776 Tonga

780 Trinidad and Tobago

784 United Arab Emirates

788 Tunisia

792 Turkey

795 Turkmenistan

796 Turks and Caicos Islands

798 Tuvalu

800 Uganda

804 Ukraine

807 Macedonia, the former Yugoslav Republic of

818 Egypt

826 United Kingdom

831 Guernsey

832 Jersey

833 Isle of Man

834 Tanzania, United Republic of

840 United States

850 Virgin Islands, U.S.

854 Burkina Faso

858 Uruguay

860 Uzbekistan

862 Venezuela

876 Wallis and Futuna

882 Samoa

887 Yemen

894 Zambia

States.XML

The following two sample nodes are from the US_States.XML. Other State or Province XML’s may be defined using the same standard. Please send us [support@clickandpledge.com] any other state or province XML’s that you create for inclusion in the list.

<State Name="Alabama" Abbrev="AL" visible="true">
</State>

& with optional parameters:

</State>

Each node has the following mandatory attributes:

Name: State name as it should appear in the state pull down menu.
Abbrev: State name abbreviation as it may be used in the state pull down menu.
Visible: If set to TRUE the state name appears in the state pull down menu, if set to FALSE the state name will not appear in the state pull down menu.

Each node may have the following optional attributes using the additional XML files included in the Standars.XML file.

Order: The state name’s display order in the pull down menu. It is recommended that a separator be used to separate ordered states with un-ordered states. A state pull down menu shows the states sorted numerically for those using the <Order> node and will list other states alphabetically. A horizontal line separates the numerically ordered and alphabetically ordered states.
ShippingZone: Shipping zone may be defined for a state. The shipping zone details are discussed in the Shipping section. If no shipping zone is listed for the state, the country shipping zone listed for the country will be used.
TaxPolicy: Tax policy may be defined for a state. The tax policy details are discussed in the Tax section. If no tax policy is listed for the state, the tax policy listed for the country will be used.

Shipping.XML

Shipping is a complex process and considering the many variations that exist, it is difficult to define a standard. The following describes a methodology that covers majority of scenarios we have encountered.

<Zone>

<Company>FedEx</Company>

</Carrier>

</Carrier>

</Zone>

<Zone>

<Company>FedEx</Company>

</Carrier>

</Carrier>

</Zone>

</Shipping>

Using the above <Shipping> node, various zones may be defined and assigned to a country or state. Selection of a state or a country as shipping address sets the shipping charges per assigned zone. For a given zone, all carriers applicable to the zone may be defined with their respective fee structure

Carrier fee structure will be charged according to the following elements:

FlatRate: The fixed rate for a shipment. The fee is regardless of the quantity or package size. The FlatRate may be the starting or minimum shipping cost for the carrier.
DimensionalWeightMultiplier: To use the DimensionalWeightMultiplier all products need to have a DimensionalWeight value. It is best to define a node such as <DimensionalWeight> for each product. The dimensional weight is typically a value that represents the size and weight of a product. The DimensionalWeightMultiplier should be multiplied by the dimensional weight of the product as part of the total shipping cost. An example is shown below.
QuntityMultiplier: A fixed value that will be multiplied by the quantity of a given product.

Example:

The following 2 products are available in a shopping cart

Product 1: Diamond Ring

DimensionalWeight= 2

Quantity = 1

Product 2: Brick

DimensionalWeight = 10

Quantity = 3

The following carriers are available:

Carrier 1: FedEx

Flat Rate = 10
DimensionalWeightMultiplier = 20
QuantityMultiplier = 5

Carrier 1: Postal Service Ground

Flat Rate = 2
DimensionalWeightMultiplier = 5
QuantityMultiplier = 2

Based on the above:

Shipping cost for carrier 1 (FedEx)

Total = 10 + [(2 x 20) + (1 x 5)] + { [3 x (10 x 20)] + (3x5) }
Total = 10 + 40 + 5 + 600 + 15

Total = 670

Shipping cost for carrier 1 (Post Service- Ground)

Total = 2 + [(2 x 5) + (1 x 2)] + { [3 x (10 x 5)] + (3x2) }
Total = 2 + 10 + 2 + 45 + 6
Total = 65

The primary objective of the above formulation is to provide enough variables for calculating shipping cost of objects of various value and size while allowing package pricing of various quantities.

Tax.XML

Tax is another complex subject in Internet commerce. In most cases tax rates are locality based. Using a tax policy approach allowing for various items to be categorically defined provides a flexible approach towards calculating taxes.

The following is a sample tax policy definition:

<Tax>

<TaxCategory>Shipping</TaxCategory>

</Category>

<TaxCategory>Clothing</TaxCategory>

</Category>

<TaxCategory>Luxury Item</TaxCategory>

</Category>

</Policy>

<TaxCategory>Clothing</TaxCategory>

</Category>

</Policy>

</Tax>

Policies may be assigned to a State / Province or Country. Each policy has a default rate which will be used if a product category is not defined. Tax categories are defined for each product and matched against the rate in the Policy.

For example:

A shopping basket contains the following items:
Product 1: Diamond Ring
<TaxCategory>Luxury Item</TaxCateogry>
Product 2: Brick
<TaxCategory>Construction </TaxCateogry>
The product will be shipped to:
<State Name="Virginia" Abbrev="VA" visible="true">
<TaxPolicy>1</TaxPolicy>
</State>
The following taxes will be added for each product:
Product 1: Diamond Ring
Tax = 9%
Product 1: Brick
Tax = 3% [default rate since construction is not a defined category in Tax Policy 1]

RSS of this page