Implement Provide Dispute Evidence API endpoint.

src/Services/VerifyDocuments.php

@@ -0,0 +1,101 @@
+<?php
+
+namespace Srmklive\PayPal\Services;
+
+use GuzzleHttp\Psr7\MimeType;
+
+class VerifyDocuments
+{
+    /**
+     * @var array
+     */
+    protected static $dispute_evidence_types = [
+        'application/pdf',
+        'image/gif',
+        'image/jpeg',
+        'image/png',
+    ];
+
+    /**
+     * @var string
+     */
+    protected static $dispute_evidence_file_size = 10;
+
+    /**
+     * @var string
+     */
+    protected static $dispute_evidences_size = 50;
+
+    /**
+     * Get Mime type from filename.
+     *
+     * @param string $file
+     *
+     * @return string
+     */
+    public static function getMimeType($file)
+    {
+        return MimeType::fromFilename($file);
+    }
+
+    /**
+     * Check if the evidence file being submitted mime type is valid.
+     *
+     * @param array $files
+     *
+     * @return bool
+     */
+    public static function isValidEvidenceFile(array $files)
+    {
+        $validFile = true;
+        $validSize = true;
+        $total_size = 0;
+
+        self::setFilesSize();
+
+        foreach ($files as $file) {
+            $mime_type = self::getMimeType($file);
+
+            if (!in_array($mime_type, self::$dispute_evidence_types)) {
+                $validFile = false;
+                break;
+            }
+
+            $size = filesize($file);
+
+            if ($size > self::$dispute_evidence_file_size) {
+                $validSize = false;
+                break;
+            }
+
+            $total_size += $size;
+
+            if ($size > self::$dispute_evidences_size) {
+                $validSize = false;
+                break;
+            }
+        }
+
+        if (($validFile === false) || ($validSize === false)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Check file size.
+     *
+     * @param int $bytes
+     * @param int $decimals
+     *
+     * @return array
+     */
+    protected static function setFilesSize()
+    {
+        $size_in_bytes = pow(1024, 2);
+
+        self::$dispute_evidence_file_size *= $size_in_bytes;
+        self::$dispute_evidences_size *= $size_in_bytes;
+    }
+}

src/Traits/PayPalAPI/Disputes.php

@@ -15,7 +15,7 @@ trait Disputes
      */
     public function listDisputes()
     {
-        $this->apiEndPoint = 'v1/customer/disputes';
+        $this->apiEndPoint = "v1/customer/disputes?page_size={$this->page_size}";
 
         $this->verb = 'get';
 

src/Traits/PayPalAPI/DisputesActions.php

@@ -2,80 +2,119 @@
 
 namespace Srmklive\PayPal\Traits\PayPalAPI;
 
+use GuzzleHttp\Psr7;
+use Srmklive\PayPal\Services\VerifyDocuments;
+
 trait DisputesActions
 {
     /**
-     * Accept customer dispute claim.
+     * Acknowledge item has been returned.
      *
      * @param string $dispute_id
      * @param string $dispute_note
-     * @param array  $data
+     * @param string $acknowledgement_type
      *
      * @throws \Throwable
      *
      * @return array|\Psr\Http\Message\StreamInterface|string
      *
-     * @see https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes-actions_accept-claim
+     * @see https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes-actions_acknowledge-return-item
      */
-    public function acceptDisputeClaim(string $dispute_id, string $dispute_note, array $data = [])
+    public function acknowledgeItemReturned(string $dispute_id, string $dispute_note, string $acknowledgement_type)
     {
-        $this->apiEndPoint = "v1/customer/disputes/{$dispute_id}/accept-claim";
-
-        $data['note'] = $dispute_note;
-        $data['accept_claim_type'] = 'REFUND';
+        $this->apiEndPoint = "v1/customer/disputes/{$dispute_id}/acknowledge-return-item";
 
-        $this->options['json'] = $data;
+        $this->options['json'] = [
+            'note'                  => $dispute_note,
+            'acknowledgement_type'  => $acknowledgement_type,
+        ];
 
         $this->verb = 'post';
 
         return $this->doPayPalRequest();
     }
 
     /**
-     * Accept offer to resolve dispute.
+     * Providence evidence in support of a dispute.
+     *
+     * @param string $dispute_id
+     * @param array  $file_path
+     *
+     * @throws \Throwable
+     *
+     * @return array|\Psr\Http\Message\StreamInterface|string
+     *
+     * https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_provide-evidence 
+     */
+    public function provideDisputeEvidence(string $dispute_id, array $files)
+    {
+        if (VerifyDocuments::isValidEvidenceFile($files) === false) {
+            $this->throwInvalidEvidenceFileException();
+        }
+
+        $this->apiEndPoint = "/v1/customer/disputes/{$dispute_id}/provide-evidence";
+
+        $this->setRequestHeader('Content-Type', 'multipart/form-data');
+
+        $this->options['multipart'] = [];
+
+        foreach ($files as $file) {
+            $this->options['multipart'][] = [
+                'name'     => basename($file),
+                'contents' => Psr7\Utils::tryFopen($file, 'r'),
+            ];
+        }
+
+        $this->verb = 'post';
+
+        return $this->doPayPalRequest();        
+    }
+
+    /**
+     * Accept customer dispute claim.
      *
      * @param string $dispute_id
      * @param string $dispute_note
+     * @param array  $data
      *
      * @throws \Throwable
      *
      * @return array|\Psr\Http\Message\StreamInterface|string
      *
-     * @see https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes-actions_accept-offer
+     * @see https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes-actions_accept-claim
      */
-    public function acceptDisputeOfferResolution(string $dispute_id, string $dispute_note)
+    public function acceptDisputeClaim(string $dispute_id, string $dispute_note, array $data = [])
     {
-        $this->apiEndPoint = "v1/customer/disputes/{$dispute_id}/accept-offer";
+        $this->apiEndPoint = "v1/customer/disputes/{$dispute_id}/accept-claim";
 
-        $this->options['json'] = [
-            'note'  => $dispute_note,
-        ];
+        $data['note'] = $dispute_note;
+        $data['accept_claim_type'] = 'REFUND';
+
+        $this->options['json'] = $data;
 
         $this->verb = 'post';
 
         return $this->doPayPalRequest();
     }
 
     /**
-     * Acknowledge item has been returned.
+     * Accept offer to resolve dispute.
      *
      * @param string $dispute_id
      * @param string $dispute_note
-     * @param string $acknowledgement_type
      *
      * @throws \Throwable
      *
      * @return array|\Psr\Http\Message\StreamInterface|string
      *
-     * @see https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes-actions_acknowledge-return-item
+     * @see https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes-actions_accept-offer
      */
-    public function acknowledgeItemReturned(string $dispute_id, string $dispute_note, string $acknowledgement_type)
+    public function acceptDisputeOfferResolution(string $dispute_id, string $dispute_note)
     {
-        $this->apiEndPoint = "v1/customer/disputes/{$dispute_id}/acknowledge-return-item";
+        $this->apiEndPoint = "v1/customer/disputes/{$dispute_id}/accept-offer";
 
         $this->options['json'] = [
-            'note'                  => $dispute_note,
-            'acknowledgement_type'  => $acknowledgement_type,
+            'note'  => $dispute_note,
         ];
 
         $this->verb = 'post';

src/Traits/PayPalRequest.php

@@ -259,4 +259,16 @@ private function throwConfigurationException()
     {
         throw new RuntimeException('Invalid configuration provided. Please provide valid configuration for PayPal API. You can also refer to the documentation at https://srmklive.github.io/laravel-paypal/docs.html to setup correct configuration.');
     }
+
+    /**
+     * @throws RuntimeException
+     */
+    private function throwInvalidEvidenceFileException()
+    {
+        throw new RuntimeException('Invalid evidence file type provided.
+        1. The party can upload up to 50 MB of files per request.
+        2. Individual files must be smaller than 10 MB.
+        3. The supported file formats are JPG, JPEG, GIF, PNG, and PDF.
+        ');
+    }
 }

tests/Feature/AdapterFeatureTest.php

@@ -333,6 +333,35 @@ public function it_can_get_details_for_a_dispute()
         $this->assertArrayHasKey('dispute_id', $response);
     }
 
+    /** @test */
+    public function it_can_provide_evidence_for_a_dispute_claim()
+    {
+        $this->client->setAccessToken([
+            'access_token'  => self::$access_token,
+            'token_type'    => 'Bearer',
+        ]);
+
+        $this->client->setClient(
+            $this->mock_http_client(
+                $this->mockAcceptDisputesClaimResponse()
+            )
+        );
+
+        $mockFiles = [
+            __DIR__ . '/../Mocks/samples/sample.jpg',
+            __DIR__ . '/../Mocks/samples/sample.png',
+            __DIR__ . '/../Mocks/samples/sample.pdf',
+        ];
+
+        $response = $this->client->provideDisputeEvidence(
+            'PP-D-27803',
+            $mockFiles
+        );
+
+        $this->assertNotEmpty($response);
+        $this->assertArrayHasKey('links', $response);
+    }
+
     /** @test */
     public function it_can_accept_dispute_claim()
     {
@@ -348,7 +377,7 @@ public function it_can_accept_dispute_claim()
         );
 
         $response = $this->client->acceptDisputeClaim(
-            'PP-D-4012',
+            'PP-D-27803',
             'Full refund to the customer.'
         );