Merge pull request #53 from ThePay/v2.x-4729-merge-v1.x

V2.x 4729 merge v1.x

doc/generate-payment-confirmation.md

@@ -0,0 +1,29 @@
+# Generating a confirmation PDF for paid payment
+
+If a merchant needs confirmation for someone that they received payment through our services.
+They can generate a confirmation PDF document for payment in ThePay administration.
+
+The generating confirmation can be also integrated into merchant application as describe example below.
+
+```php
+
+/** @var \ThePay\ApiClient\TheClient $thePayClient */
+
+$payment = $thePayClient->getPayment('exampleUID');
+// make detection if payment was really paid
+// and inform user that for not paid payment is confirmation unavailable,
+// because call method generatePaymentConfirmationPdf for unpaid payments will fail
+if($payment->wasPaid()) {
+
+    // we recommend asking user for language of receiver who confirmation wants, so he can understand it,
+    // if we not support given language, we return confirmation in english
+    $confirmationLanguageCode = 'cs';
+
+    $confirmationPdfContent = $thePayClient->generatePaymentConfirmationPdf('exampleUID', $confirmationLanguageCode);
+
+    header('Content-type:application/pdf');
+
+    echo $confirmationPdfContent;
+}
+
+```

doc/index.md

@@ -58,6 +58,8 @@
 
 [Get pay URLs for existing payments](get-pay-urls-for-existing-payment.md)
 
+[Generating a confirmation PDF for paid payment](generate-payment-confirmation.md)
+
 ## Methods
 
 ### getProjects

src/Service/ApiService.php

@@ -428,7 +428,31 @@ public function getPaymentUrlsForPayment(Identifier $uid, ?LanguageCode $languag
         return $paymentMethods;
     }
 
+    /**
+     * Method will generate PDF file as confirmation for paid payment
+     *
+     * @see https://dataapi21.docs.apiary.io/#reference/data-retrieval/payments/get-payment-confirmation
+     *
+     * @return string with binary content of PDF file
+     *
+     * @throws ApiException if payment is not paid yet
+     */
+    public function generatePaymentConfirmationPdf(Identifier $uid, LanguageCode $languageCode = null): string
+    {
+        $arguments = [];
+        if ($languageCode !== null) {
+            $arguments['language'] = $languageCode->getValue();
+        }
+
+        $url = $this->url(['payments', $uid->getValue(), 'generate_confirmation'], $arguments);
+        $response = $this->sendRequest(self::METHOD_GET, $url);
+
+        if ($response->getStatusCode() !== 200) {
+            throw $this->buildException($url, $response);
+        }
 
+        return $response->getBody()->getContents();
+    }
 
     /**
      * Build URL for API requests

src/Service/ApiServiceInterface.php

@@ -138,4 +138,15 @@ public function createPaymentRefund(Identifier $uid, Amount $amount, string $rea
      * @return array<PaymentMethodWithPayUrl>
      */
     public function getPaymentUrlsForPayment(Identifier $uid, LanguageCode $languageCode = null);
+
+    /**
+     * Method will generate PDF file as confirmation for paid payment
+     *
+     * @see https://dataapi21.docs.apiary.io/#reference/data-retrieval/payments/get-payment-confirmation
+     *
+     * @return string with binary content of PDF file
+     *
+     * @throws ApiException if payment is not paid yet
+     */
+    public function generatePaymentConfirmationPdf(Identifier $uid, LanguageCode $languageCode = null): string;
 }

src/TheClient.php

@@ -371,6 +371,27 @@ public function createPaymentRefund($paymentUid, $amount, $reason)
         $this->api->createPaymentRefund(new Identifier($paymentUid), new Amount($amount), $reason);
     }
 
+    /**
+     * Method will generate PDF file as confirmation for paid payment
+     *
+     * @see https://dataapi21.docs.apiary.io/#reference/data-retrieval/payments/get-payment-confirmation
+     *
+     * @param non-empty-string $paymentUid
+     * @param non-empty-string|null $languageCode
+     *
+     * @return string with binary content of PDF file
+     *
+     * @throws ApiException if payment is not paid yet
+     */
+    public function generatePaymentConfirmationPdf(string $paymentUid, string $languageCode = null): string
+    {
+        $this->validateUid($paymentUid);
+        return $this->api->generatePaymentConfirmationPdf(
+            new Identifier($paymentUid),
+            $languageCode !== null ? new LanguageCode($languageCode) : null
+        );
+    }
+
     /**
      * Returns <style> and <script> tags with styles and javascript code
      * @return string HTML code

tests/GeneratePaymentConfirmationTest.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ThePay\ApiClient\Tests;
+
+use GuzzleHttp\Psr7\HttpFactory;
+use GuzzleHttp\Psr7\Response;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestInterface;
+use ThePay\ApiClient\Service\ApiService;
+use ThePay\ApiClient\Service\SignatureService;
+use ThePay\ApiClient\TheClient;
+
+final class GeneratePaymentConfirmationTest extends BaseTestCase
+{
+    public function testSuccess(): void
+    {
+        $httpFactory = new HttpFactory();
+
+        $httpClient = $this->createMock(ClientInterface::class);
+        $httpClient->expects(self::once())->method('sendRequest')
+            ->willReturnCallback(function (RequestInterface $request): Response {
+                self::assertSame('GET', $request->getMethod());
+                self::assertSame(
+                    $this->config->getApiUrl() . 'projects/1/payments/testUID/generate_confirmation?language=cs&merchant_id=' . self::MERCHANT_ID,
+                    $request->getUri()->__toString()
+                );
+
+                return new Response(200, [], 'test pdf content');
+            })
+        ;
+
+        $theClient = new TheClient(
+            $this->config,
+            new ApiService(
+                $this->config,
+                $this->createMock(SignatureService::class),
+                $httpClient,
+                $httpFactory,
+                $httpFactory
+            )
+        );
+
+        $pdfContent = $theClient->generatePaymentConfirmationPdf('testUID', 'cs');
+
+        self::assertSame('test pdf content', $pdfContent);
+    }
+
+    public function testFailed(): void
+    {
+        $httpFactory = new HttpFactory();
+
+        $httpClient = $this->createMock(ClientInterface::class);
+        $httpClient->expects(self::once())->method('sendRequest')
+            ->willReturn(new Response(400));
+
+        $theClient = new TheClient(
+            $this->config,
+            new ApiService(
+                $this->config,
+                $this->createMock(SignatureService::class),
+                $httpClient,
+                $httpFactory,
+                $httpFactory
+            )
+        );
+
+        $this->expectException(\RuntimeException::class);
+
+        $theClient->generatePaymentConfirmationPdf('testUID', 'cs');
+    }
+}