Purchase?db=xx.db&cart=123&options=xx

Submits a shopping cart for final order processing.

To purchase a shopping cart full of items, send WebCatalog a Purchase command. WebCatalog verifies the checksum of the credit card (if paying by credit card), sets any quantities, taxRates, or other order file header variables, and moves the order file from the Shopping Cart folder to the Orders folder. The template displayed is usually a "Thank You" template which can contain [Email] contexts which send order verification and fulfillment requests to people in your company. The "Thank You" template can also contain any header variables from the cart, as well as a [LineItems] context so you can display final grand totals and oher verification of the items purchased.

WebCatalog does not perform any credit card validation or fulfillment of the order: you may upgrade to WebMerchant for these features. WebCatalog performs a simple check of the credit card number to see if it is a reasonable number, but it does not "call the bank" to verify funds.

Example (normally you would put the following text into a .tpl file on your server and use a web browser to link to it):

http://www.yourserver.com/GeneralStore/ThankYou.tpl?command=Purchase&db=xx.db&cart=123

Try It!

New for 3.0: normally all database filepaths are relative to the local template, or if they begin with "/" they are relative to the web server's virtual host root. As of version 3.0, you may optionally put "^" in front of the filepath to indicate that the file can be found in a global root folder called "Globals" inside the WebCatalog folder. This global root folder is the same regardless of the virtual host.

You may set any of the following variables during a Purchase command by putting named form variables into the purchase form. Some are optional, and any you do not explicitly set will remain unchanged from their previous values obtained from Add or ShowCart commands.
 Parameter  Description

template

(Required) The template that will display the "Thank You" page after the purchase command completes. If you are using suffix mapping, then the template is simply the URL of the "Thank You" page.

db

(Required) Product Database use for looking up product [xxx] fields inside the [LineItems] loop

cart

(Required) Name of the shopping cart file that is to be purchased

PayMethod

(Required) Payment method chosen by customer. May be one of:

CC - Credit Card (WebCatalog performs a checksum to make sure the number is reasonable)
AC - ACcount number (purchase order) (WebCatalog performs no validation, but WebMerchant AccountAuthorizer later does custom authorization)
BK - Book this order (verify funds, but do not deposit money). Handled by WebMerchant
SH - Ship this order (only from a previous BK order. Deposits money that was verified earlier). Handled by WebMerchant

AccountNum

(Required) Account number for payment. May be credit card number, purchase order, or First Virtual account

ExpMonth

(Required for credit cards) Month the credit card expires (between 1 and 12)

ExpYear

(Required for credit cards) Year the credit card expires

Optional Parameters

Description

card

(optional) If you only accept certain types of credit card, then set this to a list of card names you accept. For example:

VISA+MC will accept VISA and MasterCard, but no others

You may choose from VISA, MC, AMEX, DISC, JCB, CB, DINER, ALL, IGNORE

ALL - means accept all cards listed above (if checksum is correct)
IGNORE - means accept any number, regardless of checksum

Email

Bill-To: Email address the customer entered into the invoice page. Limited to 99 characters

Name

Bill-To: Customer's name. Limited to 99 characters

Company

Bill-To: Customer's company. Limited to 99 characters

Address1

Bill-To: First address line entered by customer for shipment. Limited to 99 characters

Address2

Bill-To: Second address line entered by customer for shipment. Limited to 99 characters

City

Bill-To: Customer's city. Limited to 49 characters

State

Bill-To: Customer's state. Limited to 49 characters

Zip

Bill-To: Customer's zip code. Limited to 19 characters

Country

Bill-To: Customer's country. Limited to 49 characters

Phone

Bill-To: Customer's phone number. Limited to 24 characters

ShipToEmail

Ship-To: Email address the customer entered into the invoice page. Limited to 99 characters

ShipToName

Ship-To: Customer's name. Limited to 99 characters

ShipToCompany

Ship-To: Customer's company. Limited to 99 characters

ShipToAddress1

Ship-To: First address line entered by customer for shipment. Limited to 99 characters

ShipToAddress2

Ship-To: Second address line entered by customer for shipment. Limited to 99 characters

ShipToCity

Ship-To: Customer's city. Limited to 49 characters

ShipToZip

Ship-To: Customer's zip code. Limited to 19 characters

ShipToState

Ship-To: Customer's state. Limited to 19 characters

ShipToCountry

ShipTo: Customer's country. Limited to 49 characters

ShipToPhone

Ship-To: Customer's phone number. Limited to 24 characters

TaxRate

Percentage tax rate for this order, such as 7.75

ShipVia

Method of delivery. May be one of:
  • EMAIL - Electronic delivery via email attachments (requires WebCommerce Solution's WebMerchant software to create Web Delivery pages)
  • WEB - Electronic delivery via automatically-built web pages (requires WebCommerce Solution's WebMerchant software to create Web Delivery pages)
  • FEDEX - Any other text can be entered here. Has no special meaning, but can be passed through to fulfillment emails. Maximum of 63 characters.

header1

Any extra information you want to keep in the order file, up to 255 characters

header2 - header40

Same as header1

nonTaxableTotal

Normally this value is computed automatically, but if you explicitly set its value, you can 'override' the precomputed value with any new number you like. WebMerchant will display this value if it is explicitly set, otherwise it will compute it from the numbers provided in the order file.

taxableTotal

similar to nonTaxableTotal

taxTotal

similar to nonTaxableTotal

shippingTotal

similar to nonTaxableTotal

subTotal

Calculated: based on taxableTotal + nonTaxableTotal. This cannot be overridden directly; if you want to override the subTotal of an order, you must override both taxableTotal and nonTaxableTotal to force the calculation of subTotal to become a new value.

CartIPAddress

This is not pre-set automatically, but you can set it to [ipAddress] if you want to remember the ip address of the visitor who last used the cart. Limited to 15 characters

CartUsername

You can store the username of the person who last used this cart here. It is not set automatically. Limited to 63 characters

CartPassword

You can store the password of the person who last used this cart here. It is not set automatically. Limited to 63 characters

Precision

International support: number of digits after the decimal that are considered important for tax, subtotal, grandtotal calculations. In the U.S., 2 digits is the normal precision. For Japan, 0 would cause all calculations to round off at integer values. You can change this on a cart-by-cart basis with [SetHeader]

TaxableShipping

If set to T, causes shipping to be taxed. The tax and grand total are increased by [taxRate]*[shippingTotal]. Default value is F

AuthNumber

WebMerchant Only: Text authorization ticket# returned from bank network. This field is filled in by WebMerchant after calling the bank. Limited to 63 characters

ResponseText

WebMerchant Only: Response text returned from bank network. This field is filled in by WebMerchant after calling the bank. Limited to 149 characters

Status

WebMerchant Only: status of order, such as Approved/Hold/Call/Pending. This field is filled in by WebMerchant after calling the bank. Limited to 63 characters

BatchNumber

WebMerchant Only: Batch# that PCAuthorize/MacAuthorize has stored this order in. This field is filled in by WebMerchant after calling the bank. Limited to 63 characters

ReferenceNumber

WebMerchant Only: Reference# that PCAuthorize/MacAuthorize created for this order. This field is filled in by WebMerchant after calling the bank. Limited to 63 characters

SequenceNumber

WebMerchant Only: Sequence# that PCAuthorize/MacAuthorize created for this order. This field is filled in by WebMerchant after calling the bank. Limited to 63 characters

ItemNumber

WebMerchant Only: Item# (within the batch) that PCAuthorize/MacAuthorize created for this order. This field is filled in by WebMerchant after calling the bank. Limited to 63 characters

RequiredFields

You may force the visitor to enter something into a field by using the RequiredFields parameter in the URL. Setting RequiredFields=field1+field2+field3 will display an error message if the visitor forgets to enter some text into any of those 3 fields. RequiredFields works for all commands, not just this one.

Line Item Variables

Description

quantity[lineIndex]

You may optionally set the quantity (to be purchased) of any line item. For example: quantity1=12 sets the first line item's quantity to 12. Similarly, quantity5=3 sets the fifth line item's quantity to 3 (these quantities can also be set with a Add or ShowCart command)

textA[lineIndex]

Any extra text you wish to associate with this line item. Sometimes used to store size, color, or pass catalog fields through to the shopping cart (can also be set with Add or ShowCart command). Limited to 255 characters.

textB[lineIndex]

Similar to textA

textC[lineIndex]

Similar to textA

textD[lineIndex]

Similar to textA

textE[lineIndex]

Similar to textA

taxable[lineIndex]

You are not allowed to set this value. It comes from the product database field "taxable", or from the taxable formula in Formulas.db

canEmail[lineIndex]

Similar to taxable

unitShipCost[lineIndex]

To prevent "hacking" this value cannot be set remotely -- its value either comes from the product database field "unitShipCost", or is computed from a formula stored in Formulas.db

price[lineIndex]

Similar to unitShipCost