mangopay 3.0.18 → 3.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 423c179e18019cf3aefcecedd805b3fceb391f4b
-  data.tar.gz: 281642237df4cc0944592fa18af0188c18e5bc8e
+  metadata.gz: b83a705cc7f7ea7dd6954de6b6b0ff58f44c5170
+  data.tar.gz: 3d8eaabef7fce1e401810458ec9010366a5832c3
 SHA512:
-  metadata.gz: 19a7d3665863f82d12766b1b590304cbfbb16ab3e1f2102ad22a34858e8784f08d5782c8177b93a3cce7610f1ce7e6251cc0a4737c43152bd10eacd9e2250858
-  data.tar.gz: c8bf7f070bcc27d9179d813d360346fafeeff0452461a5d0328153f3f0af39c6e025a15a3a27f2d1c49de266673403dfe368f258ec4c0e4dd3926a831786ee16
+  metadata.gz: 1bf56bfe55dfdec69bd83df86a5fe9be1d758af762d5f2c96674b0dd988242ecd85058493013ee8c584b4648311c3aa610bec1304d8da1856139b2167aacb4b4
+  data.tar.gz: 5426a2cbec6a3191a4db3253e52dc54f5b3ba5f0f9c8541be07479285d13db7ad421477ec5ebad2a56fa00062b4907471b465d7783f9936f7d821c7f6eb5d10b

data/README.md

@@ -19,17 +19,12 @@ Since [v3.0.17](https://github.com/Mangopay/mangopay2-ruby-sdk/releases/tag/v3.0
 ## Usage
 
 ### Install
+* You can get yourself a [free sandbox account](https://www.mangopay.com/get-started/create-sandbox/) or sign up for a [production account](https://www.mangopay.com/get-started/submit-your-app/create-credentials/) (note that validation of your production account can take a few days, so think about doing it in advance of when you actually want to go live).
+
 * Install the gem by either running ```gem install mangopay```
 or by adding it to your Gemfile ```gem 'mangopay'```
 
-* The Rails users will be happy to know that there is a new generator script
-that will help you configure your access to the Mangopay API version 2.
-Simply run ``rails generate mangopay:install CLIENT_ID CLIENT_NAME CLIENT_EMAIL``
-where CLIENT_ID is the id you will use to connect to the api
-and CLIENT_NAME is a full name that will be use to identify all communications
-between you and the Mangopay Team.
-
-* Otherwise, call ```MangoPay.configure``` in your script as shown in the snippet below.
+* Using the credential info from the signup process above, call ```MangoPay.configure``` in your script as shown in the snippet below.
 
 ### Examples
 
@@ -37,7 +32,7 @@ between you and the Mangopay Team.
 require 'mangopay'
 
 
-# configuration (not required if Rails generator fired as above)
+# configuration
 MangoPay.configure do |c|
   c.preproduction = true
   c.client_id = 'YOUR_CLIENT_ID'
@@ -63,7 +58,7 @@ pagination # => {"page"=>1, "per_page"=>8, "total_pages"=>748, "total_items"=>59
 accounts = MangoPay::BankAccount.fetch(john_id) # => [{...}, ...]: list of accounts data hashes (10 per page by default)
 
 
-# errors handling
+# error handling
 begin
   MangoPay::NaturalUser.create({})
 rescue MangoPay::ResponseError => ex

data/lib/mangopay.rb

@@ -28,6 +28,7 @@ module MangoPay
   autoload :KycDocument, 'mangopay/kyc_document'
   autoload :Hook, 'mangopay/hook'
   autoload :Refund, 'mangopay/refund'
+  autoload :Dispute, 'mangopay/dispute'
   autoload :JSON, 'mangopay/json'
   autoload :AuthorizationToken, 'mangopay/authorization_token'
 

data/lib/mangopay/dispute.rb

@@ -0,0 +1,124 @@
+require 'base64'
+
+module MangoPay
+
+  # See https://docs.mangopay.com/api-references/disputes/disputes/
+  class Dispute < Resource
+    include HTTPCalls::Fetch
+    include HTTPCalls::Update
+    class << self
+
+      def close(dispute_id)
+        url = url(dispute_id) + "/close/"
+        MangoPay.request(:put, url)
+      end
+
+      # +contested_funds+: Money hash
+      # see 'Contest' section @ https://docs.mangopay.com/api-references/disputes/disputes/
+      def contest(dispute_id, contested_funds)
+        url = url(dispute_id) + "/submit/"
+        MangoPay.request(:put, url, {ContestedFunds: contested_funds})
+      end
+
+      def resubmit(dispute_id)
+        url = url(dispute_id) + "/submit/"
+        MangoPay.request(:put, url)
+      end
+
+      def transactions(dispute_id, filters = {})
+        url = url(dispute_id) + "/transactions/"
+        MangoPay.request(:get, url, {}, filters)
+      end
+
+      def fetch_for_user(user_id, filters = {})
+        url = "#{MangoPay.api_path}/users/#{user_id}/disputes"
+        MangoPay.request(:get, url, {}, filters)
+      end
+
+      def fetch_for_wallet(wallet_id, filters = {})
+        url = "#{MangoPay.api_path}/wallets/#{wallet_id}/disputes"
+        MangoPay.request(:get, url, {}, filters)
+      end
+      
+      #####################################################
+      # repudiations / settlement transfers
+      #####################################################
+
+      # see https://docs.mangopay.com/api-references/disputes/repudiations/
+      def fetch_repudiation(repudiation_id)
+        url = "#{MangoPay.api_path}/repudiations/#{repudiation_id}"
+        MangoPay.request(:get, url)
+      end
+
+      # +params+: hash; see https://docs.mangopay.com/api-references/disputes/settlement-transfers/
+      def create_settlement_transfer(repudiation_id, params)
+        url = "#{MangoPay.api_path}/repudiations/#{repudiation_id}/settlementtransfer/"
+        MangoPay.request(:post, url, params)
+      end
+      
+      #####################################################
+      # documents
+      #####################################################
+
+      # +params+: hash; see https://docs.mangopay.com/api-references/disputes/dispute-documents/
+      def create_document(dispute_id, params)
+        url = url(dispute_id) + "/documents/"
+        MangoPay.request(:post, url, params)
+      end
+
+      def fetch_document(document_id)
+        url = "#{MangoPay.api_path}/dispute-documents/#{document_id}"
+        MangoPay.request(:get, url)
+      end
+
+      # +params+: hash; see 'Edit' section @ https://docs.mangopay.com/api-references/disputes/dispute-documents/
+      def update_document(dispute_id, document_id, params)
+        url = url(dispute_id) + "/documents/#{document_id}"
+        MangoPay.request(:put, url, params)
+      end
+
+      # Fetches list of dispute documents:
+      # - for the particular dispute if +dispute_id+ is provided (not nil)
+      # - or for all disputes otherwise.
+      # 
+      # Optional +filters+ is a hash accepting following keys:
+      # - +page+, +per_page+, +sort+: pagination and sorting params (see MangoPay::HTTPCalls::Fetch::ClassMethods#fetch)
+      # - filters such as +Type+ (e.g. 'REFUND_PROOF') and +Status+ (e.g. 'VALIDATED')
+      # - +BeforeDate+ (timestamp): filters documents with CreationDate _before_ this date
+      # - +AfterDate+ (timestamp): filters documents with CreationDate _after_ this date
+      # 
+      # See https://docs.mangopay.com/api-references/disputes/dispute-documents/
+      #
+      def fetch_documents(dispute_id = nil, filters = {})
+        url = (dispute_id) ? url(dispute_id) + "/documents/" : "#{MangoPay.api_path}/dispute-documents/"
+        MangoPay.request(:get, url, {}, filters)
+      end
+
+      # Adds the file page (attachment) to the given document.
+      # 
+      # See https://docs.mangopay.com/api-references/disputes/dispute-document-pages/ :
+      # - Document have to be in 'CREATED' Status
+      # - You can create as many pages as needed
+      # - Change Status to 'VALIDATION_ASKED' to submit dispute documents
+      # 
+      # The file_content_base64 param may be:
+      # - Base64 encoded file content
+      # - or nil: in this case pass the file path in the next param
+      #
+      def create_document_page(dispute_id, document_id, 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
+          url = url(dispute_id) + "/documents/#{document_id}/pages"
+          MangoPay.request(:post, url, {'File' => file_content_base64})
+        rescue ResponseError => ex
+          raise ex unless ex.code == '204'
+        end
+      end
+
+    end
+  end
+end

data/lib/mangopay/version.rb

@@ -1,3 +1,3 @@
 module MangoPay
-  VERSION = '3.0.18'
+  VERSION = '3.0.19' # disputes
 end

data/spec/mangopay/bank_account_spec.rb

@@ -16,13 +16,13 @@ describe MangoPay::BankAccount do
     it 'creates a new GB bank detail' do
       created = create({
         Type: 'GB',
-        AccountNumber: '18329068',
-        SortCode: '306541',
+        AccountNumber: '63956474',
+        SortCode: '200000',
       })
       expect(created['Id']).not_to be_nil
       expect(created['Type']).to eq('GB')
-      expect(created['AccountNumber']).to eq('18329068')
-      expect(created['SortCode']).to eq('306541')
+      expect(created['AccountNumber']).to eq('63956474')
+      expect(created['SortCode']).to eq('200000')
     end
 
     it 'creates a new US bank detail' do

data/spec/mangopay/dispute_spec.rb

@@ -0,0 +1,240 @@
+describe MangoPay::Dispute do
+
+  # IMPORTANT NOTE!
+  # 
+  # Due to the fact the disputes CANNOT be created on user's side,
+  # a special approach in testing is needed. 
+  # In order to get the tests below pass, a bunch of disputes have
+  # to be prepared on the API server side - if they're not, you can
+  # just skip these tests, as they won't pass.
+  before(:each) do
+    @disputes = MangoPay::Dispute.fetch({'page' => 1, 'per_page' => 100})
+  end
+
+  describe 'FETCH' do
+    it 'fetches disputes' do
+      expect(@disputes).to be_kind_of(Array)
+      expect(@disputes).not_to be_empty
+    end
+    it 'fetches a dispute' do
+      id = @disputes.first['Id']
+      dispute = MangoPay::Dispute.fetch(id)
+      expect(dispute['Id']).to eq(id)
+    end
+  end
+
+  describe 'TRANSACTIONS' do
+    it 'fetches transactions for dispute' do
+      id = @disputes.first['Id']
+      transactions = MangoPay::Dispute.transactions(id, {'per_page' => 1})
+      expect(transactions).to be_kind_of(Array)
+      expect(transactions).not_to be_empty
+    end
+  end
+
+  describe 'FETCH FOR USER AND WALLET' do
+    it 'fetches disputes for user' do
+      id = @disputes.first['Id']
+      transactions = MangoPay::Dispute.transactions(id, {'per_page' => 1})
+      user_id = transactions[0]['AuthorId']
+      disputes = MangoPay::Dispute.fetch_for_user(user_id, {'per_page' => 1})
+      expect(disputes).to be_kind_of(Array)
+      expect(disputes).not_to be_empty
+    end
+    it 'fetches disputes for wallet' do
+      dispute = @disputes.find {|disp| disp['InitialTransactionId'] != nil}
+      expect(dispute).not_to be_nil, "Cannot test fetching disputes for wallet because there's no disputes with transaction ID in the disputes list."
+      payin = MangoPay::PayIn.fetch(dispute['InitialTransactionId'])
+      wallet_id = payin['CreditedWalletId']
+      disputes = MangoPay::Dispute.fetch_for_wallet(wallet_id, {'per_page' => 1})
+      expect(disputes).to be_kind_of(Array)
+      expect(disputes).not_to be_empty
+    end
+  end
+
+  describe 'UPDATE' do
+    it 'updates a dispute' do
+      dispute = @disputes.first
+      id = dispute['Id']
+      new_tag = dispute['Tag'] + '.com'
+      changed_dispute = MangoPay::Dispute.update(id, {Tag: new_tag})
+      expect(changed_dispute['Tag']).to eq(new_tag)
+    end
+  end
+
+  describe 'FETCH REPUDIATION' do
+    it 'fetches a repudiation' do
+      dispute = @disputes.find {|disp| disp['InitialTransactionId'] != nil}
+      expect(dispute).not_to be_nil, "Cannot test closing dispute because there's no disputes with transaction ID in the disputes list."
+      transactions = MangoPay::Dispute.transactions(dispute['Id'], {'per_page' => 1})
+      repudiation_id = transactions[0]['Id']
+      repudiation = MangoPay::Dispute.fetch_repudiation(repudiation_id)
+      expect(repudiation['Id']).to eq(repudiation_id)
+      expect(repudiation['Nature']).to eq('REPUDIATION')
+    end
+  end
+
+  describe 'CREATE SETTLEMENT TRANSFER' do
+    it 'creates settlement transfer' do
+      dispute = @disputes.find {|disp| disp['Status'] == 'CLOSED'}
+      expect(dispute).not_to be_nil, "Cannot test creating settlement transfer because there's no closed disputes in the disputes list."
+      transactions = MangoPay::Dispute.transactions(dispute['Id'], {'per_page' => 1})
+      repudiation_id = transactions[0]['Id']
+      repudiation = MangoPay::Dispute.fetch_repudiation(repudiation_id)
+      params = {
+        AuthorId: repudiation['AuthorId'],
+        DebitedFunds: {Currency: 'EUR', Amount: 1},
+        Fees: {Currency: 'EUR', Amount: 0},
+        Tag: 'Custom tag data'
+      }
+      transfer = MangoPay::Dispute.create_settlement_transfer(repudiation_id, params)
+      expect(transfer['Type']).to eq('TRANSFER')
+      expect(transfer['Nature']).to eq('SETTLEMENT')
+    end
+  end
+
+  describe 'DISPUTE DOCUMENTS API' do
+
+    def find_dispute
+      dispute = @disputes.find {|disp| ['PENDING_CLIENT_ACTION', 'REOPENED_PENDING_CLIENT_ACTION'].include?(disp['Status'])}
+      expect(dispute).not_to be_nil, "Cannot test dispute document API because there's no dispute with expected status in the disputes list."
+      dispute
+    end
+
+    def create_doc(dispute = nil)
+      no_dispute_passed = dispute.nil?
+      dispute = find_dispute if no_dispute_passed
+      params = { Type: 'DELIVERY_PROOF', Tag: 'Custom tag data' }
+      doc = MangoPay::Dispute.create_document(dispute['Id'], params)
+      doc['dispute'] = dispute if no_dispute_passed # add it for testing purposes
+      doc
+    end
+
+    it 'creates dispute document' do
+      doc = create_doc
+      expect(doc['Type']).to eq('DELIVERY_PROOF')
+      expect(doc['Tag']).to eq('Custom tag data')
+      expect(doc['Status']).to eq('CREATED')
+    end
+
+    it 'fetches dispute document' do
+      created_doc = create_doc
+      fetched_doc = MangoPay::Dispute.fetch_document(created_doc['Id'])
+      fields = ['Id', 'Type', 'Tag', 'Status', 'CreationDate', 'RefusedReasonType', 'RefusedReasonMessage']
+      fields.each do |field|
+        expect(fetched_doc[field]).to eq(created_doc[field])
+      end
+    end
+
+    it 'updates dispute document' do
+      created_doc = create_doc
+      changed_doc = MangoPay::Dispute.update_document(created_doc['dispute']['Id'], created_doc['Id'], {
+        Status: 'VALIDATION_ASKED'
+      })
+      expect(changed_doc['Id']).to eq(created_doc['Id'])
+      expect(changed_doc['Status']).to eq('VALIDATION_ASKED')
+    end
+
+    it 'fetches a list of documents' do
+      disp = find_dispute
+      doc1 = create_doc(disp)
+      doc2 = create_doc(disp) # for the same dispute
+
+      filters = {'per_page' => 2, 'sort' => 'CreationDate:desc'}
+
+      # fetch last 2 docs for the dispute
+      docs = MangoPay::Dispute.fetch_documents(disp['Id'], filters)
+      expect(docs).to be_kind_of(Array)
+      expect(docs.count).to eq 2 # exactly 2 as pagiantion requested
+      # all 2 are at top as lastly created
+      # but may share the same CreationDate
+      # so the order between them is undetermined
+      expect(docs).to include(doc1, doc2)
+
+      # fetch all docs ever
+      docs = MangoPay::Dispute.fetch_documents()
+      expect(docs).to be_kind_of(Array)
+      expect(docs.count).to be >= 2
+
+      # fetch last 2 docs ever (sorting by date descending)
+      docs = MangoPay::Dispute.fetch_documents(nil, filters)
+      expect(docs).to be_kind_of(Array)
+      expect(docs.count).to eq 2 # exactly 2 as pagiantion requested
+      expect(docs).to include(doc1, doc2)
+    end
+
+    def create_doc_page(file)
+      disp = find_dispute
+      doc = create_doc(disp)
+      MangoPay::Dispute.create_document_page(disp['Id'], doc['Id'], file)
+    end
+
+    it 'create_document_page accepts Base64 encoded file content' do
+      fnm = __FILE__.sub('.rb', '.png')
+      bts = File.open(fnm, 'rb') { |f| f.read }
+      b64 = Base64.encode64(bts)
+      ret = create_doc_page(b64)
+      expect(ret).to be_nil
+    end
+
+    it 'create_document_page accepts file path' do
+      fnm = __FILE__.sub('.rb', '.png')
+      disp = find_dispute
+      doc = create_doc(disp)
+      ret = MangoPay::Dispute.create_document_page(disp['Id'], doc['Id'], nil, fnm)
+      expect(ret).to be_nil
+    end
+
+    it 'create_document_page fails when input string is not base64-encoded' do
+      file = 'any file content...'
+      expect { create_doc_page(file) }.to raise_error { |err|
+        expect(err).to be_a MangoPay::ResponseError
+        expect(err.code).to eq '400'
+        expect(err.type).to eq 'param_error'
+      }
+    end
+  end
+
+  describe 'CONTEST' do
+    it 'contests a dispute' do
+      dispute = @disputes.find do |disp|
+        ['PENDING_CLIENT_ACTION', 'REOPENED_PENDING_CLIENT_ACTION'].include?(disp['Status']) &&
+        ['CONTESTABLE', 'RETRIEVAL'].include?(disp['DisputeType'])
+      end
+      expect(dispute).not_to be_nil, "Cannot test contesting dispute because there's no available disputes with expected status and type in the disputes list."
+      id = dispute['Id']
+      contested_funds = dispute['Status'] == 'PENDING_CLIENT_ACTION' ? { Amount: 10, Currency: 'EUR' } : nil;
+      changed_dispute = MangoPay::Dispute.contest(id, contested_funds)
+      expect(changed_dispute['Id']).to eq(id)
+      expect(changed_dispute['Status']).to eq('SUBMITTED')
+    end
+  end
+
+  describe 'RESUBMIT' do
+    it 'resubmits a dispute' do
+      dispute = @disputes.find do |disp|
+        ['REOPENED_PENDING_CLIENT_ACTION'].include?(disp['Status'])
+      end
+      expect(dispute).not_to be_nil, "Cannot test resubmiting dispute because there's no available disputes with expected status in the disputes list."
+      id = dispute['Id']
+      changed_dispute = MangoPay::Dispute.resubmit(id)
+      expect(changed_dispute['Id']).to eq(id)
+      expect(changed_dispute['Status']).to eq('SUBMITTED')
+    end
+  end
+
+  describe 'CLOSE' do
+    it 'closes a dispute' do
+      dispute = @disputes.find do |disp|
+        ['PENDING_CLIENT_ACTION', 'REOPENED_PENDING_CLIENT_ACTION'].include?(disp['Status']) &&
+        ['CONTESTABLE', 'RETRIEVAL'].include?(disp['DisputeType'])
+      end
+      expect(dispute).not_to be_nil, "Cannot test closing dispute because there's no available disputes with expected status in the disputes list."
+      id = dispute['Id']
+      changed_dispute = MangoPay::Dispute.close(id)
+      expect(changed_dispute['Id']).to eq(id)
+      expect(changed_dispute['Status']).to eq('CLOSED')
+    end
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mangopay
 version: !ruby/object:Gem::Version
-  version: 3.0.18
+  version: 3.0.19
 platform: ruby
 authors:
 - Geoffroy Lorieux
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-30 00:00:00.000000000 Z
+date: 2015-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -77,6 +77,7 @@ files:
 - lib/mangopay/card.rb
 - lib/mangopay/card_registration.rb
 - lib/mangopay/client.rb
+- lib/mangopay/dispute.rb
 - lib/mangopay/errors.rb
 - lib/mangopay/event.rb
 - lib/mangopay/hook.rb
@@ -102,6 +103,8 @@ files:
 - spec/mangopay/card_registration_spec.rb
 - spec/mangopay/client_spec.rb
 - spec/mangopay/configuration_spec.rb
+- spec/mangopay/dispute_spec.png
+- spec/mangopay/dispute_spec.rb
 - spec/mangopay/event_spec.rb
 - spec/mangopay/fetch_filters_spec.rb
 - spec/mangopay/hook_spec.rb
@@ -153,6 +156,8 @@ test_files:
 - spec/mangopay/card_registration_spec.rb
 - spec/mangopay/client_spec.rb
 - spec/mangopay/configuration_spec.rb
+- spec/mangopay/dispute_spec.png
+- spec/mangopay/dispute_spec.rb
 - spec/mangopay/event_spec.rb
 - spec/mangopay/fetch_filters_spec.rb
 - spec/mangopay/hook_spec.rb