added preapproval implementation and some docs

lib/active_merchant/billing/gateways/paypal_adaptive_payments.rb

@@ -43,7 +43,20 @@ def details_for_payment options
       def refund options
         commit 'Refund', build_adaptive_refund_details(options)
       end
-
+
+      # Send a preapproval request to pay pal
+      #
+      # ==== Options
+      #
+      # * +:end_date+ - _xs:datetime_ The ending date
+      # * +:start_date+ - _xs:datetime_ The start date (defaults: current)
+      # * +:max_amount+ - _xs:decimal_ The preapproved maximum total amount of all payments.
+      # * +:currency_code+ - The currency code (defaults: USD)
+      # * +:cancel_url+ - URL to redirect the sender’s browser to after canceling the preapproval
+      # * +:return_url+ - URL to redirect the sender’s browser to after the sender has logged into PayPal and confirmed the preapproval
+      # * +:notify_url+ - The URL to which you want all IPN messages for this preapproval to be sent. (Optional)
+      #
+      # To get more details on fields see +Paypal PreApproval API+ at https://www.x.com/docs/DOC-1419
       def preapprove_payment options
         commit 'Preapproval', build_preapproval_payment(options)
       end
@@ -153,14 +166,32 @@ def build_adaptive_refund_details options
       end
 
       def build_preapproval_payment options
+        opts = {
+          :currency_code => "USD"
+        }.update(options)
+
         @xml = ''
         xml = Builder::XmlMarkup.new :target => @xml, :indent => 2
         xml.instruct!
         xml.PreapprovalRequest do |x|
+          # request envelope
           x.requestEnvelope do |x|
             x.detailLevel 'ReturnAll'
             x.errorLanguage opts[:error_language] ||= 'en_US'
           end
+
+          # required preapproval fields
+          x.endingDate opts[:end_date]
+          x.startingDate opts[:start_date]
+          x.maxTotalAmountOfAllPayments opts[:max_amount]
+          x.currencyCode opts[:currency_code]
+          x.cancelUrl opts[:cancel_url]
+          x.returnUrl opts[:return_url]
+
+          # notify url
+          if opts[:notify_url]
+            x.ipnNotificationUrl opts[:notify_url]
+          end
         end
       end