pp-adaptive 0.0.2

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+\#*
+.\#*

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in pp-adaptive.gemspec
+gemspec

data/README.md

@@ -0,0 +1,54 @@
+# A Ruby API for PayPal Adaptive Payments
+
+  - Current Status: Work-in-progress (don't use, API subject to major change)
+  - Working:
+    - setting up an explicit preapproval
+    - processing payments (for an explicit preapproval)
+  - Not working:
+    - executing pre-created payments
+    - changing options on a created payment
+    - refunds/cancellations
+    - minor things like currency conversion requests
+
+This gem provides access to PayPal's Adaptive Payments API using easy-to-use
+ruby classes.  The internals are largely backed by
+[Virtus](https://github.com/solnic/virtus) and
+[RestClient](https://github.com/archiloque/rest-client), and so are easy to
+work with.
+
+## Installing the Gem
+
+Via rubygems:
+
+    gem install pp-adaptive
+
+## Setting up a Preapproval Agreement
+
+``` ruby
+    require 'pp-adaptive'
+    
+    client = AdaptivePayments::Client.new(
+      :user_id       => "your-api-user-id",
+      :password      => "your-api-password",
+      :signature     => "your-api-signature",
+      :app_id        => "your-app-id",
+      :sandbox       => false
+    )
+
+    response = client.execute(AdaptivePayments::PreapprovalRequest.new(
+      :ending_date      => DateTime.now.next_year,
+      :starting_date    => DateTime.now,
+      :max_total_amount => BigDecimal("950.00"),
+      :currency_code    => "USD",
+      :cancel_url       => "http://site.com/cancelled",
+      :return_url       => "http://site.com/completed"
+    ))
+    
+    if response.success?
+      puts "Preapproval key: #{response.preapproval_key}"
+    else
+      puts "#{response.ack_code}: #{response.error_message}"
+    end
+```
+
+(Work in progress...)

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task :default => :spec
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end

data/lib/pp-adaptive/abstract_request.rb

@@ -0,0 +1,44 @@
+module AdaptivePayments
+  # AbstractRequest is a JsonModel that defines some default behaviour for all requests
+  #
+  # A request defines the operation it executes and provides a method for building the corresponding response.
+  # All requests provide a RequestEnvelope by default.  There is no need to re-define it in descendants.
+  class AbstractRequest < JsonModel
+    # The RequestEnvelope, providing the detail_level and error_language.
+    #
+    # Aliases are defined for #detail_level and #error_language.  They do not need to be accessed through the
+    # request_envelope.
+    attribute :request_envelope, Node[RequestEnvelope], :param => "requestEnvelope"
+
+    alias_params :request_envelope, {
+      :detail_level   => :detail_level,
+      :error_language => :error_language
+    }
+
+    class << self
+      # Set or get the API operation for the request class
+      #
+      # @param [Symbol] name
+      #   the name of the operation defined in the Adaptive Payments API, optional
+      #
+      # @return [Symbol]
+      #   the name of the operation defined in the Adaptive Payments API
+      def operation(name = nil)
+        @operation = name unless name.nil?
+        @operation
+      end
+
+      # Given a JSON string, return the corresponding response.
+      #
+      # @param [String] json
+      #   the raw JSON string as returned by the API
+      #
+      # @return [AbstractResponse]
+      #   the corresponding response for the JSON
+      def build_response(json)
+        klass = AdaptivePayments.const_get(operation.to_s + "Response")
+        klass.from_json(json.to_s)
+      end
+    end
+  end
+end

data/lib/pp-adaptive/abstract_response.rb

@@ -0,0 +1,46 @@
+module AdaptivePayments
+  # AbstractResponse provides a JsonModel with the default behaviour for all responses
+  #
+  # The ResponseEnvelope is already included by default.  It does not need to be redeclared in descendants.
+  #
+  # All responses have FaultMessage behaviour mixed in, so will behave as a FaultMessage if the API returns one.
+  class AbstractResponse < JsonModel
+    include FaultMessage
+
+    # The ResponseEnvelope, encapsulating common information about the response
+    #
+    # All attributes #ack_code, #build, #correlation_id and #time are aliased as top-level attributes,
+    # so you do not need to access #response_envelope directly.
+    #
+    # @see #success?, #failure?, #warning?, #success_with_warning?, #failure_with_warning?
+    attribute :response_envelope, Node[ResponseEnvelope], :param => "responseEnvelope"
+
+    alias_params :response_envelope, {
+      :ack_code       => :ack_code,
+      :build          => :build,
+      :correlation_id => :correlation_id,
+      :time           => :time
+    }
+
+    class << self
+      # Set or get the API operation
+      #
+      # This method should be called in descendants, but is not currently used.
+      #
+      # @param [Symbol] name
+      #   the name of the API operation as defined by PayPal, optional
+      #
+      # @return [Symbol]
+      #   the name of the API operation as defined by PayPal
+      def operation(name = nil)
+        @operation = name unless name.nil?
+        @operation
+      end
+    end
+
+    # Provide status predicates for the possible response ack codes
+    %w{success? failure? warning? success_with_warning? failure_with_warning?}.each do |method|
+      define_method(method) { response_envelope.send(method) }
+    end
+  end
+end

data/lib/pp-adaptive/cancel_preapproval_request.rb

@@ -0,0 +1,7 @@
+module AdaptivePayments
+  class CancelPreapprovalRequest < AbstractRequest
+    operation :CancelPreapproval
+
+    attribute :preapproval_key, String, :param => "preapprovalKey"
+  end
+end

data/lib/pp-adaptive/cancel_preapproval_response.rb

@@ -0,0 +1,7 @@
+module AdaptivePayments
+  class CancelPreapprovalResponse < AbstractResponse
+    operation :CancelPreapproval
+
+    # no fields to define
+  end
+end

data/lib/pp-adaptive/client.rb

@@ -0,0 +1,56 @@
+require "rest-client"
+require "virtus"
+
+module AdaptivePayments
+  class Client
+    include Virtus
+
+    attribute :user_id,   String, :header => "X-PAYPAL-SECURITY-USERID"
+    attribute :password,  String, :header => "X-PAYPAL-SECURITY-PASSWORD"
+    attribute :signature, String, :header => "X-PAYPAL-SECURITY-SIGNATURE"
+    attribute :app_id,    String, :header => "X-PAYPAL-APPLICATION-ID"
+    attribute :device_ip, String, :header => "X-PAYPAL-DEVICE-IPADDRESS"
+
+    def initialize(options = {})
+      super
+      self.sandbox = options[:sandbox]
+    end
+
+    def sandbox=(flag)
+      @sandbox = !!flag
+    end
+
+    def sandbox?
+      !!@sandbox
+    end
+
+    def execute(request)
+      base_url = if sandbox?
+        "https://svcs.sandbox.paypal.com/AdaptivePayments"
+      else
+        "https://svcs.paypal.com/AdaptivePayments"
+      end
+
+      resource = RestClient::Resource.new(base_url, :headers => headers)
+      response = resource[request.class.operation.to_s].post(
+        request.to_json,
+        :content_type => :json,
+        :accept       => :json
+      )
+      request.class.build_response(response)
+    end
+
+    private
+
+    def headers
+      base_headers = {
+        "X-PAYPAL-RESPONSE-DATA-FORMAT" => "JSON",
+        "X-PAYPAL-REQUEST-DATA-FORMAT"  => "JSON"
+      }
+      attributes.inject(base_headers) do |hash, (attr, value)|
+        next hash if value.nil?
+        hash.merge(self.class.attributes[attr].options[:header] => value)
+      end
+    end
+  end
+end

data/lib/pp-adaptive/convert_currency_request.rb

@@ -0,0 +1,33 @@
+module AdaptivePayments
+  class ConvertCurrencyRequest < AbstractRequest
+    operation :ConvertCurrency
+
+    attribute :base_amount_list,         Node[CurrencyList],     :param => "baseAmountList"
+    attribute :convert_to_currency_list, NodeList[CurrencyCode], :param => "convertToCurrencyList"
+    attribute :country_code,             String,                 :param => "countryCode"
+    attribute :conversion_type,          String,                 :param => "conversionType"
+
+    alias_params :base_amount_list, {
+      :currencies => :currencies
+    }
+
+    alias_params :first_currency, {
+      :amount     => :amount,
+      :code       => :code
+    }
+
+    def convert_to_currencies
+      convert_to_currency_list.collect { |info| info[:code] }
+    end
+    
+    def convert_to_currencies=(list_of_currencies)
+      self.convert_to_currency_list = list_of_currencies.map { |t| { :code => t } }
+    end
+
+    private
+
+    def first_currency
+      currencies[0] ||= CurrencyList.new
+    end
+  end
+end

data/lib/pp-adaptive/convert_currency_response.rb

@@ -0,0 +1,11 @@
+module AdaptivePayments
+  class ConvertCurrencyResponse < AbstractResponse
+    operation :ConvertCurrency
+
+    attribute :estimated_amount_table, Node[CurrencyConversionTable], :param => "estimatedAmountTable"
+
+    alias_params :estimated_amount_table, {
+      :currency_conversions => :currency_conversion_list
+    }
+  end
+end

data/lib/pp-adaptive/execute_payment_request.rb

@@ -0,0 +1,9 @@
+module AdaptivePayments
+  class ExecutePaymentRequest < AbstractRequest
+    operation :ExecutePayment
+
+    attribute :pay_key,         String, :param => "payKey"
+    attribute :action_type,     String, :param => "actionType"
+    attribute :funding_plan_id, String, :param => "fundingPlanId"
+  end
+end

data/lib/pp-adaptive/execute_payment_response.rb

@@ -0,0 +1,12 @@
+module AdaptivePayments
+  class ExecutePaymentResponse < AbstractResponse
+    operation :ExecutePayment
+
+    attribute :payment_exec_status, String,             :param => "paymentExecStatus"
+    attribute :pay_error_list,      Node[PayErrorList], :param => "payErrorList"
+
+    alias_params :pay_error_list, {
+      :pay_errors => :pay_errors
+    }
+  end
+end

data/lib/pp-adaptive/get_payment_options_request.rb

@@ -0,0 +1,7 @@
+module AdaptivePayments
+  class GetPaymentOptionsRequest < AbstractRequest
+    operation :GetPaymentOptions
+
+    attribute :pay_key, String, :param => "payKey"
+  end
+end

data/lib/pp-adaptive/get_payment_options_response.rb

@@ -0,0 +1,32 @@
+module AdaptivePayments
+  class GetPaymentOptionsResponse < AbstractResponse
+    operation :GetPaymentOptions
+
+    attribute :initiating_entity,   Node[InitiatingEntity],     :param => "initiatingEntity"
+    attribute :display_options,     Node[DisplayOptions],       :param => "displayOptions"
+    attribute :shipping_address_id, String,                     :param => "shippingAddressId"
+    attribute :sender_options,      Node[SenderOptions],        :param => "senderOptions"
+    attribute :receiver_options,    NodeList[ReceiverOptions],  :param => "receiverOptions"
+
+    alias_params :initiating_entity, {
+      :institution_id          => :institution_id,
+      :customer_first_name     => :customer_first_name,
+      :customer_last_name      => :customer_last_name,
+      :customer_display_name   => :customer_display_name,
+      :institution_customer_id => :institution_customer_id,
+      :customer_country_code   => :customer_country_code,
+      :customer_email          => :customer_email
+    }
+
+    alias_params :display_options, {
+      :email_header_image_url    => :email_header_image_url,
+      :email_marketing_image_url => :email_marketing_image_url,
+      :header_image_url          => :header_image_url,
+      :business_name             => :business_name
+    }
+
+    alias_params :sender_options, {
+      :require_shipping_address_selection => :require_shipping_address_selection
+    }
+  end
+end

data/lib/pp-adaptive/pay_request.rb

@@ -0,0 +1,64 @@
+module AdaptivePayments
+  class PayRequest < AbstractRequest
+    operation :Pay
+
+    attribute :receiver_list,                      Node[ReceiverList],      :param => "receiverList"
+    attribute :action_type,                        String,                  :param => "actionType"
+    attribute :currency_code,                      String,                  :param => "currencyCode"
+    attribute :cancel_url,                         String,                  :param => "cancelUrl"
+    attribute :return_url,                         String,                  :param => "returnUrl"
+    attribute :ipn_notification_url,               String,                  :param => "ipnNotificationUrl"
+    attribute :sender,                             Node[SenderIdentifier]
+    attribute :preapproval_key,                    String,                  :param => "preapprovalKey"
+    attribute :pin,                                String
+    attribute :reverse_parallel_payments_on_error, Boolean,                 :param => "reverseAllParallelPaymentsOnError"
+    attribute :tracking_id,                        String,                  :param => "trackingId"
+    attribute :memo,                               String
+    attribute :funding_constraint,                 Node[FundingConstraint], :param => "fundingConstraint"
+    attribute :client_details,                     Node[ClientDetailsType], :param => "clientDetails"
+
+    include ReceiverListAliases
+
+    alias_params :client_details, {
+      :client_ip_address     => :ip_address,
+      :client_device_id      => :device_id,
+      :client_application_id => :application_id,
+      :client_model          => :model,
+      :client_geo_location   => :geo_location,
+      :client_customer_type  => :customer_type,
+      :client_partner_name   => :partner_name,
+      :client_customer_id    => :customer_id
+    }
+
+    alias_params :sender, {
+      :sender_email           => :email,
+      :sender_phone           => :phone,
+      :use_sender_credentials => :use_credentials
+    }
+
+    alias_params :sender_phone, {
+      :sender_phone_country_code => :country_code,
+      :sender_phone_number       => :phone_number,
+      :sender_phone_extension    => :extension
+    }
+
+    alias_params :funding_constraint, {
+      :allowed_funding_type => :allowed_funding_type
+    }
+
+    alias_params :allowed_funding_type, {
+      :allowed_funding_type_info => :funding_type_info
+    }
+
+    def allowed_funding_types
+      allowed_funding_type_info.collect { |info| info[:funding_type] }
+    end
+
+    def allowed_funding_types=(list_of_types)
+      self.allowed_funding_type_info = list_of_types.map { |t| { :funding_type => t } }
+    end
+
+    # For explicit approval, redirect the user to https://www.paypal.com/webscr?cmd=_ap-payment&paykey=value
+    # When paying for DIGITALGOODS, use https://paypal.com/webapps/adaptivepayment/flow/pay?paykey=
+  end
+end

data/lib/pp-adaptive/pay_response.rb

@@ -0,0 +1,29 @@
+module AdaptivePayments
+  class PayResponse < AbstractResponse
+    operation :Pay
+
+    attribute :pay_key,                   String,             :param => "payKey"
+    attribute :payment_exec_status,       String,             :param => "paymentExecStatus"
+    attribute :default_funding_plan,      Node[FundingPlan],  :param => "defaultFundingPlan"
+    attribute :pay_error_list,            Node[PayErrorList], :param => "payErrorList"
+
+    alias_params :default_funding_plan, {
+      :funding_plan_id           => :id,
+      :funding_amount            => :amount,
+      :funding_currency_code     => :currency_code,
+      :backup_funding_source     => :backup_funding_source,
+      :sender_fees_amount        => :sender_fees_amount,
+      :sender_fees_currency_code => :sender_fees_currency_code,
+      :from_currency_amount      => :from_currency_amount,
+      :from_currency_code        => :from_currency_code,
+      :to_currency_amount        => :to_currency_amount,
+      :to_currency_code          => :to_currency_code,
+      :exchange_rate             => :exchange_rate,
+      :charges                   => :charges
+    }
+
+    alias_params :pay_error_list, {
+      :pay_errors => :pay_errors
+    }
+  end
+end

data/lib/pp-adaptive/payment_details_request.rb

@@ -0,0 +1,9 @@
+module AdaptivePayments
+  class PaymentDetailsRequest < AbstractRequest
+    operation :PaymentDetails
+
+    attribute :pay_key,        String, :param => "payKey"
+    attribute :transaction_id, String, :param => "transactionId"
+    attribute :tracking_id,    String, :param => "trackingId"
+  end
+end

data/lib/pp-adaptive/payment_details_response.rb

@@ -0,0 +1,53 @@
+module AdaptivePayments
+  class PaymentDetailsResponse < AbstractResponse
+    operation :PaymentDetails
+
+    attribute :cancel_url,                         String,                  :param => "cancelUrl"
+    attribute :ipn_notification_url,               String,                  :param => "ipnNotificationUrl"
+    attribute :return_url,                         String,                  :param => "returnUrl"
+    attribute :memo,                               String
+    attribute :currency_code,                      String,                  :param => "currencyCode"
+    attribute :payment_info_list,                  Node[PaymentInfoList],   :param => "paymentInfoList"
+    attribute :status,                             String
+    attribute :tracking_id,                        String,                  :param => "trackingId"
+    attribute :pay_key,                            String,                  :param => "payKey"
+    attribute :action_type,                        String,                  :param => "actionType"
+    attribute :fees_payer,                         String,                  :param => "feesPayer"
+    attribute :reverse_parallel_payments_on_error, Boolean,                 :param => "reverseAllParallelPaymentsOnError"
+    attribute :preapproval_key,                    String,                  :param => "preapprovalKey"
+    attribute :funding_constraint,                 Node[FundingConstraint], :param => "fundingConstraint"
+    attribute :sender,                             Node[SenderIdentifier]
+
+    alias_params :sender, {
+      :sender_email           => :email,
+      :sender_phone           => :phone,
+      :use_sender_credentials => :use_credentials
+    }
+
+    alias_params :sender_phone, {
+      :sender_phone_country_code => :country_code,
+      :sender_phone_number       => :phone_number,
+      :sender_phone_extension    => :extension
+    }
+
+    alias_params :funding_constraint, {
+      :allowed_funding_type => :allowed_funding_type
+    }
+
+    alias_params :allowed_funding_type, {
+      :allowed_funding_type_info => :funding_type_info
+    }
+
+    alias_params :payment_info_list, {
+      :payments => :payment_info
+    }
+
+    def allowed_funding_types
+      allowed_funding_type_info.collect { |info| info[:funding_type] }
+    end
+
+    def receivers
+      payments.collect { |info| info[:receiver] }
+    end
+  end
+end

data/lib/pp-adaptive/preapproval_details_request.rb

@@ -0,0 +1,8 @@
+module AdaptivePayments
+  class PreapprovalDetailsRequest < AbstractRequest
+    operation :PreapprovalDetails
+
+    attribute :preapproval_key,     String,  :param => "preapprovalKey"
+    attribute :get_billing_address, Boolean, :param => "getBillingAddress"
+  end
+end

data/lib/pp-adaptive/preapproval_details_response.rb

@@ -0,0 +1,35 @@
+module AdaptivePayments
+  class PreapprovalDetailsResponse < AbstractResponse
+    operation :PreapprovalDetails
+
+    attribute :approved,                   Boolean
+    attribute :cancel_url,                 String,            :param => "cancelUrl"
+    attribute :return_url,                 String,            :param => "returnUrl"
+    attribute :ipn_notification_url,       String,            :param => "ipnNotificationUrl"
+    attribute :currency_code,              String,            :param => "currencyCode"
+    attribute :max_total_amount,           Decimal,           :param => "maxTotalAmountOfAllPayments"
+    attribute :starting_date,              DateTime,          :param => "startingDate"
+    attribute :ending_date,                DateTime,          :param => "endingDate"
+    attribute :max_amount_per_payment,     Decimal,           :param => "maxAmountPerPayment"
+    attribute :max_payments,               Integer,           :param => "maxNumberOfPayments"
+    attribute :max_payments_per_period,    Integer,           :param => "maxNumberOfPaymentsPerPeriod"
+    attribute :payment_period,             String,            :param => "paymentPeriod"
+    attribute :current_payments,           Integer,           :param => "curPayments"
+    attribute :current_payments_amount,    Decimal,           :param => "curPaymentsAmount"
+    attribute :current_period_attempts,    Integer,           :param => "curPeriodAttempts"
+    attribute :current_period_ending_date, DateTime,          :param => "curPeriodEndingDate"
+    attribute :date_of_month,              Integer,           :param => "dateOfMonth"
+    attribute :day_of_week,                String,            :param => "dayOfWeek"
+    attribute :pin_type,                   String,            :param => "pinType"
+    attribute :sender_email,               String,            :param => "senderEmail"
+    attribute :memo,                       String
+    attribute :status,                     String
+    attribute :fees_payer,                 String,            :param => "feesPayer"
+    attribute :display_max_total_amount,   Boolean,           :param => "displayMaxTotalAmount"
+    attribute :address_list,               Node[AddressList], :param => "addressList"
+
+    alias_params :address_list, {
+      :addresses => :addresses
+    }
+  end
+end

data/lib/pp-adaptive/preapproval_request.rb

@@ -0,0 +1,36 @@
+module AdaptivePayments
+  class PreapprovalRequest < AbstractRequest
+    operation :Preapproval
+
+    attribute :client_details,           Node[ClientDetailsType], :param => "clientDetails"
+    attribute :ending_date,              DateTime,                :param => "endingDate"
+    attribute :starting_date,            DateTime,                :param => "startingDate"
+    attribute :max_total_amount,         Decimal,                 :param => "maxTotalAmountOfAllPayments"
+    attribute :currency_code,            String,                  :param => "currencyCode"
+    attribute :cancel_url,               String,                  :param => "cancelUrl"
+    attribute :return_url,               String,                  :param => "returnUrl"
+    attribute :ipn_notification_url,     String,                  :param => "ipnNotificationUrl"
+    attribute :date_of_month,            Integer,                 :param => "dateOfMonth"
+    attribute :day_of_week,              String,                  :param => "dayOfWeek"
+    attribute :max_amount_per_payment,   Decimal,                 :param => "maxAmountPerPayment"
+    attribute :max_payments,             Integer,                 :param => "maxNumberOfPayments"
+    attribute :max_payments_per_period,  Integer,                 :param => "maxNumberOfPaymentsPerPeriod"
+    attribute :payment_period,           String,                  :param => "paymentPeriod"
+    attribute :memo,                     String
+    attribute :sender_email,             String,                  :param => "senderEmail"
+    attribute :pin_type,                 String,                  :param => "pinType"
+    attribute :fees_payer,               String,                  :param => "feesPayer"
+    attribute :display_max_total_amount, Boolean,                 :param => "displayMaxTotalAmount"
+
+    alias_params :client_details, {
+      :client_ip_address     => :ip_address,
+      :client_device_id      => :device_id,
+      :client_application_id => :application_id,
+      :client_model          => :model,
+      :client_geo_location   => :geo_location,
+      :client_customer_type  => :customer_type,
+      :client_partner_name   => :partner_name,
+      :client_customer_id    => :customer_id
+    }
+  end
+end

data/lib/pp-adaptive/preapproval_response.rb

@@ -0,0 +1,7 @@
+module AdaptivePayments
+  class PreapprovalResponse < AbstractResponse
+    operation :Preapproval
+
+    attribute :preapproval_key, String, :param => "preapprovalKey"
+  end
+end

data/lib/pp-adaptive/refund_request.rb

@@ -0,0 +1,14 @@
+module AdaptivePayments
+  class RefundRequest < AbstractRequest
+    operation :Refund
+
+    attribute :currency_code,        String,             :param => "currencyCode"
+    attribute :pay_key,              String,             :param => "payKey"
+    attribute :tracking_id,          String,             :param => "trackingId"
+    attribute :transaction_id,       String,             :param => "transactionId"
+    attribute :receiver_list,        Node[ReceiverList], :param => "receiverList"
+    attribute :ipn_notification_url, String,             :param => "ipnNotificationUrl"
+
+    include ReceiverListAliases
+  end
+end

data/lib/pp-adaptive/refund_response.rb

@@ -0,0 +1,12 @@
+module AdaptivePayments
+  class RefundResponse < AbstractResponse
+    operation :Refund
+
+    attribute :currency_code,    String,               :param => "currencyCode"
+    attribute :refund_info_list, Node[RefundInfoList], :param => "refundInfoList"
+
+    alias_params :refund_info_list, {
+      :refund_info => :refund_info
+    }
+  end
+end