mangopay4-ruby-sdk 3.44.0

data/README.md

@@ -0,0 +1,162 @@
+# Mangopay Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/mangopay4-ruby-sdk.svg)](https://rubygems.org/gems/mangopay4-ruby-sdk) 
+
+Official [Mangopay Gem](https://rubygems.org/gems/mangopay4-ruby-sdk) to access the [Mangopay API](https://docs.mangopay.com/api-reference) from applications written in Ruby.
+
+See the [Mangopay API documentation](https://docs.mangopay.com/) for Ruby samples and details on product features. See the [SDK tests](#tests) for further usage examples.
+
+## Prerequisites
+- * A `ClientId` and an API key – if you don't have these, <a href="https://mangopay.com/contact" target="_blank">contact Sales</a> to get access to the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>
+- Ruby 1.9.2 or higher (tested from 1.9.2 up to 3.4.4)
+
+Since SDK [v3.0.17](https://github.com/Mangopay/mangopay2-ruby-sdk/releases/tag/v3.0.17), the library uses v2.01 of the API. The older API version (v2) is no longer available.
+
+## Installation
+
+* Install the gem by either running ```gem install mangopay4-ruby-sdk```
+or by adding it to your Gemfile ```gem 'mangopay4-ruby-sdk'```
+
+* Call ```MangoPay.configure``` in your script as shown in the snippet below.
+
+### Usage
+
+```ruby
+require 'mangopay'
+
+
+# configuration
+MangoPay.configure do |c|
+  c.preproduction = true
+  c.client_id = 'YOUR_CLIENT_ID'
+  c.client_apiKey = 'YOUR_CLIENT_API_KEY'
+  c.log_file = File.join('mypath', 'mangopay.log')
+  c.http_timeout = 10000
+end
+
+
+# get some user by id
+john = MangoPay::User.fetch(john_id) # => {FirstName"=>"John", "LastName"=>"Doe", ...}
+
+
+# update some of his data
+MangoPay::NaturalUser.update(john_id, {'LastName' => 'CHANGED'}) # => {FirstName"=>"John", "LastName"=>"CHANGED", ...}
+
+
+# get all users (with pagination)
+pagination = {'page' => 1, 'per_page' => 8} # get 1st page, 8 items per page
+users = MangoPay::User.fetch(pagination) # => [{...}, ...]: list of 8 users data hashes
+pagination # => {"page"=>1, "per_page"=>8, "total_pages"=>748, "total_items"=>5978}
+
+# pass custom filters (transactions reporting filters)
+filters = {'MinFeesAmount' => 1, 'MinFeesCurrency' => 'EUR', 'MaxFeesAmount' => 1000, 'MaxFeesCurrency' => 'EUR'}
+reports = MangoPay::Report.fetch(filters) # => [{...}, ...]: list of transaction reports between 1 and 1000 EUR
+
+# get John's bank accounts
+accounts = MangoPay::BankAccount.fetch(john_id) # => [{...}, ...]: list of accounts data hashes (10 per page by default)
+
+
+# error handling
+begin
+  MangoPay::NaturalUser.create({})
+rescue MangoPay::ResponseError => ex
+
+  ex # => #<MangoPay::ResponseError: One or several required parameters are missing or incorrect. [...] FirstName: The FirstName field is required. LastName: The LastName field is required. Nationality: The Nationality field is required.>
+
+  ex.details # => {
+             #   "Message"=>"One or several required parameters are missing or incorrect. [...]",
+             #   "Type"=>"param_error",
+             #   "Id"=>"5c080105-4da3-467d-820d-0906164e55fe",
+             #   "Date"=>1409048671.0,
+             #   "errors"=>{
+             #     "FirstName"=>"The FirstName field is required.",
+             #     "LastName"=>"The LastName field is required.", ...},
+             #   "Code"=>"400",
+             #   "Url"=>"/v2/.../users/natural"
+             # }
+end
+```
+
+### Using multiple Client IDs 
+The Ruby SDK offers the option to create multiple configuration objects tailored to your specific needs:
+
+```
+config = MangoPay::Configuration.new
+config.client_id = 'your-client-id'
+config.client_apiKey = 'your-api-key'
+config.preproduction = true
+```
+
+Add them using:
+
+`MangoPay.add_config('config1', config)`
+
+And perform a call with them using:
+
+`MangoPay.get_config('config1').apply_configuration`
+
+The previous method `configure()` is still working.
+
+### Accessing rate limiting headers
+The API returns rate limiting headers which are automatically updated in the `MangoPay` object:
+
+* X-RateLimit-Limit
+* X-RateLimit-Remaining
+* X-RateLimit-Reset
+
+```
+  MangoPay.ratelimit
+
+  {
+    :limit=>["74", "74", "75", "908"],
+    :remaining=>["2226", "4426", "8725", "104692"],
+    :reset=>["1495615620", "1495616520", "1495618320", "1495701060"]
+  }
+```
+
+For more information, see the [rate limiting](https://docs.mangopay.com/api-reference/overview/rate-limiting) article on the Mangopay docs.
+
+### Log requests and responses
+You can enable logs by setting the ```log_file``` configuration option (see [usage](#usage) above). If you don't want logs, remove the ```log_file``` line.
+
+Requests and responses are filtered, so confidential data is not saved in logs.
+
+### Tests
+Make sure that you have run: 
+```
+bundle install
+```
+Then to run the test suite, run: 
+```
+rspec
+```
+
+## Issues
+
+Create a [GitHub issue](https://github.com/Mangopay/mangopay2-ruby-sdk/issues) to report any problems or request features.
+
+We aim to reply to issues and contributions in a timely manner. For additional followup or anything that can't be shared over GitHub, please get in touch with our Support teams via the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>.
+
+## Contributing
+
+1. Fork the repo.
+
+2. Run the tests. We only take pull requests with passing tests, and it's great
+to know that you have a clean slate: `bundle && bundle exec rspec`
+
+3. Add a test for your change. Only refactoring and documentation changes
+require no new tests. If you are adding functionality or fixing a bug, we need
+a test!
+
+4. Make the test pass.
+
+5. Push to your fork and submit a pull request.
+
+Syntax:
+
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Prefer &&/|| over and/or.
+* MyClass.my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
+* a = b and not a=b.
+* Follow the conventions you see used in the source already.

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+
+task :hello do
+  puts "Running Rakefile"
+end

data/bin/mangopay

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs = " -r irb/completion"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/mangopay'}"
+
+puts "Loading MangoPay gem"
+exec "#{irb} #{libs}"

data/lib/generators/mangopay/install_generator.rb

@@ -0,0 +1,60 @@
+require 'rails/generators/base'
+require 'mangopay'
+
+module Mangopay
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('../../templates', __FILE__)
+      argument :client_id, type: :string,
+        desc: 'The id you want to use to query the MangoPay API (must match with the regex ^[a-z0-9_-]{4,20}$)'
+      argument :client_name, type: :string, desc: "Full name of you're organization"
+      argument :client_email, type: :string, desc: "An email for future contacts"
+      class_option :preproduction, type: :boolean, default: true, desc: 'Whether or not use the preproduction environment'
+
+      desc 'Installs all the basic configuration of the mangopay gem'
+      def setup
+        begin
+          client = client_id_valid?
+          remove_file 'config/initializers/mangopay.rb'
+          @client_id = client_id
+          @client_apiKey = client['APIKey']
+          template 'mangopay.rb.erb', 'config/initializers/mangopay.rb'
+        rescue => e
+          puts e.message
+        end
+      end
+
+      protected
+
+      def client_id_valid?
+        check_client_id_validity
+        check_client_id_availablility
+      end
+
+      def check_client_id_validity
+        if (/^[a-z0-9_-]{4,20}$/ =~ client_id).nil?
+          raise "The client_id must match the regexp ^[a-z0-9_-]{4,20}$"
+        end
+      end
+
+      def check_client_id_availablility
+        client = create_client
+        if client['Type'] == 'ClientID_already_exist'
+          raise client['Message']
+        end
+        client
+      end
+
+      def create_client
+        MangoPay.configure do |c|
+          c.preproduction = options[:preproduction]
+        end
+        MangoPay::Client.create({
+          ClientID: client_id,
+          Name: client_name,
+          Email: client_email
+        })
+      end
+    end
+  end
+end

data/lib/generators/templates/mangopay.rb.erb

@@ -0,0 +1,5 @@
+MangoPay.configure do |c|
+  c.preproduction = <%= options[:preproduction] %>
+  c.client_id = '<%= @client_id %>'
+  c.client_apiKey = '<%= @client_apiKey %>'
+end

data/lib/mangopay/acquiring.rb

@@ -0,0 +1,56 @@
+module MangoPay
+
+  class Acquiring < Resource
+    module PayIn
+      module Card
+        class Direct < Resource
+          def self.create(params, idempotency_key = nil)
+            MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/card/direct", params, {}, idempotency_key)
+          end
+        end
+      end
+
+      module ApplePay
+        class Direct < Resource
+          def self.create(params, idempotency_key = nil)
+            MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/payment-methods/applepay", params, {}, idempotency_key)
+          end
+        end
+      end
+
+      module GooglePay
+        class Direct < Resource
+          def self.create(params, idempotency_key = nil)
+            MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/payment-methods/googlepay", params, {}, idempotency_key)
+          end
+        end
+      end
+
+      module Ideal
+        class Web < Resource
+          def self.create(params, idempotency_key = nil)
+            MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/payment-methods/ideal", params, {}, idempotency_key)
+          end
+        end
+      end
+
+      module PayPal
+        class Web < Resource
+          def self.create(params, idempotency_key = nil)
+            MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/payment-methods/paypal", params, {}, idempotency_key)
+          end
+
+          def self.create_data_collection(params, idempotency_key = nil)
+            MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/payment-methods/paypal/data-collection", params, {}, idempotency_key)
+          end
+        end
+      end
+    end
+
+    class Refund < Resource
+      def self.create(pay_in_id, params, idempotency_key = nil)
+        MangoPay.request(:post, "#{MangoPay.api_path}/acquiring/payins/#{pay_in_id}/refunds", params, {}, idempotency_key)
+      end
+    end
+  end
+end

data/lib/mangopay/authorization_token.rb

@@ -0,0 +1,89 @@
+module MangoPay
+  module AuthorizationToken
+
+    # See http://docs.mangopay.com/api-references/authenticating/
+    class Manager
+
+      class << self
+        def storage
+          @@storage ||= StaticStorage.new
+        end
+
+        def storage= (storage)
+          @@storage = storage
+        end
+
+        def get_token
+          token = storage.get
+          env_key = get_environment_key_for_token
+          if token.nil? || token['timestamp'].nil? || token['timestamp'] <= Time.now || token['environment_key'] != env_key
+            token = MangoPay.request(:post, "/#{MangoPay.version_code}/oauth/token", {}, {}, {}, Proc.new do |req|
+              cfg = MangoPay.configuration
+              req.basic_auth cfg.client_id, cfg.client_apiKey
+              req.body = 'grant_type=client_credentials'
+              req.add_field('Content-Type', 'application/x-www-form-urlencoded')
+            end)
+            token['timestamp'] = Time.now + (token['expires_in'].to_i - 30)
+            token['environment_key'] = env_key
+            storage.store token
+          end
+          token
+        end
+
+        def get_environment_key_for_token
+          cfg = MangoPay.configuration
+          key = "#{cfg.root_url}|#{cfg.client_id}|#{cfg.client_apiKey}"
+          key = Digest::MD5.hexdigest(key)
+          key
+        end
+      end
+    end
+
+    class StaticStorage
+      def get
+        @@token ||= nil
+      end
+
+      def store(token)
+        @@token = token
+      end
+    end
+
+    class FileStorage
+      require 'yaml'
+      @temp_dir
+
+      def initialize(temp_dir = nil)
+        @temp_dir = temp_dir || MangoPay.configuration.temp_dir
+        if !@temp_dir
+          raise "Path to temporary folder is not defined"
+        end
+      end
+
+      def get
+        begin
+          f = File.open(file_path, File::RDONLY)
+          f.flock(File::LOCK_SH)
+          txt = f.read
+          f.close
+          YAML.load(txt) || nil
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+
+      def store(token)
+        File.open(file_path, File::RDWR | File::CREAT, 0644) do |f|
+          f.flock(File::LOCK_EX)
+          f.truncate(0)
+          f.rewind
+          f.puts(YAML.dump(token))
+        end
+      end
+
+      def file_path
+        File.join(@temp_dir, "MangoPay.AuthorizationToken.FileStore.tmp")
+      end
+    end
+  end
+end

data/lib/mangopay/bank_account.rb

@@ -0,0 +1,49 @@
+module MangoPay
+
+  # See http://docs.mangopay.com/api-references/bank-accounts/
+  class BankAccount < Resource
+    include HTTPCalls::Fetch
+    class << self
+      def create(user_id, params, idempotency_key = nil)
+        type = params.fetch(:Type) { |no_symbol_key| params.fetch('Type') }
+        MangoPay.request(:post, "#{url(user_id)}/#{type}", params, {}, idempotency_key)
+      end
+
+      # Fetches:
+      # - list of bank accounts belonging to the given +user_id+
+      # - or single bank account belonging to the given +user_id+ with the given +bank_account_id+.
+      #
+      # In case of list query, optional +filters+ is a hash accepting pagination and sorting params
+      # (+page+, +per_page+, +sort+; see MangoPay::HTTPCalls::Fetch::ClassMethods#fetch)
+      #
+      def fetch(user_id, bank_account_id_or_filters={})
+        bank_account_id, filters = HTTPCalls::Fetch.parse_id_or_filters(bank_account_id_or_filters)
+        MangoPay.request(:get, url(user_id, bank_account_id), {}, filters)
+      end
+
+      # see https://docs.mangopay.com/endpoints/v2.01/bank-accounts#e306_disactivate-a-bank-account
+      def update(user_id, bank_account_id, params = {})
+        MangoPay.request(:put, url(user_id, bank_account_id), params)
+      end
+
+      # Fetches list of transactions belonging to given +bank_account_id+.
+      #
+      # Optional +filters+ is a hash accepting following keys:
+      # - +page+, +per_page+, +sort+: pagination and sorting params (see MangoPay::HTTPCalls::Fetch::ClassMethods#fetch)
+      # - +Status+: TransactionStatus {CREATED, SUCCEEDED, FAILED}
+      # - +ResultCode+: string representing the transaction result
+      def transactions(bank_account_id, filters = {})
+        url = "#{MangoPay.api_path}/bankaccounts/#{bank_account_id}/transactions"
+        MangoPay.request(:get, url, {}, filters)
+      end
+
+      def url(user_id, bank_account_id = nil)
+        if bank_account_id
+          "#{MangoPay.api_path}/users/#{CGI.escape(user_id.to_s)}/bankaccounts/#{CGI.escape(bank_account_id.to_s)}"
+        else
+          "#{MangoPay.api_path}/users/#{CGI.escape(user_id.to_s)}/bankaccounts"
+        end
+      end
+    end
+  end
+end

data/lib/mangopay/bankingaliases.rb

@@ -0,0 +1,29 @@
+module MangoPay
+
+  # See children class:
+  # - MangoPay::BankingAliasesIBAN
+  class BankingAliases < Resource
+    include HTTPCalls::Create
+    include HTTPCalls::Update
+    include HTTPCalls::Fetch
+
+    class << self
+      def create
+        raise 'Cannot create a MangoPay::BankingAlias. See MangoPay::BankingAliasesIBAN'
+      end
+
+      def url(id = nil)
+        if id
+          "#{MangoPay.api_path}/bankingaliases/#{CGI.escape(id)}"
+        else
+          "#{MangoPay.api_path}/bankingaliases"
+        end
+      end
+
+      def fetch_for_wallet(wallet_id, filters = {})
+        url = "#{MangoPay.api_path}/wallets/#{wallet_id}/bankingaliases"
+        MangoPay.request(:get, url, {}, filters)
+      end
+    end
+  end
+end

data/lib/mangopay/bankingaliases_iban.rb

@@ -0,0 +1,16 @@
+module MangoPay
+
+  # See parent class MangoPay::BankingAliases
+  class BankingAliasesIBAN < BankingAliases
+
+    def self.create(params, wallet_id, headers_or_idempotency_key = nil)
+      url = "#{MangoPay.api_path}/wallets/#{wallet_id}/bankingaliases/iban"
+      MangoPay.request(:post, url, params, {}, headers_or_idempotency_key)
+    end
+
+    def self.url(id = nil)
+      "#{super.url(id)}"
+    end
+
+  end
+end

data/lib/mangopay/card.rb

@@ -0,0 +1,54 @@
+module MangoPay
+
+  # See http://docs.mangopay.com/api-references/card/
+  class Card < Resource
+    include HTTPCalls::Fetch
+    include HTTPCalls::Update
+    class << self
+
+      # Retrieves a list of cards having the same fingerprint.
+      # The fingerprint is a hash code uniquely generated
+      # for each 16-digit card number.
+      #
+      # @param +fingerprint+ The fingerprint hash code
+      # @param +filters+ Optional - a hash accepting following keys:
+      # - +page+, +per_page+, +sort+: pagination and sorting params (see MangoPay::HTTPCalls::Fetch::ClassMethods#fetch)
+      def get_by_fingerprint(fingerprint, filters = {})
+        MangoPay.request(:get, fingerprint_url(fingerprint), {}, filters)
+      end
+
+      # Retrieves a list of transactions belonging to given +card_id+.
+      #
+      # Optional +filters+ is a hash accepting following keys:
+      # - +page+, +per_page+, +sort+: pagination and sorting params (see MangoPay::HTTPCalls::Fetch::ClassMethods#fetch)
+      # - +Status+: TransactionStatus {CREATED, SUCCEEDED, FAILED}
+      # - +ResultCode+: string representing the transaction result
+      def transactions(card_id, filters = {})
+        url = url(card_id) + '/transactions'
+        MangoPay.request(:get, url, {}, filters)
+      end
+
+      def fingerprint_url(fingerprint)
+        "#{MangoPay.api_path}/cards/fingerprints/#{fingerprint}"
+      end
+
+      def get_pre_authorizations(card_id, filters = {})
+        MangoPay.request(:get, "#{MangoPay.api_path}/cards/#{card_id}/preauthorizations")
+      end
+
+      def validate(card_id, params)
+        url = "#{MangoPay.api_path}/cards/#{card_id}/validation"
+        MangoPay.request(:post, url, params)
+      end
+
+      def get_card_validation(card_id, validation_id)
+        url = "#{MangoPay.api_path}/cards/#{card_id}/validation/#{validation_id}"
+        MangoPay.request(:get, url)
+      end
+
+      def get_transactions_by_fingerprint(fingerprint, filters = {})
+        MangoPay.request(:get, "#{fingerprint_url(fingerprint)}/transactions", {}, filters)
+      end
+    end
+  end
+end

data/lib/mangopay/card_registration.rb

@@ -0,0 +1,9 @@
+module MangoPay
+
+  # See http://docs.mangopay.com/api-references/card-registration/
+  class CardRegistration < Resource
+    include HTTPCalls::Create
+    include HTTPCalls::Update
+    include HTTPCalls::Fetch
+  end
+end

data/lib/mangopay/client.rb

@@ -0,0 +1,94 @@
+require 'base64'
+
+module MangoPay
+  class Client < Resource
+
+    class << self
+
+      # see https://docs.mangopay.com/api-references/client-details/
+      def fetch()
+        MangoPay.request(:get, url())
+      end
+
+      # see https://docs.mangopay.com/api-references/client-details/
+      def update(params)
+        MangoPay.request(:put, url(), params)
+      end
+
+      # see https://docs.mangopay.com/api-references/client-details/
+      def upload_logo(file_content_base64, file_path = nil)
+        if file_content_base64.nil? && !file_path.nil?
+          bts = File.open(file_path, 'rb') { |f| f.read }
+          file_content_base64 = Base64.encode64(bts)
+        end
+        # normally it returns 204 HTTP code on success
+        begin
+          MangoPay.request(:put, url() + '/logo', {'File' => file_content_base64})
+        rescue ResponseError => ex
+          raise ex unless ex.code == '204'
+        end
+      end
+
+      # Fetch all your client wallets;
+      # +funds_type+ may be:
+      #   - nil: all wallets
+      #   - 'fees': fees wallets
+      #   - 'credit': credit wallets
+      # see https://docs.mangopay.com/api-references/client-wallets/
+      def fetch_wallets(funds_type = nil)
+        MangoPay.request(:get, url() + "/wallets/#{funds_type}")
+      end
+
+      # Fetch one of your client wallets (fees or credit) with a particular currency;
+      # +funds_type+ may be:
+      #   - nil: all wallets
+      #   - 'fees': fees wallets
+      #   - 'credit': credit wallets
+      # +currency_iso_code+ is currncy ISO code
+      # see https://docs.mangopay.com/api-references/client-wallets/
+      def fetch_wallet(funds_type, currency_iso_code)
+        method = :get
+        path = url() + "/wallets/#{funds_type}/#{currency_iso_code}"
+        yield method, path if block_given?
+        MangoPay.request(method, path)
+      end
+
+      # Fetch transactions for all your client wallets.
+      # Optional +filters+ hash: see MangoPay::Transaction.fetch
+      # See https://docs.mangopay.com/api-references/client-wallets/
+      def fetch_wallets_transactions(filters = {})
+        MangoPay.request(:get, url() + "/transactions", {}, filters)
+      end
+
+      # Fetch transactions for one of your client wallets (fees or credit) with a particular currency;
+      # +funds_type+ may be:
+      #   - nil: all wallets
+      #   - 'fees': fees wallets
+      #   - 'credit': credit wallets
+      # +currency_iso_code+ is currncy ISO code
+      # Optional +filters+ hash: see MangoPay::Transaction.fetch
+      # See https://docs.mangopay.com/api-references/client-wallets/
+      def fetch_wallet_transactions(funds_type, currency_iso_code, filters = {})
+        MangoPay.request(:get, url() + "/wallets/#{funds_type}/#{currency_iso_code}/transactions", {}, filters)
+      end
+
+      def create_bank_account(params)
+        MangoPay.request(:post, url() + "/bankaccounts/iban", params)
+      end
+
+      def create_payout(params)
+        method = :post
+        path = url() + "/payouts"
+        yield method, path, params if block_given?
+        MangoPay.request(method, path, params)
+      end
+
+      # Create a Bank Wire PayIn to the Repudiation Wallet
+      # see https://docs.mangopay.com/api-reference/dispute-settlement/create-bank-wire-payin-to-repudiation-wallet
+      def create_bank_wire_direct_pay_in(params, idempotency_key = nil)
+        MangoPay.request(:post, url() + "/payins/bankwire/direct", params, {}, idempotency_key)
+      end
+
+    end
+  end
+end