Merge pull request #241 from mwarzybok-sumoheavy/feature/SP-553-master

SP-553 Payout Groups - PHP

src/BitPaySDK/Client.php

@@ -11,32 +11,31 @@
 use BitPaySDK\Exceptions\BillUpdateException;
 use BitPaySDK\Exceptions\BitPayException;
 use BitPaySDK\Exceptions\CurrencyQueryException;
-use BitPaySDK\Exceptions\InvoiceCreationException;
-use BitPaySDK\Exceptions\InvoiceUpdateException;
-use BitPaySDK\Exceptions\InvoiceQueryException;
 use BitPaySDK\Exceptions\InvoiceCancellationException;
+use BitPaySDK\Exceptions\InvoiceCreationException;
 use BitPaySDK\Exceptions\InvoicePaymentException;
+use BitPaySDK\Exceptions\InvoiceQueryException;
+use BitPaySDK\Exceptions\InvoiceUpdateException;
 use BitPaySDK\Exceptions\LedgerQueryException;
-use BitPaySDK\Exceptions\PayoutRecipientCreationException;
-use BitPaySDK\Exceptions\PayoutRecipientCancellationException;
-use BitPaySDK\Exceptions\PayoutRecipientQueryException;
-use BitPaySDK\Exceptions\PayoutRecipientUpdateException;
-use BitPaySDK\Exceptions\PayoutRecipientNotificationException;
+use BitPaySDK\Exceptions\PayoutBatchCancellationException;
+use BitPaySDK\Exceptions\PayoutBatchCreationException;
+use BitPaySDK\Exceptions\PayoutBatchNotificationException;
+use BitPaySDK\Exceptions\PayoutBatchQueryException;
 use BitPaySDK\Exceptions\PayoutCancellationException;
 use BitPaySDK\Exceptions\PayoutCreationException;
-use BitPaySDK\Exceptions\PayoutQueryException;
-use BitPaySDK\Exceptions\PayoutUpdateException;
 use BitPaySDK\Exceptions\PayoutNotificationException;
-use BitPaySDK\Exceptions\PayoutBatchCreationException;
-use BitPaySDK\Exceptions\PayoutBatchQueryException;
-use BitPaySDK\Exceptions\PayoutBatchCancellationException;
-use BitPaySDK\Exceptions\PayoutBatchNotificationException;
+use BitPaySDK\Exceptions\PayoutQueryException;
+use BitPaySDK\Exceptions\PayoutRecipientCancellationException;
+use BitPaySDK\Exceptions\PayoutRecipientCreationException;
+use BitPaySDK\Exceptions\PayoutRecipientNotificationException;
+use BitPaySDK\Exceptions\PayoutRecipientQueryException;
+use BitPaySDK\Exceptions\PayoutRecipientUpdateException;
 use BitPaySDK\Exceptions\RateQueryException;
-use BitPaySDK\Exceptions\RefundCreationException;
-use BitPaySDK\Exceptions\RefundUpdateException;
 use BitPaySDK\Exceptions\RefundCancellationException;
+use BitPaySDK\Exceptions\RefundCreationException;
 use BitPaySDK\Exceptions\RefundNotificationException;
 use BitPaySDK\Exceptions\RefundQueryException;
+use BitPaySDK\Exceptions\RefundUpdateException;
 use BitPaySDK\Exceptions\SettlementQueryException;
 use BitPaySDK\Exceptions\SubscriptionCreationException;
 use BitPaySDK\Exceptions\SubscriptionQueryException;
@@ -46,16 +45,18 @@
 use BitPaySDK\Model\Facade;
 use BitPaySDK\Model\Invoice\Invoice;
 use BitPaySDK\Model\Invoice\Refund;
-use BitPaySDK\Model\Wallet\Wallet;
 use BitPaySDK\Model\Ledger\Ledger;
 use BitPaySDK\Model\Payout\Payout;
 use BitPaySDK\Model\Payout\PayoutBatch;
+use BitPaySDK\Model\Payout\PayoutGroup;
+use BitPaySDK\Model\Payout\PayoutGroupFailed;
 use BitPaySDK\Model\Payout\PayoutRecipient;
 use BitPaySDK\Model\Payout\PayoutRecipients;
 use BitPaySDK\Model\Rate\Rate;
 use BitPaySDK\Model\Rate\Rates;
 use BitPaySDK\Model\Settlement\Settlement;
 use BitPaySDK\Model\Subscription\Subscription;
+use BitPaySDK\Model\Wallet\Wallet;
 use BitPaySDK\Util\JsonMapper\JsonMapper;
 use BitPaySDK\Util\RESTcli\RESTcli;
 use Exception;
@@ -1918,6 +1919,63 @@ public function cancelPayout(string $payoutId): bool
         return $result;
     }
 
+    /**
+     * Create Payout Group.
+     *
+     * @see <a href="https://developer.bitpay.com/reference/create-payout-group">Create Payout Group</>
+     *
+     * @param Payout[] $payouts
+     * @return PayoutGroup
+     * @throws PayoutCreationException
+     */
+    public function createPayoutGroup(array $payouts): PayoutGroup
+    {
+        $request = [];
+        try {
+            $request['token'] = $this->_tokenCache->getTokenByFacade(Facade::Payout);
+        } catch (Exception $e) {
+            throw new PayoutCreationException("Missing facade token");
+        }
+
+        try {
+            foreach ($payouts as $payout) {
+                $request['instructions'][] = $payout->toArray();
+            }
+            $responseJson = $this->_RESTcli->post("payouts/group", $request);
+
+            return $this->getPayoutGroupResponse($responseJson, 'created');
+        } catch (Exception $e) {
+            throw new PayoutCreationException("failed to serialize Payout object : " . $e->getMessage());
+        }
+    }
+
+    /**
+     * Cancel Payout group.
+     *
+     * @see <a href="https://developer.bitpay.com/reference/cancel-a-payout-group">Cancel a Payout Group</>
+     *
+     * @param string $groupId
+     * @return PayoutGroup
+     * @throws PayoutCancellationException
+     */
+    public function cancelPayoutGroup(string $groupId): PayoutGroup
+    {
+        $request = [];
+        try {
+            $request['token'] = $this->_tokenCache->getTokenByFacade(Facade::Payout);
+        } catch (Exception $e) {
+            throw new PayoutCancellationException("Missing facade token");
+        }
+
+        try {
+            $responseJson = $this->_RESTcli->delete("payouts/group/" . $groupId, $request);
+
+            return $this->getPayoutGroupResponse($responseJson, 'cancelled');
+        } catch (Exception $e) {
+            throw new PayoutCancellationException("failed to serialize Payout object : " . $e->getMessage());
+        }
+    }
+
     /**
      * Notify BitPay Payout.
      *
@@ -2718,4 +2776,26 @@ private function isSmsCodeRequired(bool $autoVerify, string $buyerSms, string $s
         return $autoVerify == false &&
             (!empty($buyerSms) && empty($smsCode)) || (!empty($smsCode) && empty($buyerSms));
     }
+
+    /**
+     * @param string $responseJson
+     * @param string $responseType completed/cancelled
+     * @return PayoutGroup
+     * @throws Exception
+     */
+    private function getPayoutGroupResponse(string $responseJson, string $responseType): PayoutGroup
+    {
+        $mapper = new JsonMapper();
+        $response = json_decode($responseJson, true, 512, JSON_THROW_ON_ERROR);
+
+        $payouts = $mapper->mapArray($response[$responseType], [], Payout::class);
+
+        $mapper->bIgnoreVisibility = true;
+
+        $payoutGroup = new PayoutGroup();
+        $payoutGroup->setPayouts($payouts);
+        $payoutGroup->setFailed($mapper->mapArray($response['failed'], [], PayoutGroupFailed::class));
+
+        return $payoutGroup;
+    }
 }

src/BitPaySDK/Env.php

@@ -9,7 +9,7 @@ interface Env
     const TestUrl               = "https://test.bitpay.com/";
     const ProdUrl               = "https://bitpay.com/";
     const BitpayApiVersion      = "2.0.0";
-    const BitpayPluginInfo      = "BitPay_PHP_Client_v7.3.1";
+    const BitpayPluginInfo      = "BitPay_PHP_Client_v7.4.0";
     const BitpayApiFrame        = "std";
     const BitpayApiFrameVersion = "1.0.0";
 }

src/BitPaySDK/Model/Payout/Payout.php

@@ -34,6 +34,7 @@ class Payout
     protected $_label = '';
     protected $_supportPhone = '';
     protected $_message = '';
+    protected bool $ignoreEmails = false;
     protected $_percentFee = 0.0;
     protected $_fee = 0.0;
     protected $_depositTotal = 0.0;
@@ -46,6 +47,7 @@ class Payout
     protected $_requestDate;
     protected $_exchangeRates;
     protected $_transactions;
+    protected ?string $_groupId = null;
 
     /**
      * Constructor, create a request Payout object.
@@ -764,6 +766,48 @@ public function setTransactions(array $transactions)
         $this->_transactions = $transactions;
     }
 
+    /**
+     * Gets boolean to prevent email updates on a specific payout.
+     * Defaults to false if not provided - you will receive emails unless specified to true.
+     *
+     * @return bool
+     */
+    public function isIgnoreEmails(): bool
+    {
+        return $this->ignoreEmails;
+    }
+
+    /**
+     * Sets boolean to prevent email updates on a specific payout.
+     * Defaults to false if not provided - you will receive emails unless specified to true.
+     *
+     * @param bool $ignoreEmails
+     */
+    public function setIgnoreEmails(bool $ignoreEmails): void
+    {
+        $this->ignoreEmails = $ignoreEmails;
+    }
+
+    /**
+     * Gets group id.
+     *
+     * @return string|null
+     */
+    public function getGroupId(): ?string
+    {
+        return $this->_groupId;
+    }
+
+    /**
+     * Sets group id.
+     *
+     * @param string|null $groupId
+     */
+    public function setGroupId(?string $groupId): void
+    {
+        $this->_groupId = $groupId;
+    }
+
     /**
      * Return Payout values as array.
      *
@@ -788,6 +832,8 @@ public function toArray()
             'label'             => $this->getLabel(),
             'supportPhone'      => $this->getSupportPhone(),
             'message'           => $this->getMessage(),
+            'groupId'           => $this->getGroupId(),
+            'ignoreEmails'      => $this->isIgnoreEmails(),
             'percentFee'        => $this->getPercentFee(),
             'fee'               => $this->getFee(),
             'depositTotal'      => $this->getDepositTotal(),

src/BitPaySDK/Model/Payout/PayoutGroup.php

@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * @author BitPay Integrations <[email protected]>
+ * @license http://www.opensource.org/licenses/mit-license.php MIT
+ */
+
+declare(strict_types=1);
+
+namespace BitPaySDK\Model\Payout;
+
+class PayoutGroup
+{
+    /**
+     * @var Payout[]
+     */
+    private array $payouts = [];
+
+    private array $failed = [];
+
+    /**
+     * @return Payout[]
+     */
+    public function getPayouts(): array
+    {
+        return $this->payouts;
+    }
+
+    /**
+     * @param Payout[] $payouts
+     */
+    public function setPayouts(array $payouts): void
+    {
+        $this->payouts = $payouts;
+    }
+
+    /**
+     * @return PayoutGroupFailed[]
+     */
+    public function getFailed(): array
+    {
+        return $this->failed;
+    }
+
+    /**
+     * @param PayoutGroupFailed[] $failed
+     */
+    public function setFailed(array $failed): void
+    {
+        $this->failed = $failed;
+    }
+}

src/BitPaySDK/Model/Payout/PayoutGroupFailed.php

@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * @author BitPay Integrations <[email protected]>
+ * @license http://www.opensource.org/licenses/mit-license.php MIT
+ */
+
+declare(strict_types=1);
+
+namespace BitPaySDK\Model\Payout;
+
+class PayoutGroupFailed
+{
+    private string $errMessage = '';
+    private ?string $payoutId;
+    private ?string $payee;
+
+    /**
+     * @return string
+     */
+    public function getErrorMessage(): string
+    {
+        return $this->errMessage;
+    }
+
+    /**
+     * @param string $errMessage
+     */
+    public function setErrorMessage(string $errMessage): void
+    {
+        $this->errMessage = $errMessage;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getPayoutId(): ?string
+    {
+        return $this->payoutId;
+    }
+
+    /**
+     * @param string|null $payoutId
+     */
+    public function setPayoutId(?string $payoutId): void
+    {
+        $this->payoutId = $payoutId;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getPayee(): ?string
+    {
+        return $this->payee;
+    }
+
+    /**
+     * @param string|null $payee
+     */
+    public function setPayee(?string $payee): void
+    {
+        $this->payee = $payee;
+    }
+}

src/BitPaySDK/Util/JsonMapper/JsonMapper.php

@@ -16,6 +16,7 @@
 
 use ReflectionClass;
 use ReflectionNamedType;
+use ReflectionProperty;
 
 /**
  * Automatically map JSON structures into objects.