creative-pp-adaptive 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 79cad064ea06aef0e3e1d3ee573ab6a8ed146669
+  data.tar.gz: cea5a9a46df1c20f01228f4bd5ba84b66696efb0
+SHA512:
+  metadata.gz: b0b46b651a5fe7b6689af8eab5befff332d719f62697d3cde86fe4753445c36a557b3ac784488a77981d2385ceebce7eaf4ba935283729a61f24d8ea0296b926
+  data.tar.gz: 0382f8145a703cb141041e9f02f376f6de34c2b31319f66b7a0637a0c09af6a8ed08b1bfc25ee2e168a33cc6a7419ab9f4e2b428ace4352189f46d714eaf2a70

data/.gitignore

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

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - '1.9.3'
+  - '2.0.0'
+  - '2.1.0'

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+All notable changes in this gem will be documented here.
+This project aspires to follow [semantic versioning](http://semver.org).
+
+## 1.1.1 - 2016-05-05
+### Added
+- :receiver_email interpretation in PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID for mobile express checkouts
+
+## 1.1.0 - 2016-03-03
+### Added
+- Support for mobile responsive express checkout via option and new methods on Client
+- "pry" gem in dev dependencies, so one can `binding.pry`
+
+## 1.0.0 - 2014-10-31
+### Added
+- Core funcionality

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,302 @@
+# pp-adative [![Build Status](https://travis-ci.org/flippa/pp-adaptive.svg?branch=master)](https://travis-ci.org/flippa/pp-adaptive)
+
+A Ruby API for PayPal Adaptive Payments
+
+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
+
+All API calls are made by calling `#execute` on the client, with the relevant
+request type. Naming conventions have been ruby-ized, but you should just
+follow along with the PayPal documentation to understand the inputs and outputs.
+
+Some aliases have been added, to make things simpler. Some example scenarios
+are outlined below, but due to the size of the API, this README does not aim
+in any way to be an exhaustive reproduction of the official Adaptive Payments
+documentation. Given the declarative, model-style, nature of the classes in
+this gem, it probably makes sense to just browse the source to know what
+fields are available.
+
+## Example API calls
+
+The following example should give you enough of an idea to be able to
+follow your senses and use this gem in your own applications.
+
+### <a name="regular_payment"></a> Taking a regular payment
+
+A typical checkout payment request starts like this.
+
+``` 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       => true
+)
+
+client.execute(:Pay,
+  :action_type     => "PAY",
+  :receiver_email  => "your@email.com",
+  :receiver_amount => 50,
+  :currency_code   => "USD",
+  :cancel_url      => "https://your-site.com/cancel",
+  :return_url      => "https://your-site.com/return"
+) do |response|
+
+  if response.success?
+    puts "Pay key: #{response.pay_key}"
+
+    # send the user to PayPal to make the payment
+    # e.g. https://www.sandbox.paypal.com/webscr?cmd=_ap-payment&paykey=abc
+    redirect_to client.payment_url(response)
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+### Checking the payment status on return
+
+When the customer is sent back from PayPal to your `return_url`, you need to
+check if the payment was successful or not.
+
+``` 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       => true
+)
+
+client.execute(:PaymentDetails, :pay_key => "pay-key-from-pay-request") do |response|
+  if response.success?
+    puts "Payment status: #{response.payment_exec_status}"
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+end
+```
+
+### Initiating a chained payment
+
+If you need to take a cut of a payment and forward the remainder onto one
+or more other recipients, you use a chained payment. This is just a regular
+PayRequest, except it includes multiple receivers, one of which is marked as
+'primary'.
+
+``` 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       => true
+)
+
+client.execute(:Pay,
+  :action_type     => "PAY",
+  :currency_code   => "USD",
+  :cancel_url      => "https://your-site.com/cancel",
+  :return_url      => "https://your-site.com/return",
+  :receivers       => [
+    { :email => "your@email.com", :amount => 50, :primary => true },
+    { :email => "other@site.tld", :amount => 45 }
+  ]
+) do |response|
+
+  if response.success?
+    puts "Pay key: #{response.pay_key}"
+
+    # send the user to PayPal to make the payment
+    # e.g. https://www.sandbox.paypal.com/webscr?cmd=_ap-payment&paykey=abc
+    redirect_to client.payment_url(response)
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+In the above example, you get $5 from the $50 payment, with the remaining $45
+going to other@site.tld.
+
+### Setting up a Preapproval Agreement
+
+If you need to be able to take payments from a user's account on-demand, you
+get the user to authorize you for preapproved payments.
+
+``` 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
+)
+
+client.execute(:Preapproval,
+  :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"
+) do |response|
+  # you may alternatively pass a PreapprovalRequest instance
+
+  if response.success?
+    puts "Preapproval key: #{response.preapproval_key}"
+
+    # send the user to PayPal to give their approval
+    # e.g. https://www.paypal.com/webscr?cmd=_ap-preapproval&preapprovalkey=abc
+    redirect_to client.preapproval_url(response)
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+### Taking a payment using an existing Preapproval
+
+To take a payment from a user who has previously authorized you for preapproved
+payments, just pass the `pay_key` in the usual PayRequest.
+
+``` 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
+)
+
+client.execute(:Pay,
+  :preapproval_key => "existing-preapproval-key",
+  :action_type     => "PAY",
+  :receiver_email  => "your@email.com",
+  :receiver_amount => 50,
+  :currency_code   => "USD",
+  :cancel_url      => "https://your-site.com/cancel",
+  :return_url      => "https://your-site.com/return"
+) do |response|
+
+  if response.success?
+    puts "Pay key: #{response.pay_key}"
+    puts "Status: #{response.payment_exec_status}"
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+
+end
+```
+
+### Issuing a refund
+
+If you have the pay_key from a previously made payment (up to 60 days), you
+can send a RefundRequest.
+
+``` 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
+)
+
+client.execute(:Refund, :pay_key => "the-pay-key") do |response|
+  if response.success?
+    puts "Refund sent"
+  else
+    puts "#{response.ack_code}: #{response.error_message}"
+  end
+end
+```
+
+You can also do partial refunds by passing an `amount` field in the request.
+
+### <a name="mobile_checkout"></a>Taking a regular payment with a responsive mobile checkout
+Mobile checkouts uses the [Mobile Express Checkout](https://developer.paypal.com/docs/classic/express-checkout/ht_ec-singleItemPayment-curl-etc/) setup, an alternative to adaptive API.  
+The difference is that there is a first POST to paypal to retrieve a token, then a redirect to PayPal, and finally, another POST to paypal after user accepts the payment to finalize the deal.
+
+Please consult `client.rb#express_handshake` and `client.rb#express_perform` for details on what options to pass and what to expect in response.
+
+A TODO is to wrap the response strings in more functional response objects.
+
+```ruby
+# 1. initialize @client with the optional :checkout_type attribute
+@client = AdaptivePayments::Client.new(
+  :user_id       => "your-api-user-id",
+  :password      => "your-api-password",
+  :signature     => "your-api-signature",
+  :app_id        => "your-app-id",
+  :sandbox       => true,
+  :checkout_type => "mobile" # this does the trick
+)
+
+# 2. call the handshake method and obtain the token
+@client.express_handshake(options) do |response|
+  token = response.split("&").select{|param| param["TOKEN="].present?}.first.split("=").last
+  if token.present?
+    # do some transaction logging
+    redirect_to @client.express_checkout_url(token))
+  else
+    render json: response
+  end
+end
+
+# User does his thing at PayPal here
+
+# 3. process PayPal return GET parameters at success_path
+@client.express_perform(options)) do |response|  
+  success = response["ACK=Success"].present? ? true : false
+  # use success boolean to process logging, order updates  
+end      
+```
+
+### Other API calls
+
+Adaptive Payments is a very extensive API with a lot of endpoints and a lot
+of fields within each request. It wouldn't be wise to attempt to document them
+all here, but the official API documentation covers everything in detail.
+
+https://developer.paypal.com/webapps/developer/docs/classic/adaptive-payments/integration-guide/APIntro/
+
+Just ruby-ize the fields (i.e. underscores, not camel case) and open up the
+request/response classes in this repository to get a feel for how this all works.
+
+## Contributors
+
+* [d11wtq](https://github.com/d11wtq)
+* [Maxim-Filimonov](https://github.com/Maxim-Filimonov)
+* [hajder](https://github.com/hajder)
+* [Epigene](https://github.com/Epigene)
+
+## License & Copyright
+
+Copyright © Flippa.com Pty Ltd. Licensed under the MIT license. See the
+LICENSE file for details.

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.rb

@@ -0,0 +1,77 @@
+require "pp-adaptive/version"
+
+require "pp-adaptive/exception"
+
+require "pp-adaptive/support/aliases"
+require "pp-adaptive/support/json_model"
+require "pp-adaptive/support/coerced_array"
+require "pp-adaptive/support/node"
+require "pp-adaptive/support/node_list"
+
+require "pp-adaptive/types/aliases/receiver_aliases"
+require "pp-adaptive/types/aliases/receiver_list_aliases"
+
+require "pp-adaptive/types/client_details_type"
+require "pp-adaptive/types/request_envelope"
+require "pp-adaptive/types/phone_number_type"
+require "pp-adaptive/types/receiver"
+require "pp-adaptive/types/receiver_list"
+require "pp-adaptive/types/account_identifier"
+require "pp-adaptive/types/sender_identifier"
+require "pp-adaptive/types/funding_type_info"
+require "pp-adaptive/types/funding_type_list"
+require "pp-adaptive/types/funding_constraint"
+require "pp-adaptive/types/response_envelope"
+require "pp-adaptive/types/error_data"
+require "pp-adaptive/types/error_list"
+require "pp-adaptive/types/fault_message"
+require "pp-adaptive/types/base_address"
+require "pp-adaptive/types/address"
+require "pp-adaptive/types/address_list"
+require "pp-adaptive/types/currency_type"
+require "pp-adaptive/types/currency_code"
+require "pp-adaptive/types/currency_list"
+require "pp-adaptive/types/currency_conversion"
+require "pp-adaptive/types/currency_conversion_list"
+require "pp-adaptive/types/currency_conversion_table"
+require "pp-adaptive/types/funding_source"
+require "pp-adaptive/types/funding_plan_charge"
+require "pp-adaptive/types/funding_plan"
+require "pp-adaptive/types/invoice_item"
+require "pp-adaptive/types/invoice_data"
+require "pp-adaptive/types/institution_customer"
+require "pp-adaptive/types/initiating_entity"
+require "pp-adaptive/types/receiver_identifier"
+require "pp-adaptive/types/display_options"
+require "pp-adaptive/types/sender_options"
+require "pp-adaptive/types/receiver_options"
+require "pp-adaptive/types/pay_error"
+require "pp-adaptive/types/pay_error_list"
+require "pp-adaptive/types/payment_info"
+require "pp-adaptive/types/payment_info_list"
+require "pp-adaptive/types/refund_info"
+require "pp-adaptive/types/refund_info_list"
+
+require "pp-adaptive/abstract_request"
+require "pp-adaptive/abstract_response"
+require "pp-adaptive/pay_request"
+require "pp-adaptive/pay_response"
+require "pp-adaptive/payment_details_request"
+require "pp-adaptive/payment_details_response"
+require "pp-adaptive/execute_payment_request"
+require "pp-adaptive/execute_payment_response"
+require "pp-adaptive/get_payment_options_request"
+require "pp-adaptive/get_payment_options_response"
+require "pp-adaptive/set_payment_options_request"
+require "pp-adaptive/set_payment_options_response"
+require "pp-adaptive/preapproval_request"
+require "pp-adaptive/preapproval_response"
+require "pp-adaptive/preapproval_details_request"
+require "pp-adaptive/preapproval_details_response"
+require "pp-adaptive/cancel_preapproval_request"
+require "pp-adaptive/cancel_preapproval_response"
+require "pp-adaptive/refund_request"
+require "pp-adaptive/refund_response"
+require "pp-adaptive/convert_currency_request"
+require "pp-adaptive/convert_currency_response"
+require "pp-adaptive/client"

data/lib/pp-adaptive/abstract_request.rb

@@ -0,0 +1,55 @@
+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
+
+      # Get the request class for the given operation.
+      #
+      # @param [Symbol] operation
+      #   the name of the operation
+      #
+      # @return [AbstractRequest]
+      #   the request subclass
+      def for_operation(name)
+        AdaptivePayments.const_get(name.to_s + "Request")
+      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