VCS Basket Interfacing Specification

Last modified March 2007

Contact Details: Phone: 011 257 6222 E-mail: [email protected]

Table of Content

Introduction ......................................................................................................2 “Add to Basket” button .....................................................................................2 Example HTML code for each 'Add to Basket' button ..................................2 “Add to Basket” button parameter table........................................................3 Example Basket buttons...............................................................................4 “View Basket” link ............................................................................................5 “Continue Shopping” link..................................................................................5 Authorisation response ....................................................................................5 Option 1........................................................................................................5 Option 2........................................................................................................5 Merchant Settings ............................................................................................9 Test..................................................................................................................9 Activation .........................................................................................................9

VCS Basket Interfacing Specification

Introduction The purpose of this document is to provide the web developer with a sample layout of how to interface with the VCS Basket. The VCS Basket is a secure generic service that provides: ‰ Shopping capabilities. ‰ VCS credit card payment facility. ‰ Delivery address input fields. ‰ Optional - VCS response pages. ‰ Payment confirmations.

“Add to Basket” button To utilise the VCS generic Basket the Merchant has to create a page that contains a listing of his products and place a “Buy” or “Add to Basket” button next to each product.

Example HTML code for each 'Add to Basket' button

2

VCS Basket Interfacing Specification

“Add to Basket” button parameter table Parameter

Max

Type

Mandatory

uid

10

Alphanumeric

Y

pc

10

Alphanumeric

Y

pd

30

Alphanumeric

Y

up

6 for rand 2 for cent

Numeric

Y

c

3

Alpha

Y

u

255

Alphanumeric

Y

Comment

VCS Terminal ID allocated by VCS. Product Code. Product Description. Unit Price, Value and VAT inclusive. Do not insert commas, use a decimal point. If you do not include the decimal point we will assume one at the end of the amount, i.e. 10 is 10.00. Currency, ZAR is the only valid currency. The URL of the page where visitors should be returned to when exiting from their shopping basket. VAT Percentage.

v

2

Numeric

Y

14

1) If you are registered for VAT then submit your VAT number to VCS. 2) If you include VAT in the price, then enter the VAT percentage here to be displayed on the invoice.

0

Not registered for VAT. Note: If you do not use the optional parameters then exclude the name/value pairs completely.

ud

6 for rand 2 for cent

Numeric

N

Unit Delivery Charge. Note: Fixed Delivery Fee option available. Refer Merchant Settings. i.e. If included: 10.00 Item price = up + ud SA Delivery Only. All countries will be displayed in the “Country” dropdown of the delivery details input page, if this parameter is omitted or the value = "N"

N sa_only

1

Alpha

N

ONLY 'South Africa' will be displayed in the “Country” Y dropdown of the delivery details input page if this parameter’s value = "Y" Note: None of the parameters may contain an ampersand or an equal sign.

3

VCS Basket Interfacing Specification

Example Basket buttons Sample Merchant Page

All Prices are VAT inclusive Product1: R110.99 (R100.99 + R10.00 delivery)... Product2: R220.99 (R200.99 + R20.00 delivery)... Product3: R330.99 (R300.99 + R30.00 delivery)...

View Shopping Basket

4

VCS Basket Interfacing Specification

“View Basket” link Create a hyperlink for visitors to view their shopping Basket. Example HTML code: View Shopping Basket “View Shopping Basket” hyperlink parameter table Parameter uid u

Comments VCS Terminal ID The URL of the page that visitors should be returned to when exiting from their shopping Basket.

“Continue Shopping” link Parameters returned in “Continue Shopping” link. Parameter Name

Comments

BasketItems

Count of Items in the Basket

BasketSubTotal

Basket Sub Total - Rand Value

BasketVat

Basket Vat – Rand Value

BasketTotal

Basket Total – Rand Value

Authorisation response The authorisation results can be displayed in the following ways:

Option 1

Utilise the VCS default Shopping Basket Response pages. VCS will display the authorisation response to the cardholder in the Basket environment and send out a Payment Confirmation via e-mail to the cardholder and to the Merchant. Option 2 If additional interaction with the Merchant’s website is required after the credit card transaction has been authorised then create two additional web pages: A page to receive the Approved responses from the VCS Shopping Basket environment and a page to receive the Declined responses.

5

VCS Basket Interfacing Specification

Option 2 - Response parameters Parameter

Max

Type

uid

4

Alphanumeric

VCS Terminal ID.

reference

25

Alphanumeric

The unique transaction Reference Number generated by the Shopping Basket.

response

30

Alphanumeric

The Response returned by the bank.

name

50

amount

Comments

Characters 1 - 6

APPROVED Transaction: Contains the Approval Number.

Characters 7 - 16

APPROVED Transaction: Contains the constant APPROVED. Left justified right space filled.

Characters 1 - 16

DECLINED Transaction: Contains the reason for decline.

Alphanumeric

The Name entered on the Delivery Info page or if Basket Delivery setting is set to ‘No’ then the name entered by the Cardholder on the Authorisation page.

6 for rand 2 for cents

Numeric

The transaction Amount = the basket total.

email

255

Alphanumeric

Email Address entered as the Shopping Basket Login.

goods

255

Alphanumeric

Basket Line Items in the format: product code|product description|quantity Example: p001|product1|2|p002|product2|3 will be returned if basket contained 2 line items.

addr

30

Alphanumeric

Delivery address 1, street address. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

subr

30

Alphanumeric

Delivery address 2, suburb. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

city

30

Alphanumeric

Delivery address 3, city. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

prov

30

Alphanumeric

Delivery address 4, province. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

country

30

Alphanumeric

Delivery address 5, country. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

postal

10

Alphanumeric

Postal code. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

phone

20

Alphanumeric

Telephone number. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

fax

20

Alphanumeric

Fax number. This parameter will only be returned with a value if the Basket Delivery setting = “Yes”. Refer point 5.

6

VCS Basket Interfacing Specification

Option 2 - Example ASP code to receive the responses from the shopping Basket Credit Card Transaction APPROVED uid:
reference:
amount:
response:
name:
addr:
subr:
city:
prov:
country:
postal:
phone:
fax:
email:
goods:


View Shopping Basket 1 then varDisplay = varDisplay & " (" & qty & ")" end if Response.Write varDisplay & "
" cnt = 0 qty = 0 varHref = "" end select if PosPipe = len(varGoods) then PosPipe = 0 else varGoods = mid(varGoods,PosPipe + 1) PosPipe = instr(varGoods,"|") end if wend End Function %>

7

VCS Basket Interfacing Specification

Option 2 - Example ASP code for an Approved page with 'Download' hyperlinks View Shopping Basket

Credit Card Transaction APPROVED uid:
reference:
amount:
response:
name:
email: You can now download your on-line purchase: 1 then varHref = varHref & " (" & qty & " copies)" end if%> Download


8

VCS Basket Interfacing Specification

Merchant Settings How to modify the VCS Basket settings: ‰ ‰ ‰ ‰ ‰ ‰

Use an Internet browser to go to www.vcs.co.za. Click on Admin Login > Virtual Terminal. Enter the User Login Name and Password that was confirmed via the Virtual Vendor Application – Approved e-mail. Click on the Merchant Administration link. Click on the 3. VCS Interfacing (page1) link. After editing the Basket settings click the Modify button.

The following Basket settings can be modified to suit the Merchant’s requirements: 1) Enter the Merchant’s Approved and Declined page URLs, in the appropriate URL fields provided, if the Merchant requires additional interaction with his website after the credit card transaction has been authorised. If the Merchant is using the VCS default Shopping Basket Response pages then VCS will enter the URLs. 2) Modify the Basket Delivery option to “No” if the Merchant does not require delivery information, e.g. Merchant has download links on his web site. 3) A fixed Delivery Fee option is available. This Delivery Fee will be added to each basket. 4) Select a basket Button Colour from the selection available. Forward the Merchant’s company logo (maximum banner size 150 x 750 pixels) in .gif or .jpg format to [email protected]. This logo will be displayed to the shopper in the Basket environment and on the Payment Confirmation e-mail.

Test New Merchants loaded on the VCS system have access to the VCS Test platform. We run a response generator that has some fixed but mostly random responses. Card Number 4242424242424242 5454545454545454 5221001010000024 5221001010000032 5221001010000040

Fixed response ??????Approved where?????? = a numeric value ??????Approved Call Invalid Expiry ~No Active Connection to Acquirer exists

Any valid credit card number can be submitted to the test platform during the test phase because no real money is involved. The following responses occur randomly with any other card number used. "Invalid Terminal”, "Declined”, "Invalid Expiry”, "Batch Full”, "Call”, "??????Approved” Please ensure that sufficient testing has been completed before requesting activation as once a terminal has been activated it cannot be reset into Test status.

Activation To enable “live” operation send an activation request by e-mail to [email protected].

9