Copyright © 2000, William Weiland
The purpose of this module is to allow customers to place an order at a MIVA Merchant © Miva Corp. enabled store which they will then pay for using their PayPal © x.com account. These instructions are used for the MIVA Merchant 5.x.
1) In admin, click Add Modules link (fig 2)
2) Click the file upload button
3) Browse to find the paypalr.mvc file on your hard drive and upload (fig 3)
4) Click Add to add it to the domain
5) Then in admin click on the plus to the left of Stores
6) Click the plus to the left of your store name
7) Click on the Payment Configuration link under your store
8) Check the box next to the Payment via Paypal-R
9) Click Update
10) Click Pages link to get to the User Interface (fig 4)
11) Click Items link at the top of the User Interface page (fig 5)
12) Click the Add Item button (fig 6)
13) Enter paypalr for the code (fig 8)
14) Look up and scroll to the last page of items and Payment via Paypal-R should be at the end of the list of items
15) Select Payment via Paypal-R
16) Click the Add button to assign the module
17) Click on System Extension Configuration link
18) Check the box next to the Payment via Paypal-R
19) Click Update
20) Click on the word Utilities
21) Check the box next to the Payment via Paypal-R
22) Click Update
23) FTP (binary mode) the paypal_1.mvc and paypal_2.mvc to the Merchant root directory, e.g. mm5/ This is the same directory that your merchant.mvc file is located in. It should be the same directory that you have identified the Non-Secure URL to MIVA Merchant in your Admin:Domain Settings:Site Configuration. These must be FTP'd; they are not installed as modules.
Enter data into the applicable input fields (fig 9).
Merchant Script Name
In most cases this is merchant.mvc However, some people have changed this to
things like catalog.mvc, store.mvc, etc. Use the current file name of your store. Do
not include the full URL.
PayPal ID
PayPal accounts are based on your email address. You should have already
established your business or premier PayPal account before installing this
module so that you will know the ID and type of account beforehand. Then
enter the email address which you are using to accept funds through PayPal.
This should be the default email address that you setup in paypal.com.
URL to PayPal
This is a fixed URL. However, PayPal at a later date, may change this URL.
For this reason, you have the option to make the change yourself without
having to get an updated version of this module. At the time this install
document was written, the url was https://www.paypal.com/cgi-bin/webscr
Conversion Rate from USD ($)
This rate allows you to convert your store's currency to a currency that
paypal.com allows you to accept directly. There are several currency types
that you can establish in your paypal.com account. Most will use USD for
US dollars. For example, if your store is based on US dollars, this value
should be 1. If your store is in other than US currency (e.g. Italian lire),
the totals from the sale need to be converted to US dollars in order
to insert the correct amounts into the PayPal screen. This rate will
probably be the same as that rate you are using with the Euro Currency
Module in Merchant. Whenever, the conversion rate changes you will need
to edit this field in admin.
Currency you accept as Default
PayPal.com allows you to accept money in the currency of some countries other
than US dollars. Check with paypal.com to see if yours is available and what
the currency code is. You first login at paypal.com and then go to page
https://www.paypal.com/cgi-bin/webscr?cmd=p/sell/mc/mc_wa The three letter
codes are what is used in this field. You only enter one of them into the
PayPal module admin screen. That is your default.
PayPal Logo URL
When the customer checks out, the PayPal logos can be displayed on the
checkout screens. The URL for this logo on the PayPal site can result
in a broken image on the secure server. Hence, you will need to determine
which logo you are going to use, copy it to your web site (in a virtual
path below Merchant), then enter the virtual path to that logo.
Payment Method Prompt
Normally this will be PayPal. However, you may wish to change that to
Payment via PayPal, PayPal Web Accept, etc.
Additional Instructions
This message appears on the Order Payment screen. It allows you to inform the
customer what the payment process consists of at the PayPal site and that they need to
continue through all of the screens to return to your store to display the
invoice screen.
Invoice Messages (HTML and plain text)
This message appears on the invoice screen using a token. You can pass on
specific info about PayPal payment processing and even include the transaction ID.
It is temporarily not available for emails.
Instant Payment Notification (IPN)
Make sure there is a series of numbers in the input for local code. These
are used to help prevent hacker attempts. When you initally setup the
module, check the box "Include IPN as a hidden input". You can change that
and increase security after you have the module working correctly.
Once it is working correctly, you can follow the onscreen instructions for
entering the IPN URL at paypal.com so that the local code cannot be viewed
or guessed by hackers. Without the local code a hacker cannot update a
fake payment to make it look like an order.
PayPal will post notification of payment directly to your MIVA Merchant
store before the customer even returns to your store's invoice screen. This
means that the customer does NOT need to click the final continue to return
to your store in order to complete the order. This feature solves the
problem that the built in paypal module has had in losing orders when
customers forget to continue. This posting will not contain credit card
details, but will submit info about the transaction directly into your store's
database. This posting is for information and order update only and should
not be considered a verification. The verification can be made from a link
to PayPal in the admin screen in the Order Edit section or by logging in
directly at paypal.com. Also, when you are setting your preferences at
the PayPal site, do not setup PayPal to calculate shipping and tax.
Your MIVA Merchant will do that and pass the values to PayPal. You do
not want PayPal to override the Merchant charges.
Additional Security Checks
Leave these unchecked until you have tested the module and have it working.
Once you are certain the module works correctly you MUST check these last two boxes and
test again. Hackers have found ways of beating some of the other paypal
systems, so I implemented these checks to reduce known hacker exploits. Since hackers continually come
up with new schemes, you must always compare the order total in Miva Merchant with the money received at PayPal.
You must go to https://www.paypal.com and verify the actual payment.
You can add a message and/or icon to the invoice screen using render tokens. The tokens are in the format of
<mvt:item name="itemcode" param="xxxx" />
The templates are listed at the Pages link. You will edit the template by inserting the token and clicking the Update (fig 7). Important: After adding the render token to a template page, you must click the Items link for that page, scroll down to the item name and assign it to the page (fig 8). These two steps are repeated for every page that a module's render token is used on.
This module has four tokens available: <mvt:item name="paypalr" param="icon_opay" /> for icon display on the opay screen, <mvt:item name="paypalr" param="icon_invc" /> for icon display on the invc screen, <mvt:item name="paypalr" param="text_message" /> for invoice message display on the invc screen, <mvt:item name="paypalr" param="html_message" /> for invoice message display on the invc screen
Individual payment details are available through the basic PayPal module (fig 10). The summary reports provide more info for broader time periods and multiple transactions (fig 11, 12).
Q: The payment is made at PayPal.com but the store orders are never updated. The customer does not get an email and the order does not show up in admin.
A: If this happens on every order your IPN posting is not correct between paypal.com and your Miva Merchant store. First, make sure you FTPd the intermediate handler files paypal_1.mvc and paypal_2.mvc to the root mm5/ directory. Also, make sure that the PayPal ID that you entered in the module's admin configuration screen is your correct and "verified" business or premier PayPal ID (default email address). You then have two options:
1) Check the box in the paypal module admin screen to send the IPN URL as a hidden input. Be sure you have nothing entered at paypal.com for IPN URL preference.
OR
2) Go to paypal.com to your Profile:preferences. Then under IPN, check the box and enter the URL to post to. There is a sample URL on your paypal module admin screen which you can view for format. Modify it for your domain. An alternative way to get the IPN URL is to check the box as in option 1 above. Create an order and proceed to checkout. At the last checkout screen at your store, you can view the source to copy and paste to paypal.com the hidden input called notify_url. Then go back and uncheck the box in your paypal module admin. This will ensure that the IPN URL info is used only from the preferences that you entered at paypal.com. Note: This method cannot be used if your store is using the same paypal.com account for multiple Miva Merchant stores. Some people have multiple stores using one paypal.com account so the IPN URL has to be supplied by the paypal module in the store using it.
A: If this happens only with some PayPal orders, then there is a transient Internet communication problem. Your server may be down when the paypal.com server tries to post the order completion data. Or the paypal.com server responsible for posting may go down between when the customer pays and the queue is ready to send your posting. Due to heavy traffic, posting may not be instantaneous. During mid-December each year, I have seen the time between customer payment and the paypal.com IPN being posted as long as 45 minutes. If the customer goes back to your store and starts shopping around again, their previous order number will be deleted before the paypal.com server makes its posting. Hence, the order will never get completed. Likewise, if you have your basket timeout set below that length of time, there will be no order for the paypal.com server to complete. You should make your basket timeout at least two hours. You should also include information in the paypal module's admin screen IPN delay input (so the customer will see it if it happens) about transient delays before the order is finalized.
Q: The orders show up in miva, but shipping charges are not included in the paypal payment. Shipping charges calculated by the shopping cart do not appear to be passed on to PayPal.
A: If you view source at the order payment screen (the screen just before you are taken to paypal.com) you should see the shipping charge as a hidden input that is being passed to paypal.com. The problem is that you have not setup your profile at paypal.com correctly. Log into your account at paypal.com and click on the tab for Profile. Then click on Shipping Calculations.
Per PayPal Technical Support
Create a shipping method, and check the button for allowing transaction based shipping to override what you have in your profile. Click on continue, then click on save. Now your shipping charges passed from your cart will over ride what is listed in the profile.
Frank I.
PayPal Certified Developer
PayPal Merchant Technical Support
Note that you will need to do this for domestic and international shipping.
Q: I'm having sudden problems with not receiving orders, though I receive notification from PayPal that I have received funds. In most cases, the email order notice finally comes through, though one today appears to be lost. In this case, PayPal reports it as order #1234. It is not in the list of orders under Order Processing. The number 1234 does not show up in the Show Baskets either. I haven't made changes and everything has been working fine until now.
A: The key is you have made no changes, some orders are getting into Merchant, and those that do get in, seem to be posting with long delays. Paypal.com is probably running show due to heavy traffic. This happens every year around Christmas time. When the customer returns to your store, the background IPN has not yet posted from paypal.com back to your store. There is a note to tell them not to worry about it; that it might take 30 minutes. But if they are the curious type and go to their basket and start changing things the order number that paypal got will be deleted. Hence, when the IPN finally does post, there is no order to complete. You should have your basket timeout set to 120 or higher. You can also put a note in the order payment screen message to be aware there may be delays in paypal.com notifying your store that a payment has been made during heavy shopping seasons. They should not be concerned and by all means, do not delete the items in the basket after the payment has been made. You can also check to see if there are issues at paypal.com in their live status blog.
Q: I am getting the following error message when return from paypal.com back to my store.
Runtime error in mm5/paypal_1.mvc @ [00000000:000018e0]: paypal_1.mv: Line 208: MvOPEN: Error opening 'Merchant5/,Merchant5/s1,1/paypalr/payhx.dbf': No such file or directory
A: This is being caused by the fact that your PayPal account is using PDT (Payment Data Transfer). With PDT, additional parameters are appended to the return URL as PDT is used to customize your return page with payment information. As you are using IPN already, you are getting the same parameters passed via IPN that you would through PDT. You MUST turn PDT off in your PayPal Profile under 'Website Payment Preferences'. By doing so, you will eliminate the additional parameters that are being appended to the return URL.
Q: I have two stores using the same paypal.com account. Can I use this module to collect payments for both stores?
A: Yes. Check the box in the paypal module admin screen to send the IPN URL as a hidden input. Be sure you have nothing entered at paypal.com for IPN URL preference.
Q: I had a strange transaction. Apparently a customer canceled or didn't complete an order but was charged $.02 on their PayPal account. The item in their basket at the time cost $20+. Nothing on my website costs $.02. What is going on?
A: They tried to hack your account and place a fake order. You correctly had the security settings set in paypal module to block order totals that did not match. If you had not, they would successfully placed an order for $20 while only paying 2 cents. Always make sure the security checks are turned on, i.e. that the order total in merchant matches the amount the customer pays at paypal.com and the email address for the store (recipient) is the same email address the money goes to. Also, you must always manually compare the order total in merchant with the amount paid at paypal.com. No telling if and when hackers will figure out a new exploit.
Q: Is it possible to authorize a sale to hold the funds and then use paypal's authorize and capture panel?
A: If you know how to use paypal's capture, you can add a hidden input on the OPAY page. The input would be <input type="hidden" name="paymentaction" value="authorization"> Make sure you put it inside the form on the OPAY page. It will be submitted to paypal.com along with the other variables.
Still have a question?
