Integration Guide

Integration steps to follow:

  1. Register the orderpage location
  2. Building your order page
    1. required variables
    2. more variables
    3. recurring billings
    4. customer/cardholder details
    5. example code
    6. order processing API
    7. Rebill update API
    8. Refund API
  3. Orderpage ID configuration
    1. Sending customers back to your server
    2. silent post
    3. multiple languages
    4. multiple currencies
    5. pincodes, username/passwords
  4. Instant Payment Notifications
    1. difference between silent post and IPN
  5. Configure Password Links
  6. Run a test order
  7. Contact our technical helpdesk

Step 1: Register the orderpage location

Hosting of your orderpage

Hosting on the MultiCards secure 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 and follow the instructions.

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.

Orderpage location registration

For security reasons all order pages must be registered in the Merchant Menu. Login to your account and click on the ‘orderpages’ button to list all allowed orderpage locations.

Adding new orderpages
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.

Change orderpage location for existing page id
Send a support ticket with the page id number to update and the new orderpage location. The new orderpage will be reviewed by our risk department and updated within 24 hours during business days.
 

 

Step 2: Building your order page

Once the location of your order page is configured in the merchant menu, you have to create the HTML code with required form variables. Contact our technical department via a support ticket for FREE assistance!

Shopping cart systems

A shopping cart system normally is used for order systems with more than 25 products.

Supported shopping carts

Create a web form

Our technicians can help!
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.

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

<form action=https://secure.multicards.com/cgi-bin/order2/processorder1.pl method="post">

Required form 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.
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.

More variables (optional)

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.

Recurring billings (optional)

The optional 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. The variables for rebilling are:

Variable Value explained
rebill_type

[frequency]-[amount]-[days]

Where Frequency is:

  • monthly
  • quarterly
  • sixmonthly
  • yearly

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".

Rebilling example

Here is an example for a monthly rebilling for US$ 19.99 started after 14 days, with an initial charge of US$ 9.99:

<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="14 days trial" type="hidden">
<input name="item1_price" value="9.99" type="hidden">
<input name="item1_qty" type="hidden" value="1">

<input type="hidden" name="rebill_type" value="monthly-19.99-14">

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

Customer/cardholder details (optional)

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. See an example.

Skip the first two MultiCards screens
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 only possible to post the credit card details with the API.

Customer/cardholder variables:

Variable Value
next_phase Use value "paydata" to go directly to the credit card fields page
cust_country The country name in ISO format
pay_method_type Use one of the following values: creditcard_visa, creditcard_mastercard, creditcard_eurocard, creditcard_americanexpress, creditcard_discover, creditcard_dinersclub, creditcard_carteblanche, creditcard_jcb, bank_directdebit, bank_ideal
cust_name The customer name
cust_company The company name
info1 Delivery/Mail/Business Address
cust_phone Customer phone number
cust_fax Customer fax number
cust_email Customer e-mail address
cust_address1 Cardholder address
cust_zip Cardholder zipcode
cust_city Cardholder city
cust_state Cardholder state

Example html code

You can download example html code containing all the above variables to use in your order page.

Order processing API (optional)

Another option to post the order details is using our order processing API. This option is only available for:

  • PCI DSS compliant merchants
  • Merchants with a direct merchant account with our acquiring bank

Contact our Accounts Department for a complete overview of all requirements for this option and availability for your account.

Extra variables for order processing API
The API uses exactly the same variables as our normal processing interface, but including:

  • card_num
  • card_name
  • card_code 
  • card_exp (mm/yy)

The location of the API processing script will be provided once your account has been approved.

API response codes:

Variable name: Value:
response_code 1 = accepted
2 = declined
3 = error
response_text descriptive text of response code, i.e. InputError, Declined, Accepted.
error In case of an error response, error contains one or more reasons why the post data was rejected.
order_num In case of an accepted response, the MultiCards order number is returned.
billing_name Very important: The name that will appear on the customers credit card statements.

Rebill update API (optional)

To stop, restart, or change the amount for existing rebilling transactions via the MultiCards Gateway, the following parameters should be posted to the secure script under SSL.

The location of the API rebill script will be provided once this feature has been activated for your account.

Input parameters:

Name
Type
Example Value
Notes
MerchantID
TEXT
070167
Your 6 digit merchant number
password
TEXT
huj%t678
As directed by MultiCards.
action
TEXT
rebill.stop, rebill.start, rebill.changeamount
rebill.ondemand
Stop existing rebilling, restart existing inactive rebilling, change amount to be rebilled in next period for specified order number. Ondemand processes the rebilling immediately (max once per month).
ordernumber
TEXT
070167.3234567
MultiCards order number.
amount
TEXT
10.05
New rebill amount (only for action rebill.changeamount).

Response parameters:

Name
Type
Example Value
Notes
response_code
TEXT
000, 001, 002, 003, 004, 100, 101, 300, 301, or 302
000 = success,
001 = unknown or invalid MerchantID,
002 = password incorrect,
003 = service has not been enabled for this merchant,
004 = action parameter incorrect,
005 = this IP is not in the allowed list (IP=$remote),
100= Invalid or unknown order number,
101= No rebilling was found for this order number,
300 = rebilling already stopped,
301 = rebilling already started,
302 = invalid amount passed (only for action rebill.changeamount).
600 = error – contact support.
response_text
TEXT
Success, Unknown or invalid MerchantID, …
Descriptive text for the response code. Will repeat for each response as necessary.

Refund API

To issue a refund for an existing transaction via the MultiCards Gateway, the following parameters should be posted to the secure script under SSL.

Secure Script Location: https://secure.multicards.com/cgi-bin/auto/crauto.cgi

Refund Transaction API input parameters:

Name
Type
Example Value
Notes
merchantid
TEXT
070167
Your 6 digit merchant number.
password
TEXT
huj%t678
As directed by MultiCards.
action
TEXT
credit, partial.credit
Full credit, or partial credit.
reason
TEXT
Customer requested refund, Duplicate transaction placed in error, …
Descriptive text of reason for refund.
trans_id
TEXT
745677789
As output previously by the debit transaction script.
amount
TEXT
10.05
Only for action = partial.credit. Cannot exceed original debit amount.

 Refund Transaction API response parameters:

Name
Type
Example Value
Notes
response_code
TEXT
000, 001, 002, 003, 004, 100, 300, 301, or 302
000 = success, 001 = unknown or invalid MerchantID, 002 = password incorrect, 003 = service has not been enabled for this merchant, 004 = action parameter incorrect, 100= Invalid or unknown transaction id, 300 = transaction already refunded, 301 = transaction refund pending, 302 = invalid amount passed (only for action partial.credit).
response_text
TEXT
Success, Unknown or invalid MerchantID, …
Descriptive text for the response code. Will repeat for each response as necessary.

 

 

Step 3: Orderpage ID configuration in Merchant Menu

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.
Successful transaction return location (PostURL) The location where we can redirect the customer to after a successful transaction.
Post fields List the variables we must post to the script defined in the "Continue page location".

For example:
order_num,total_amount,item1_qty,cust_name
Continue button Label Change the label of the thank you page button. The default label is: "proceed to ".
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.

Sending the customer back to your server

After a successful transaction the customer will be redirected back to the "Successful transaction return location (PostURL)" defined in the Page ID settings.

It is possible to add transaction variables to that URL. The field 'Postfields' can be used to post the allowed and accepted order page variables posted by the orderpage and also special processing variables such as: total_amount and order_num.

How do Postfields work?
The Successful transaction return location (PostURL) and post fields you defined in your page id settings are added to the order receipt page (the last page in the order process) in the following web form format:

 <form action="continue page location" method="post">
<input name="postfield1" value="field1 value" type="hidden">
<input name="postfield2" value="field2 value" type="hidden">
<input name="postfield3" value="field3 value" type="hidden">
.....
<input name="submit" type="submit" value="Continue button label">
</form>

Activate 'Silent Post'

What is silent post?
When silent post is enabled, the form is automatically submitted in the background by our server. The post result is included where normally the above form is located. The silent post function is mostly used to retrieve a dynamic message or webform from your server, and include it in the MultiCards receipt page.

How does silent post work
To use 'Silent Post' you need to include <!--success--> in the response of your script. If this is not found in the response, our server assumes that the post was not successful and displays an error message to the customer together with a retry button.

Is silent post safe?
Because the post is done in the background by our server the PostURL is hidden for the customer. This allows you to add an IP check to your script and use the silent post function to start a secure process on your server.

Here is an example:

A company sells online tickets. They post their ticket ID in the user1 variable. The PostURL with Silent Post enabled is used to display the button to print the ticket in the receipt page.

Two scripts are involved:

The PostURL contains a link to script A. This script A receives user1 and order_num. Because silent post is used script A can have an IP check. Only posts from the MultiCards server are allowed. This ensures that only MultiCards marks an 'ID' (set in user1) to be paid. Script A needs to mark the ID as paid and adds the order number and a unique pincode.

Script A responds with the following (this will be included in the receipt page):

<!--success-->
<form action="http://yourdomain.com/location_of_script_B" autocomplete="off">
<input type=hidden name=ticketid value="value_of_user1">
<input type=hidden name=pincode value="pincode_created_by_script_A">
<input type=submit name=submit value="Print ticket">
</form>

Script B is called by the customer and receives the user1 and pincode values. This script checks if script A has marked the ID as paid and if the pincode is valid. If not, the customer is trying to commit fraud.

Use multiple languages

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 optional 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>

Use multiple currencies

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>

Pincodes & username/passwords

The MultiCards server can dynamically generate pincodes and use a by the merchant supplied list of pincodes and login details. In the orderpages section of the merchant menu click on Pincodes.

Pincode type How it works
Numeric (7 digits) You can upload a list if 7 digit pincodes. Per transaction a pincode will be removed from the list.
Username / Password Works like the Numeric 7 digit pincodes, but now can contain any value. For example:
username: xxxxxx password: yyyyyy
Repeatable password This password is not deleted after use, hence is used by all customers.
Auto generated repeatable password Use the notation {D7}-{A1} to auto generate patterns, D=digit, A=letter

The pincode value can be used as a post field to be posted to the continue page location (see above).

Pre-authorization

This function is under construction. Contact our technicians for more information.

 

Step 4: Instant Payment Notifications (optional)

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 (IPN)'. The field 'ExtraFields' can be used to post the allowed and accepted order page variables posted by the orderpage and also special processing variables such as: total_amount and fraudscore.

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

Field:

Description:

password The password field can be used to secure the post and make sure it is being posted from the MultiCards server. A second security layer can be an IP filter.

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
  • rebilldeactivated
  • 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,,item1_qty.

Because the transaction is completed you can also use total_amount and total_amount_us as postfields.

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.

Difference between silent post and Instant Payment Notifications

Silent post:

Server notifications:

Post triggered by the customer's web browser on 'accepted order confirmation screen': manually by customer, or automatically with 'silent post'

Post triggered automatically by our server after 3 minutes

Only accepted orders

Accepted orders, declined orders, refunds, chargebacks, etc...

Visible to customer during order process

Done by our server in the background

Mostly used to display information to the customer

Mostly used to update a database

It is possible to use both systems at the same time.

 

Step 5: Configure Password Links (optional) 

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 6: 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 7: Contact our technical helpdesk

Finally, contact our technicians for an order page check.