PayPal provides a "sandbox" environment in which developers can debug the use of PayPal by new applications (like your new hotspot/UM facility) without making a bunch of real-world credit-card transactions.
In general, I find that User Manager is a complex subsystem which is vastly under-documented. I wasted way too much time trying to use the PayPal sandbox to test my new hotspot/UM facility because of some hidden backdoors in UM that make it fail every time. I thought I would take the time to post some notes describing how I finally made it work, from a more task-oriented focus that the general UM documentation, so that others can benefit from it.
PAYPAL SANDBOX SETUP
Obviously, any instructions as to where to find links on PayPal's website will be obsoleted whenever PayPal decides to reorganize their website. They're certainly different today than they were two years ago, which was the last time I tried to do this.
Go to developer.paypal.com and log in using your existing business ID. Go to Applications. Ignore the two apparent choices (REST and Classic). Instead, go to the left-hand column and click "Sandbox accounts."
You will need at least two sandbox accounts: a business account with the same name as your real business account (or whatever name you will be making actual payments to later), and an account for your test hotspot user to use to make payments to the other account. You have to go through pretty much every screen to create each account as you would for a real PayPal account, especially the business account.
I found I had to create the business account as a personal account first, then "upgrade" it to a business account (because the pages to create a business account directly were dead-ends). You could type in any set of numbers for a bank account to get verified, but not so for a credit card. (Later I found that the sandbox issued the account a couple of phony credit cards, but you had to go to the account area and look for them.)
You will have to get all your phony accounts right before you start testing! If you don't, you can end up making payments to an email address that has not been properly set up to receive payments. PayPal marks these as successful but "unilateral" payments, meaning that they have not yet been delivered to a recipient because the recipient does not yet have an account in the proper state to receive them. User Manager doesn't consider unilateral payments as successful, and so it will create no hotspot user accounts. It's worth testing the payment process in the sandbox outside UM to make sure payments show up at the recipient before you start testing a hotspot system.
As soon as you have created the account, and before upgrading, take the time to visit your setting page and set your email preferences to plain text -- if you leave it on HTML (the default), you will receive "sandbox mail" messages consisting of undecipherable BASE64-type garbage that simply cannot be read. Since part of the process of upgrading to a business account involves responding to "mail" asking you to click a link or enter a code to verify your email address -- which mail will be unreadable -- you will effectively have ruined your sandbox account in a way that will require PayPal's assistance to address.
The sandbox gives you the opportunity to preload your test hotspot user's account with "phony cash" -- take it, so you can avoid typing phony credit card data on every test to make a "payment."
USER MANAGER SETTINGS FOR PAYPAL
("ROUTER" is shorthand for the DNS name or IP address of your router running User Manager.)
This section is valid for both the sandbox and the production environment of PayPal. References to web page form fields are as they appear in ROS 5 or 6.
Although you can (and must) create a few initial User Manager data items in /tool/user-manager (other guides in the wiki explain how to do this), most of the data items are set by accessing the web forms at http://ROUTER/userman.
Start in Settings / Payment Gateways. Enable PayPal. Enter the email address for the account to which you want payments sent. The "return URL" is NOT PayPal's "notify_url", which PayPal uses to report the transaction to UM -- it is the page a new user will be sent to after completing his payment transaction.
The actual "notify_url" is set in the Customer record, and is called "Public host." PayPal will accept either a DNS name or a numeric IP here. It will verify the transaction by POSTing a form to http(s)://{that-value}/user?… Make sure that http(s)://{that-value}/user is accessible from the internet so PayPal can access it.
(One random note: the field "Name for Users" in the Profile settings is documented as "Descriptive name for the Profile that is displayed to the end user when they login to their user page." I thought the user would see this string in the signup page, but the regular Name field shows up instead. The "Name for Users" field does appear in the invoice that PayPal mails the hotspot user.)
USER MANAGER TRANSACTION FLOW
When a new hotspot user uses the PayPal pay screen to pay for a new account, PayPal posts a form to http(s)://{customer-public-host-value}/user?… telling UM that the payment succeeded, failed, or whatever.
If PayPal indicates success, UM double-checks that the message actually came from PayPal by making an https query directly to http://www.paypal.com to check the status of that payment. This double-check transaction is undocumented, and in normal operation is invisible to you. If PayPal validates the payment, then UM creates the hotspot user account; otherwise, it puts a line in the log that the message was not valid. This double-check confounds any attempt to use the sandbox unless you understand how to finesse it.
MAKING THE SANDBOX WORK
Once you have all your phony accounts set up properly in PayPal's sandbox, you can redirect all UM's new-account payment activity to the sandbox simply by editing one line in um/signup_pay_form.html. Change the line
html code
<form name="payform" action="$(url)" method="post">to
html code
<!-- <form name="payform" action="$(url)" method="post"> --> <form name="payform" action="https://www.sandbox.paypal.com/cgi-bin/webscr" method="post">Now you will see all new account sign-up pages routed to the sandbox instead of the live PayPal site.
You will also have to make one more change: because of the double-check that UM performs when it receives a payment posting from PayPal, your payments will all fail until you create a static DNS entry on the UM router for http://www.paypal.com, containing the current IP address of "sandbox.paypal.com". This will make UM's double-check go to the sandbox as well, verifying and completing the transaction.
There's a big corollary to this workaround: your test version of UM must be run on a separate router from any actual production users. Obviously, redirecting all traffic meant for the real http://www.paypal.com to the PayPal sandbox would disrupt the activities of live users. Only UM itself should be exposed to the "poisoned" DNS. For my sandbox testing, I run UM on a dedicated RB750 that does nothing else.
I hope this helps anyone trying to debug a new hotspot setup with PayPal billing.
