Merchant Integration Guide

Step 1: Define orderpage locations in the Merchant Menu

For security reasons all order pages must be defined in the Merchant Menu. Login to your account and click on the ‘orderpages’ button to list all allowed orderpage locations. Use the Request new Page ID button to create a new orderpage id ($25 one time charge). Only the MultiCards accounts department can change the location of an existing order page id at your request.


The order pages section of the Merchant Menu

Step 2: Orderpage hosting

Order pages can be hosted on the MultiCards secure server or on your own server. New accounts are delivered with one order page hosted on the MultiCards secure server. This can be changed to an order page or shopping cart on your own server. Send a support ticket with the new Orderpage location.

Hosting on the MultiCards server

Your account includes a free web space on our secure server. This space can be used to store your order pages and required graphics. Click on edit orderpages in the orderpages section of the Merchant Menu. The following screen appears:


Edit orderpages hosted on the MultiCards server

Use the Modify button to start the online What You See Is What You Get (WYSIWYG) editor:


The online editor in WYSIWYG mode

Click on the Code button in the toolbar to toggle between WYSIWYG and text HTML editing mode:


The online editor in text HTML mode

When you are ready please click on the update and return button to save your work. You return back to the orderpages list. Two new buttons are added:

  • send for review
  • cancel and trash:


Send your modified orderpage to MultiCards

Before the page is published an approval is required from our review department. Click on the Send for review button to submit your work together with comments for the MultiCards technicians.


Provide comments or instructions for the MultiCards technicians

Our review department will approve and publish the orderpage update, or send it back to your merchant menu together with new comments. You will be notified via e-mail once the status changes.

No HTML knowledge required with layout templates

Layout Templates allow non-technical merchants to create orderpages without any knowledge of html coding. Ask the MultiCards technical helpdesk to enable a template for your order page. That will add the following elements to the modify orderpage screen:


Add products to an orderpage


Add orderpage details

File explorer

It is also possible to access the files in your web space directly from a file explorer interface. Click on the following icon in the Edit Orderpages section of the merchant menu:

This loads the file explorer with possibilities to upload additional files such as style sheets, javascript files, images and flash files:


The file explorer

Hosting on your own server

Of course it is also possible to host the order page on your own server. A secure server is not required since the order page does not contain any credit card entry fields.

You should contact our accounts department via a support ticket in your merchant menu and ask them to change the OrderPageURL for any of your existing page id records. Or you can request a new page id.

Our technical helpdesk can only assist with updating the orderpage html code when you provide them FTP access to your server. Please note that for some business models MultiCards only allows the orderpage to be hosted on the MultiCards server.

Step 3: The HTML code

An orderpage contains a web form with the allowed and accepted MultiCards variables. The variables must be posted to our secure server script at:

<FORM METHOD=POST ACTION=“https://secure.multicards.com/cgi-bin/order2/processorder1.pl”>

Required variables:

name= type= value=
mer_id hidden Your 6 digit merchant number.
mer_url_idx hidden Refers to the page ID (page properties) in the MultiCards database. Every order page should have it's own idx number. You can create new page ID's in the Merchant Menu.

Optional variables:

name= value=
user1
user2
etc...		 These fields allows you to post extra information. The user variables are the only allowed variables to include query input fields, any other variable name is not supported.
sales_tax_factor Tax, value=0.10 for 10% sales tax.
sales_tax_exclude Tax exclude, value=10 to exclude item10, or value=10,11 to exclude item 10 and 11 from taxation.
sales_discount_factor Discount, value=0.10 for 10% discount.
sales_discount_exclude Discount exclude, value=10 to exclude item10, or value=10,11 to exclude item 10 and 11 from discount.
sales_discount_amount Discount amount, value=19.99 to discount 19.99.

The product item variables:

To include your products in the correct format use these 3 different variables:

name= type= value=
item1_desc
item2_desc
etc...		 hidden Short description of product.
item1_price
item2_price
etc...		 hidden Price of product in format xxx.yy, ie. 23.80.
item1_qty
item2_qty
etc...		 text or
hidden		 Quantity of product in integer format ie. 4.

Here is an example:

<form action="https://secure.multicards.com/cgi-bin/order2/processorder1.pl" method="post">
<input name="mer_id" value="xxxxxx" type="hidden"> <!--your merchant number -->
<input name="mer_url_idx" value="1" type="hidden"> <!-- the page id number -->

<input name="item1_desc" value="Sample product 1" type="hidden">
<input name="item1_price" value="50.00" type="hidden">
<input name="item1_qty" type="text" size="3" maxlength="2">

<input name="item2_desc" value="Sample product 2" type="hidden">
<input name="item2_price" value="100.00" type="hidden">
<input name="item2_qty" type="text" size="3" maxlength="2">

<input name="submit" type="submit" value="Proceed to Secure Payment Server">
</form>

IMPORTANT: Please note that it is not allowed to have open form fields for the product description and the amount in your order page. All prices and descriptions must be fixed or retrieved from a database.

Monthly/Quarterly recurring billings

The recurring billing option is a customer friendly way to charge a customer's credit card with a monthly or quarterly interval. The customer has full customer access to the rebilling, with the order number and the password, to stop and/or make changes to the rebilling information, such as frequency, address, zip code and expiration date.

The MultiCards Merchant has access to individual orders to make changes to the frequency and or amounts charged. This is useful if your prices have increased. The rebilling module works with all foreign currencies. Merchants can access the rebill orders through the 'Rebillings' link in the Merchant Menu.

Rebill variables

Variable Value explained
rebill_type (required)

[frequency]-[amount]-[days]

Where Frequency is: monthly or quarterly

Where Amount is: rebill amount in format 0.00

Where Days is: Number of days to start first rebilling after initial transaction. When empty default value for monthly rebillings is 30 and for quarterly rebillings 90 days.
rebill_count Total number of rebillings. Default is unlimited.
rebill_password Password for customer to login to transaction. When empty
the password is generated automatically.
rebill_desc Product description in all rebilling transactions. When empty
the description is "rebilling for order xxxxxx.yyyyyyy".

Here is an example for a quarterly rebilling for US$ 19.99 started after 10 days and ended after 4 rebill counts:

<input type="hidden" name="rebill_type" value="monthly-19.99-10">
<input type="hidden" name="rebill_count" value="4">

Customer details

By default an order page only submits the product information to our Payment Gateway. The first MultiCards screen asks your customers to enter their country and card type. The second screen contains the contact information fields.

It is possible to populate the fields, simply by posting the variables directly from the order page. To skip both screens completely post all the required fields. The first screen your customers then see is the credit card details page. It is not possible to post the credit card details.

Download the html code.

Shopping cart systems

A shopping cart system normally is used for order systems with more than 25 products. MultiCards supports the following third party shopping cart systems:

  • 3DCart
  • CartIt Commerce System 8.0
  • CartKeeper Gold 1.5.4
  • Designs Online
  • Jshop Professional v3
  • King-Cart
  • OS Commerce
  • Shop Factory
  • ShopMaker
  • VirtualShop
  • X-Cart
  • InstanteStore
  • VirtueMart
  • Zen-cart

Is your shop not listed?

Contact us! Please always first contact the shop vendor to verify that the latest version still is compatible with MultiCards. Shop vendors frequently change their software and it is beyond our control if the shop is not 100% compatible.

Step 4: Orderpage ID configuration

In the orderpages section of the merchant menu click on the settings icon. Complete and verify all fields explained below:

Property Explanation
Name The name of your company. This name is included in the processing screens and e-mail confirmations.
Website location The location of your site. Only the accounts department can change this value. The Website location is included in the processing screens and e-mail confirmations.
Allowed order page location A Page ID can only be used by one allowed and approved orderpage location. This can be a static page (.html) or a dynamic page (.php ,.asp, etc...). Orders submitted from an incorrect configured orderpage location are blocked by the system and the merchant receives an e-mail notification.
Continue page location The location where we can redirect the customer to after a successful transaction.
Continue button Label Change the label of the thank you page button. The default label is: "proceed to <your company name>".
Continue Button Force Press When enabled, the customer receives a warning when the browser window is closed without using the continue button.
Order page e-mail address The e-mail address where we send an e-mail order confirmation to. This e-mail address is also provided to the customer for support.
Custom message This content is included in the online receipt page and e-mail order confirmation.
Receipt page code This code is placed in the HEAD section of the receipt page, and can be used for affiliate tracking code. The MultiCards accounts department can change the code for you.
Terms and Conditions Add your own Terms and Conditions to the order processing screens.
Refund Policy Add your own Refund policy to the order processing screens.
Delivery Policy Add your own Delivery policy to the order processing screens.
Use Email Validation Code When enabled the customer receives a code by e-mail. Without this code the customer can not place an order. This function is used to make sure that the customers e-mail address is valid.

........
........

language setting

The language for an order page is set in the langcode field of the Page ID properties. When multiple languages are required you can add this code to your order page:

<select name="langcode">
<option selected>English</option>
<option value="it">Italian</option>
<option value="es">Spanish</option>
<option value="nl">Dutch</option>
<option value="fr">French</option>
<option value="de">German</option>
<option value="ru">Russian</option>
</select>

currency setting

The default currency for an order page or shopping cart is set in the Page ID properties. It is possible to send the currency together with the other transaction details. Please note that this option needs to be enabled in the Page ID properties screen in the Merchant Menu. The variable name for the currency is: valuta_code.

An example:

<select name="valuta_code" >
<option value="EUR" selected>EUR</option>
<option value="AUD">AUD</option>
<option value="CAD">CAD</option>
<option value="CHF">CHF</option>
<option value="CYP">CYP</option>
<option value="DKK">DKK</option>
<option value="GBP">GBP</option>
<option value="HKD">HKD</option>
<option value="INR">INR</option>
<option value="ISK">ISK</option>
<option value="JPY">JPY</option>
<option value="NZD">NZD</option>
<option value="USD">USD</option>
</select>

Transaction success page

- pincode
- username/password

Pre-authorization

Step 5: Setup Instant Payment Notifications

Notifications are messages that can be sent to a script, which allows your server to be automatically notified when a new order is placed, or when the status of an order changes. To prevent unnecessary delays in the order system itself due to timeouts, the notifications are not sent in realtime, they are stored in our database and processed later. The delay should under normal circumstances not be more than 5 minutes.

Configuration

To use this feature, login to the merchant menu and click on 'Order Pages'. Then use the link 'server notifications'. The field 'ExtraFields' can be used to post the allowed and accepted order page variables (for example cust_phone, user1, total_amount, etc...).

Specification

A notification consists of a HTTP POST, containing the following fields:

Field:

Description:

order_num

Order number in 6.5 or 6.7 format

status

New order status, as follows:

  • accepted
  • creditrequested
  • credited
  • retrieval
  • chargeback
  • declined
  • redirected (to the customers bank to place the order)
  • suspended (a customer email copy bounced, and he/she has several days to correct this. If that doesn't happen the order is voided/credited, if it is corrected the order is accepted)
  • unknown (the order was batch processed (this might occur if the realtime system is unable to process the order), meaning that the status will be known after processing the batch (usually the next day). So once again, the status will be sent using a second notification containing declined/accepted)
  • voided
  • rebillactivated new
  • rebilldeactivated new
  • error

reason

Reason for status change (text, not strictly specified, for informative purposes only). Examples are:
New order created (with status of order, see B and C why this is necessary)
Order accepted (when an order was batch processed and accepted later)
Order rejected
Order voided
Order credited
Rebilling accepted
Rebilling failed

origin

Origin of order/change. Possible values are order, rebill or manual

trans_type

Transaction type. Possible values are debit, credit or other

pageid

PageID that generated the order/rebilling. This value corresponds to the ID of your order pages. By including this value, you can optionally use the same notification handler script on your server for all your order pages.

notifyid

Our internal unique id for this notification.

created

Date + time in YYYY-MM-DD HH:MM:SS format when notification was created

**

Variables used during the order process. For example: cust_email,cust_phone,total_amount_us,item1_qty. For a complete list of all variables used in an order page, click here. Because the transaction is completed you can also use total_amount and total_amount_us and order_num as postfields. MultiCards can configure the variables for you.

Response code
Your script should respond with a 200 OK HTTP Status code, letting our handler know that your script received the notification. Please do not post back a large amount of content.

Step 6: Configure Password Links

The MultiCards PWLink© is a real-time online access verification system linked to a rebilling and password management sytem and is used to manage subscription based membership sites.
This is a script that allows customers automatic access to a password protected area on your site after a realtime order is approved.

After approval of a realtime order, from the receipt page, a customer is asked to enter a username and password, which are then submitted to a script on your website. This script updates a password file, giving the customer instant access.

The latest version of this software is now able to automatically disable users after a rebill failure, or if the order is voided. We have added a password maintenance facility in your merchant menu. Through this facility you can manually deactivate/reactivate passwords, delete passwords (temporary disabled though), and create custom passwords, which are not linked to any order.

Configuration

Step 1. Download the password script here.
Step 2. Install the password script in a directory on your website with execute permissions.
Step 3. Test the script by entering the script url in your browser. You should see a login form.
Step 4. Enter the authentication code you chose or was issued to you by MultiCards. A menu should appear. If it does not, there are several possibilities, refer to errors below.

Operation

The script is activated from the receipt page, after an order was accepted.

In the receipt page a small form is included, which the customer can use to submit a username and password to your server

If something goes wrong, the action taken depends on what went wrong. If the customer entered a wrong username or a username that already existed, an error is shown to the customer stating what was wrong, giving the customer the chance to fix it. If something went wrong that can not be fixed by the customer, the customer sees "Configuration error" and an email is sent to the merchant containing details of the error.

When a password has successfully been submitted, both the merchant and the customer will receive a confirmation email.

Setup a password controlled directory

To use the MultiCards MC-Access Password link you need to have .htaccess installed on the directory that you want to protect. If you don't know how that works on your server, you need to contact your server administrator and ask him to install this in the directory you want to protect and add one administrative user. He also needs to tell you the server path to the directory where the password file is stored. Please note that if you place the script in the directory where the password file is and activate the script, a techinfo button appears that allows you to find the correct server path.

Error messages

The following table lists the most common errors messages you may encounter, with possible solutions.

Code Reason
602 Authentication failure
The authentication code you submitted was incorrect. Please check the authentication in the script itself against the authentication code set in the page definition on the MultiCards server.
650 Password file not found
The location you specified for the password is incorrect.
651 Password file not readable
The password file doesn't have proper access permissions. In order for the web browser to be able to read it, it must have sufficient read permissions. These can be set using the chmod command. If you don't know how this works, you should contact your system administrator.
652 Password file not writable
The password file doesn't have proper access permissions. In order for the web browser to be able to write it, it must have sufficient write permissions. These can be set using the chmod command. If you don't know how this works, you should contact your system administrator.
653 Password file can not be created
The password file didn't exist, so the script tried to create it, but that didn't work. Please make sure the directory where you want to keep the password file has proper permissions, or create a password file yourself.
650 Password file not found
660 Password file may not be stored in web directory
If you see this error, you tried to put the password file inside the web directory. This is very bad, because this may enable visitors of your website to retrieve the password file. If you specifically want to do this or you protected the directory the password file is in (for instance with a password), you can set the variable check_webdir in the script to 0. This check will then be disabled.

Step 7: Run a test order

In the merchant menu go to the desktop screen and click on "Test order page". Enable a test credit card code and follow the instructions to run a test order with a test credit card.

Step 8: Contact our technical helpdesk

Finally, contact our technicians for an order page check.

Need any help?

Contact our technical helpdesk for free assistance. You can reach them via telephone or support ticket in your merchant menu.