Purchase Command

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 WebDNA a Purchase command. WebDNA 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 to 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 other verification of the items purchased.

WebDNA performs credit card validation or fulfillment of the order if you are using the WebMerchant feature. WebDNA performs a simple check of the credit card number to see if it is a reasonable number, but it does not 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
: Note: Normally all database file paths are relative to the local template, or if they begin with "/," they are relative to the web server's virtual host root. You may optionally put "^" in front of the file path to indicate the file can be found in a global root folder called "Globals" inside the WebCatalogEngine 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 displaying 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 to be purchased.

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

CC - Credit Card (WebDNA performs a checksum to make sure the number is reasonable)
AC - ACcount number (purchase order) (WebDNA 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 displays this value if it is explicitly set, otherwise it computes 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 user name 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 causes 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 displays an error message if the visitor forgets to enter text into any of those 3 fields. RequiredFields works for all commands, not just this one.

New Optional Parameters
for WebDNA 5.1 Description

bankRoutingNumber
Typically required with e-Check transactions. Limited to 63 characters.

bankAccountNumber
Typically required with e-Check transactions. Limited to 63 characters.

bankAccountType
Typically required with e-Check transactions. Limited to 31 characters.

bankName
Typically required with e-Check transactions. Limited to 99 characters.

bankAccountName
Typically required with e-Check transactions. Limited to 99 characters.

CCID
More recently required by some merchants for Credit Card transactions. Limited to 15 characters.

currencyCode
Limited to 15 characters

recurringBillingCode
Can be used to designate a weekly, monthly, yearly, etc... billing cycle. Limited to 15 characters.

fax
'Bill To' fax number. Limited to 31 characters.

ShipTofax
'Ship To' fax number. Limited to 31 characters.

customerID
Limited to 31 characters

invouceNumber
Limited to 63 characters.

poNumber
Limited to 63 characters.

description
Limited to 255 characters.

customerType
Limited to 15 characters.

customerTaxID
Limited to 31 characters.

driversLicenseNumber
Limited to 31 characters.

driversLicenseState
Limited to 49 characters.

driversLicenseDOB
Limited to 15 characters.

lastName
'Bill To' last name. Limited to 99 characters.

ShipTolastname
'Ship To' last name. Limited to 99 characters.

Comment
Limited to 255 characters.

SameAsShipping
'T' or 'F'. 'T' if billing information is the same as the shipping information.

AVS
Used to store the 'Address Verification Code'. Limited to 31 characters.

MD5Hash
Used to store the Hash code returned by some Payment Processors. Limited to 127 characters.

taxExempt
'T' or 'F'. 'T' if order is exempt from taxing.

resellerNumber
Limited to 127 characters.

transactionIndex
Can be used to store the 'rank' in a related set of orders. Limited to 63 characters.

relatedTransaction
Can be used to store a 'related' order id. Limited to 63 characters.

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.

Parameter	Description
template	(Required) The template displaying 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 to be purchased.
PayMethod	(Required) Payment method chosen by customer. May be one of: CC - Credit Card (WebDNA performs a checksum to make sure the number is reasonable) AC - ACcount number (purchase order) (WebDNA 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 displays this value if it is explicitly set, otherwise it computes 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 user name 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 causes 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 displays an error message if the visitor forgets to enter text into any of those 3 fields. RequiredFields works for all commands, not just this one.
New Optional Parameters for WebDNA 5.1	Description
bankRoutingNumber	Typically required with e-Check transactions. Limited to 63 characters.
bankAccountNumber	Typically required with e-Check transactions. Limited to 63 characters.
bankAccountType	Typically required with e-Check transactions. Limited to 31 characters.
bankName	Typically required with e-Check transactions. Limited to 99 characters.
bankAccountName	Typically required with e-Check transactions. Limited to 99 characters.
CCID	More recently required by some merchants for Credit Card transactions. Limited to 15 characters.
currencyCode	Limited to 15 characters
recurringBillingCode	Can be used to designate a weekly, monthly, yearly, etc... billing cycle. Limited to 15 characters.
fax	'Bill To' fax number. Limited to 31 characters.
ShipTofax	'Ship To' fax number. Limited to 31 characters.
customerID	Limited to 31 characters
invouceNumber	Limited to 63 characters.
poNumber	Limited to 63 characters.
description	Limited to 255 characters.
customerType	Limited to 15 characters.
customerTaxID	Limited to 31 characters.
driversLicenseNumber	Limited to 31 characters.
driversLicenseState	Limited to 49 characters.
driversLicenseDOB	Limited to 15 characters.
lastName	'Bill To' last name. Limited to 99 characters.
ShipTolastname	'Ship To' last name. Limited to 99 characters.
Comment	Limited to 255 characters.
SameAsShipping	'T' or 'F'. 'T' if billing information is the same as the shipping information.
AVS	Used to store the 'Address Verification Code'. Limited to 31 characters.
MD5Hash	Used to store the Hash code returned by some Payment Processors. Limited to 127 characters.
taxExempt	'T' or 'F'. 'T' if order is exempt from taxing.
resellerNumber	Limited to 127 characters.
transactionIndex	Can be used to store the 'rank' in a related set of orders. Limited to 63 characters.
relatedTransaction	Can be used to store a 'related' order id. Limited to 63 characters.
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.