Payment System Configuration

Rapid Classified can be configured to accept fees for ad posting. A popular PayPal ,  Moneybookers and 2Checkout payment processors has been selected and pre-configured to accept user payments and automatically post amount paid to user accounts. Please carefully read instructions below to have a complete understanding on how the payment system works.

Please Note: The payment system will not function properly unless software is registered (license purchased) and payment notification pages downloaded.

There are 2 pay modes are available to select from. "Credits Mode" and "Package Mode". Once the board is switch into the Pay Mode (Admin Preferences), users either must purchase "Credits" before they can post ads or purchase a "Package". Two pay modes are independent. This mean you have to decide which mode is the most appropriate for your type of business. 

Credits are the absolute money equivalent units, which can represent any currency you have selected to accept. Board can be configured to accept only one type of currency at a time. Meaning if you selected British Pounds in PayPal configuration, then no other currency will be accepted by the board. One credit will be equal to 1 GBP in this case. If you selected US Dollars then 1 credit will be equal to 1 Dollar, etc... Utilizing PayPal IPN notification system application automatically post purchased amount of credits to user accounts. Those credits are available to be spent by user for posting ads right away.

Package is practically highly customizable clients membership. Once the package is purchased, clients can post ads according to the package specification: number of ads, number of attached images, ads duration until the package is expired. To continue ads posting after package expiration, client needs to extend the membership by purchasing another package and so on. Note: Packages cannot be combined or accumulated.

You would need to have at list a Business PayPal account to be able to accept credit cards. If you do not have PayPal account yet, go to http://www.PayPal.com
If you use Moneybookers, then you need to send a request to Moneybookers support and have your account promoted to merchant status http://www.moneybookers.com
For 2checkout open and account at: http://www.2checkout.com

If you have different payment processor on you site, or willing to get merchant account other than PayPal, Moneybookers or 2checkout, then you would need to make sure your merchant has a secure "post-back" notification system in place. Plus, scripts has to be written to integrate this system into Rapid Classified Board. The last chapter describe a procedures and methods for integration, which are rather simple if you have some experience with ASP. I may consult you further on the matter of integration techniques, but cannot provide a complete support i.e. writing new scripts for every other merchant notification system.

Note: Successful operation of the Rapid Classified Board in Pay Mode highly depends on 3-rd party payment processor providers (PayPal, Moneybookers, 2checkout). I cannot guaranty, that the mentioned merchants in the future would not change conditions, service methods, notification systems which might affect one way or another payment automations on the Board. I will try however to update application in an event of such changes which might affect the performance or features of the Rapid Classified Board.

To switch the board to Pay Mode:

1. Logon to Admin page.

2. Open "Admin Preferences"

3. Check "Collect fees for ad Posting"

4. Select Payment Mode

5. Save configuration.

Regardless of the payment mode you selected, the Payment processor configuration is done via Payment Processor and ads Durations page.

Credits Mode Configuration:

Start configuring a "default" price scheme. The scheme consists of 4 categories, which can be configured independently and 2 levels of credits. 

1. The most top category contain only one product which is a "Base Price for 10 days ad". This will be the list expensive product upon which the final price would be based given that user selected additional ad posting options. Write down in the box the base price. 
   Note: It is desirable, that you put down all prices with 2 decimals even for round numbers i.e. 2.35, 1.00, etc...
   You may enter 0.00 for the base price and have users to post the basic ad for free and then have them pay for additional options you configure below.
   Note: All additional category prices would automatically be added to the "Base Price for 10 days ad" which you just configured.
   
   

2. The next price category is additional fees for an "Extra Ad Duration". There are 4 products here. Additional fees for 20, 30, 45 and 60 days of ad duration. Configure the scheme at you will. Again you may leave 0.00 to have the appropriate option to be free. You may change the duration scheme by assigning appropriate number of days in the text field in place of default values. You can select 0 duration, to exclude current selection from the option list during ad post process. NOTE: If you exclude an option, make sure the following by options are excluded as well. In other words start excluding from the last option and up. Do not leave excluded option in between those you have assigned a valid duration. Do not leave duration field blank either.
   
   

3. Ad duration is followed by an "Image Attachment Price". There are 10 images can be attached to each ad. Accordingly you may charge for each additional image attached to the ad. Again variety of choices. Have first image attachment for free for instance and charge for each additional. It is completely up to you. To set the image field to be free, assign value of 00.00 to the corresponding field. If you specified a price 0.00 for any of the image option, this option will be omitted  from the selection while client is posting ads.
   
   

4. The last category in a price scheme is a single charge for ad participation in "What's Hot" list. This is featured ads list and regardless of category posted all ads participated can be instantly viewed by clicking on What's Hot link from the top navigation bar. The ads listed here have a bit more attractive appearance and have the icon, when viewed in regular category list.
   Note: What's Hot list is only available in Pay Mode, because in a free mode everyone would post their ads there.
   For the reason above you should definitely charge for this option.
   
   

5. To attract users you may give some credits for initial sign up. Enter the appropriate amount at "Give NEW users a credit for" box. Every new user will get this credit at sign up time and may use it to post some free ads depending on the credits level you gave them.
   
   

6. Occasionally you may wish to run a Discount campaign. Select a discount percentage at "Run Discount Campaign" drop-down box. The discount would be deducted from the final price for any new ad posting from that moment on.
   
   

7. Finally you need to enter the minimum amount which can be paid via merchant. I can speak for US $ here. PayPal charge 3% + 30 cents per transaction. Therefore if user pays you 50 cents you would actually get around 15 cents. And if theoretically someone is making 10 payments of 50 cents, they would get $5.00 on the account, but you will only get $1.50. The optimal minimum payment should be around $1.00 

The final price for the ad would now be calculated as following: Base Price for 10 days ad + Extra Ad Duration Charge + Image Attachment Price - Discount Campaign Percentage.

This concludes a "default" scheme configuration. The "default" scheme is linked to ALL categories by default. But what if you want to have a different price scheme/options for each category on your board? Well, you can create an unlimited number of pricing schemes and then link them to appropriate categories. The board comes with 3 preset pricing schemes (beside the default), which you can modify/delete as well as create new schemes. Click Custom Scheme at the top of the payment configuration page. You can select different schemes from the "Selected Payment Scheme" drop-down selector. Create/Configure as many schemes as you'd like at this page the same way you configured a "default" scheme.
Note: The default scheme cannot be deleted.

You can lock any category while configuring Custom Schemes. Only Moderator can post in locked category while it linked to that category.

Linking Schemes to Categories

Once finished with schemes configuration, you may start linking them to categories. Click the Link to Categories and begin linking schemes. Select appropriate category, scheme and click "Create Link". All lower level categories under the category you linked the scheme to, would automatically inherit this scheme.

Note: Schemes can be individually linked to any category at any level, but because of the inheritance you should start from the top category level and go down while linking. Example:

Category tree: Business>New Business>Marketing. You would like the "Business" (main category and all subcategories under it) to have the "Business" scheme linked to. But at the same time you would like the "Marketing" (3-rd level category) to be an exception and to retain the "default" scheme. First, link the "Business" scheme to "Business" category. And then link the "default" scheme to "Marketing".

Clients would get a "Business" scheme while posting to "Business" category and all it's subcategories... except "Marketing", for which clients would be presented a "default" scheme.

Package Mode Configuration:

Click on Packages link within Payment Processor and ads Durations page. There are few preset packages come with application. The first available package is "Trial Package"- membership. This free package would be assigned to all newly created user accounts if you choose to enable it. If you disable "Enable Free Trial" then no one can post ads unless one of the premium packages is purchased. There is only one "Trial Package" in the system and it cannot be deleted from the list. The rest of the packages selected from the "Drop-Down" list are premium packages for which you can assign different price. You can create an unlimited number of packages with different sets of features.

Description - Describe the package and it's features. The text you enter here would appear at the package selection page presented to clients. HTML Format is OK.

Product ID - This is 2checkout specific. See info about it within 2checkout configuration bellow. Disregard if using PayPal or Moneybookers as your merchant.

Package Duration: - Specify the duration of the package. The package would automatically expire when user first log on to the system after the package expiration date.

Ads Duration - Select ads duration for the package. There can only be one ads duration for the specific package.

Expire Ads as Package Expires: This would effectively override the Ads Duration when the package expired. Example: You set 30 days Ads duration and 60 days Package duration.
During first 30 days after the package was purchased all posted ad would have 30 days duration. But if a client posts/reposts the ad on 45-th day of membership, the ad duration would be set to 15 days, on 52-nd day - 8 days and so on. So that all client's ads would expire as soon as membership package expires. In this scenario if the client reposts the ad 8 days before the pack expiration but then decides to purchase another package, the ad would expire in 8 days but when client reposts it, the duration would automatically be extended to the full Ad Duration set for the package. If you uncheck this setting, then ads would stay online for the whole duration specified at the "Ads Duration" level even if package expires. This flexible configuration gives you plenty of room to manipulate and configure the most appropriate for your site scheme.

Allow to post no more than: This is a flat setting and overrides the ad limit set in "Admin Preferences". This setting counts ALL ads under the clients accounts (including expired). If clients reach the limit, they cannot post no more unless they delete some existed ads. If you configure this setting as 0, then client can post an unlimited number of ads.

Allow to post in "What's Hot" list: "What's Hot" is featured ads list and regardless of category posted all ads participated can be instantly viewed by clicking on What's Hot link from the top navigation bar. The ads listed here have a bit more attractive appearance and a special the icon when viewed in a regular category list. If you enable this feature for the package, clients who purchase this package would be prompted to choose this feature while posting an ad.

Max. Number of Images: Select how many images to allow as an attachment to the ad (10 max).

Allow to post in locked categories: Now, where the locked categories are and how do I set them? You can set locked categories and allow/disallow to post ads there for certain packages.  To lock a category you'd use a custom Pricing Scheme. The pricing schemes for the most part are irrelevant to "Package payment mode" and used in "Credits Mode". One setting however directly relevant to packages. That is "Lock Category". Navigate to Custom Scheme page, select any scheme other than "default", from a drop-down selector (if you do not have any custom schemes other than default, simply create it - type some name of the scheme and click "Create"). You do not really need to configure anything else here, other than to select "Yes" at the "Lock Category" setting and save the scheme. Now you can select any Top Category and link this scheme to it. Follow the procedure in "Linking Schemes to Categories" (just above in Credits Mode section) to create a link. Once link is create the category and ALL subcategories under it would become locked. The inheritance rule cannot be overridden in this case (if you link a different scheme to a subcategory which has the "Lock Category" set to "No", this subcategory would still be locked by the scheme inherited from a Main Category).
Now lets return to the package configuration. If you enable "Allow to post in locked categories", the package owner would be able to post in ALL categories. If you however uncheck this box and at the same time have locked some Main Categories by linking appropriate schemes, then the package owners will not be presented with locked categories in the categories list when they start posting ads. There will be no warning either. So you have to let your clients know in advance, that this package will not allow to post in certain categories. The best place to do it at, is package description.

Take Package Offline: This would effectively remove the package from the list of available sale packages. Offline is irrelevant for "Trial Package" because the trial package is controlled by "Enable Free Trial" setting.

Formatted Package Name: This is how the package name would actually appear to your clients. You may freely use HTML code and images (<img> tags) if necessary to highlight the package name.

Creating "Free Post" categories. All the way at the bottom of the page, there is a "Free Post" Categories configuration section. You can move any Main Category into the "Free Post" section. Why do you need this and how does it work? By default client cannot post ads at all without a package applied to the account. You can however use Free Post Categories to allow clients to post ads even if they did not purchase any packages and if the trial package has expired (that is if you have enabled a trial package). When clients, who do not have a package on the account (or it has expired) click on "Post Ads", they would be presented with a message asking to purchase one of the available packages. If you however assigned at list one category to the "Free Post" list, then the client can freely post ads to that category.
But what about the duration and the number of attached images to the ad? Where this information would come from if client does not have any packages on the account? Well, in this case, for the ad duration, the "pricing scheme" would automatically be applied to this "Free Post" Category and the max. number of images client can attach to the ad would be the same as you set in "Admin Preferences". Do not be confused by "pricing" term. Only ads durations part would be used from the scheme to render duration options and create a drop-down list for the client at the ads submission page. The interesting part of this case is, that you can create a different "pricing schemes" (see "Credits Mode"), then link those schemes to different categories, make those categories "Free Post" and have a different duration schemes for each of them.

Note: Again, the "Free Post" Categories are only valid for clients who did not purchase any packages. Once client purchased a package, ads duration and other attributes of the ad would follow the rules set within the purchased package. The "Free Post" categories duration would no longer be valid for this client. In addition,  the "Free Post" overrides "Locked Categories", but again only for clients without any packages.

We almost finished, there are 4 more links at the packages configuration page, which you need to know about.
When no clients logged to board, the link to acquire_display.asp is displayed at the navigation bar. This page displays all available packages information to your visitors. If client creates an account and logs on to the system, this link changes to acquire.asp. This page would display not only packages information but also renders a purchase buttons. The packages information at both pages is pulled directly from database. But at some point you might wish to display packages information at your main page - default.asp. Note: the package can only be purchased by registered clients, therefore you cannot display purchase buttons on your main page for every visitor. The best place to display general packages information (without purchase buttons) is a Main_Page_Center template. The template however cannot utilize any ASP code to pull packages data from database. For that reason 4 links were created at the  admin_paymentpack.asp page (Payment configuration page in Package Mode).

1. List Code Row - This link generates a page with an HTML code (from acquire_display.asp), which contains all packages information for your Main Template. This code includes a style box (same as portal boxes). The packages information is listed in a row. See the instruction within generated page for the code integration.

2. List Code Row Bare - This link generates the same page as 1. The only difference is, that the code generated in a bare format (without a style box).

3. List Code Column - Same as 1, only package information displayed in columns.

4. List Code Column Bare - Same as 3, only only in bare format (without a style box).

Note: It is important to understand, that the generated code is static. It will not be changed within the template when you changed packages configuration. If you modified any package, you would need to generate this code over and copy it to the template.

In addition you can modify the acquire_display.asp and acquire.asp pages to display package information in column/row and with or without a style box. Open each page in an editor and follow instructions at the top of the page.
 

Merchant Accounts Configuration

Navigate to the Payment Processor and ads Durations (in "Package Mode" additionally click the Default Scheme link at this page).

PayPal account settings. Click "Enable" to activate PayPal payments. There are 3 fields you would need to configure. Specify your PayPal account Email address (primary is desirable). Select the currency you would accept. And type the Item Name under which the transactions would take place. Note: For "Package Mode" the Item Name is irrelevant. Item Name would be equal to the purchased package name in this case.

Moneybookers account Settings. Click "Enable" to activate Moneybookers payments. Specify your Moneybookers email. Select currency and an Item Name under which the transactions would take place. Note: For "Package Mode" the Item Name is irrelevant. Item Name would be equal to the purchased package name in this case.
Important: The "Secret Word" must be specified for secure transactions. The Secret Word you enter and save here must match the one you entered on your Moneybookers profile.

2CheckOut account settings. Click "Enable" to activate 2Checkout payments. Specify your Seller ID and an Item Name under which the transactions would take place. Note: For "Package Mode" the Item Name is irrelevant. Item Name would be equal to the purchased package name in this case. The Secret Word must be specified for secure transactions. The secret word you enter and save here must match the one you entered on your 2CheckOut profile.
 

2checkout Account Configuration

• Open an account at 2CheckOut.com

• Logon to your 2CheckOut account.

• In "Helpful Links" section click "Settings" next to "Look & Feel"

• Set "Direct Return:" to "NO".

• Type your secret word in "Secret Word:" field. Secret word can be any string and have to match the word you set at Rapid Classified payment configuration.

• Click "Save Changes"

• Click "Home" link navigating to main configuration page.

• Click "Setup Products", then "New Products"
  
  I. Credits Mode Specific Configuration
  

• Create a New Product. In the "Price Field" type any price. This field is irrelevant. The actual price would be rendered from the for submitted form when client makes credits purchase. Give the product a name such as "Credits Purchase" or similar. Within "Approved URL" and "Pending URL" sections enter a return script location: http://www.your_domain.com/Rapid_Board_Location/2c_notify.asp. The "2c_notify.asp" script is the return script, which comes with Rapid Classified Package.

• Within the Products List page look for the "Ploduct ID" column for the newly created product. Write this ID down. Note: You must look for the "Ploduct ID" number and NOT the "Your Ploduct ID". Open 2c_payment.asp in any editor. Assign the noted Product ID number to product_id variables such as product_id = 1

• To test transactions you need to manually modify page 2c_payment.asp. Open this page in any editor and remove a ['] character at the front of the line: '.Write "<input type='hidden' name='demo' value='Y'>". All purchases initiated after that will be in a demo mode and no credit card will be charged. To switch back to live mode place the ['] back in front of the mentioned line in 2c_payment.asp.
  
  II. Package Mode Specific Configuration
  

• Create a new product for each package you created and enabled in packages configuration page.

• For each product set the price reflecting package configuration. Set the product name (the name of your package). Within "Approved URL" and "Pending URL" sections enter a return script location: http://www.your_domain.com/Rapid_Board_Location/pack2c_notify.asp. The "pack2c_notify.asp" script is the return script, which comes with Rapid Classified Package.

• After you created a product for each package go back to 2checkout products list page and write down a "Ploduct ID" for each package (not the "Your Ploduct ID"). Then open package configuration page (Payment Processor and ads Durations) and for EACH package set the "Product ID" to the corresponding number gathered from 2checkout products page.

The next chapter describes procedures for purchasing Credits with PayPal and notification system. The payment procedures using Moneybookers and 2CheckOut for the most part is the same as with PayPal.

While the board is in Pay Mode, clients directed to credits evaluation and payment page when click "Post Ad". This page dynamically builds payment options you have configured in "Payment System Configuration". When clients select options, the total price dynamically displayed at the bottom of the page and compared to the credits user have available at the moment. Access to the next page where clients start submission process is granted only if the total price is less or equal to the client's credit level. Depending on a selected category, the appropriate Price Scheme would be applied

The only way to get to the next page is through "Next >>" button. The button is unavailable until clients has sufficient credits for the type of ad they are trying to submit. Even if clients know the URL to the next page and try to navigate manually, they would be directed right back to the payment page. There is a short instruction for the client and PayPal purchase button at the very top of the page, where they can initiate credits purchase. While clients select options and given that they do not have sufficient credit level, the difference between total price and available credits automatically pasted into the purchase amount box so they can buy enough credits. 

The amount displayed in the box is always equal or higher than the minimum purchase level you have selected in "Payment System Configuration". If for instance you have selected the minimum level at $1.00 and difference between total price and available credits is $0.45, then $1.00 would be displayed in the box. Moreover client would get error prompt if try to purchase credits for the amount of less than $1.00.

Purchasing Credits procedure is described in the next chapter. For now assume that clients have sufficient credits to post ad. Clicking the "Next >>" button would bring them to the familiar from Free Mode page for selecting images to upload. The difference is, that the number of allowed images is reflected the option client selected at the Payment page. If client selected not to have images, then this page would be skipped at all and client would be directed to the category selection page. In other words all the options client selected is memorized until the final ad submission or until clicking over the "Post Ad" link. This obviously prevents clients from selecting one set of options but trying to post with other options. For the same reason, unlike in Free Mode, clients cannot change the ad duration at the final ad submission page.

The only way to change options, is to click "Post Ad". At that point the memorized options are cleared from clients session and they are directed back to the initial start up page.

Attention: This is the most important chapter in the section. Although it is filled with technical terms, you will need to have a complete understanding on how the automated credit purchasing system works in order to be able to answer client questions in this matter.

All credits purchasing must be initiated from "Purchase Credits with PayPal" button on the ad post start up page. After clients enter the amount of credits they wish to purchase and click the button, they directed to PayPal secure site to make payments. After the transaction is complete clients presented with final PayPal page with "Continue" button. They should click that button to return to your Classified Board site. The brief instruction at the top of the ad post start up page highly encourage clients to do so.

Important: For the clients to successfully return to your Board make sure you have a correct URL address to your Board specified on "Admin Preferences" page within "Site URL" box.

Let's see how exactly the automated system works.

1. Once transaction is complete at PayPal, but before the time when user comes back to your Board, PayPal server initiate a seamless background "dialog" (IPN notification) with the script on your board. During this process the data about transaction details such as payment status, transaction number, transaction amount, client name, your Email address, client Email address etc.. is posted back to board script - cl_notify.asp

2. cl_notify.asp script among other data, receives the designated User ID by which users are identified on the classified board. The script runs a security routine to prevent fraud notifications and then posted the amount to user account who initiated the purchasing. PayPal may reports different payment status.
   Note: It is important to remember that the credits are posted to user accounts in two cases only: 1) When PayPal reports that the transaction status is "Completed", meaning user successfully paid you some amount and 2) The transaction status is "Completed" but the transaction type is "reversal". This means that PayPal for one reason or another initiated the funds reversal in which case the amount is Deducted from user account. In both cases above the Email from the Board is sent to the user (Templates - Credits_Add, Credits_Removed) For all other cases of Payment Status (Pending, Failed, Refund, Denied....)  no Actions will be taken. ALL transaction details however will be logged.
   
   The transaction log can be accessed via main Admin page by clicking "Payments Log". This log contain thorough information about all transactions posted by PayPal. The "Status" column tells you whether the transaction is valid (i.e. the post comes from PayPal site) or someone is trying to hack into your payment system by posting a fraud transaction or there has been a glitch on PayPal site which prevents successful communication with PayPal. All successful transactions should have status "Verified". The column "Pay Status" tells you the payment status of transactions. It could be "Completed", Pending", "Failed", "Denied", "Refund". Once again, only "Completed" Pay Status initiates credit post to user's account. In case of the "Pending" status, PayPal needs to verify validity of the payer's funds. This might take up a few days. If funds are eventually cleared, then there will be second notification with the status "Completed" at which time amount will be posted to user account. The last column "Details" contains more information, when you click on the PayPal link. Pay attention to the Note section of it, this is where you get more detailed explanation about transaction.

3. So now the credits amount is posted to user's account. But it is not yet available to user's current session. While clients click "Continue" on PayPal final page, they directed to the return page cl_return.asp. This is second page where PayPal posts transaction details (exact the same information was posted to cl_notify.asp). Only this time the information is available to share with client. Client prompted with all the information available and at the same time this information is compared with the one has been sent to cl_notify.asp to verify the transaction integrity and validity. The existing log entry for this transaction gets update with the user IP address and if everything checks out to be valid, user Credits Session variable gets updated with new amount (shown right next to user name at the top navigation bar). At this point User click "Post Ad" and may start with options selection having sufficient Credits to spend.
   If the session is expired by the time clients return from PayPal site, then purchased credit level will be available once they logged back to the system.

Transaction log can be converted to .csv on the fly and downloaded from Payments Log page. Cvs log destroyed after the download and download occur with "stream" ADO object and not with direct URL download.

It worth to mention that PayPal itself has an extensive Email notification in place. Combined with the detailed "Payments Log" you may easy investigate and maintain your board payment transactions.

To view individual users credit level open "User Manager" page. It is also possible to add/remove credits from individual user accounts manually here by selecting amount next to the credit level in the user properties and then clicking "+" or "-".

For more Information on IPN Notification, testing your system and other topics please go PayPal Merchant Tools and logon.  

Submit your question at http://www.4u2ges.com