Merge pull request #46 from alexstewartja/6.0.x

+ Release 6.0.0
  - Updated BitPay client dependency to v7.1.0
  - Bumped minimum PHP version to 7.4
  - Implemented the invoice webhook/notification resend action
  - Isolated implementation of the `Refunds` resource

Author: alexstewartja

.github/workflows/php.yml

@@ -7,7 +7,7 @@ on:
     branches: [ master ]
 
 jobs:
-  build_php_73:
+  build_php_74:
 
     runs-on: ubuntu-latest
 
@@ -17,7 +17,7 @@ jobs:
     - name: Setup PHP with PECL extension
       uses: shivammathur/setup-php@v2
       with:
-        php-version: '7.3'
+        php-version: '7.4'
 
     - name: Validate composer.json and composer.lock
       run: composer validate --strict
@@ -66,3 +66,33 @@ jobs:
 
     - name: Run test suite
       run: composer run-script test
+
+  build_php_81:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Setup PHP with PECL extension
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.1'
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate --strict
+
+    - name: Cache Composer packages
+      id: composer-cache
+      uses: actions/cache@v2
+      with:
+        path: vendor
+        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-php-
+
+    - name: Install dependencies
+      run: composer install --prefer-dist --no-progress
+
+    - name: Run test suite
+      run: composer run-script test

CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to `vrajroham/laravel-bitpay` will be documented in this file
 
 ---
+
+#### v6.0.0 - 2022-12-18
+
+* Updated BitPay client dependency to v7.1.0
+* Bumped minimum PHP version to 7.4
+* Implemented the invoice webhook/notification resend action
+* Isolated implementation of the `Refunds` resource
+
+#### v5.3.0 - 2022-06-20
+
+* Fixed issues, updated deps & corrected typos by @alexstewartja in https://github.com/vrajroham/laravel-bitpay/pull/42
+
 #### v5.0.1 - 2021-12-18
 
 * Make newLine() calls compatible with Laravel versions below 8 by @Ririshi in https://github.com/vrajroham/laravel-bitpay/pull/41

README.md

@@ -10,7 +10,7 @@
 LaravelBitPay enables you and your business to transact in Bitcoin, Bitcoin Cash and 10+ other BitPay-supported
 cryptocurrencies within your Laravel application.
 
-> Requires PHP 7.3+
+> Requires PHP 7.4+
 
 ## :warning: Migration From v4 :warning:
 
@@ -19,6 +19,7 @@ If upgrading from v4, please follow [MIGRATION.md](./MIGRATION.md)
 ## Supported Resources
 
 - :white_check_mark: [Invoices](https://bitpay.com/api/#rest-api-resources-invoices)
+- :white_check_mark: [Refunds](https://bitpay.com/api/#rest-api-resources-refunds)
 - :white_check_mark: [Bills](https://bitpay.com/api/#rest-api-resources-bills)
 - :white_check_mark: [Subscriptions](https://bitpay.com/api/#rest-api-resources-subscriptions)
 - :white_check_mark: [Settlements](https://bitpay.com/api/#rest-api-resources-settlements)
@@ -43,6 +44,7 @@ If upgrading from v4, please follow [MIGRATION.md](./MIGRATION.md)
         + [Create an invoice](#create-an-invoice)
         + [Retrieve an existing invoice](#retrieve-an-existing-invoice)
         + [Retrieve a list of existing invoices](#retrieve-a-list-of-existing-invoices)
+    + [Refunds](#refunds)
         + [Refund an invoice](#refund-an-invoice)
         + [Retrieve a refund request](#retrieve-a-refund-request)
         + [Retrieve all refund requests on an invoice](#retrieve-all-refund-requests-on-an-invoice)
@@ -141,8 +143,10 @@ php artisan laravel-bitpay:createkeypair
 
 <center><img src="https://i.ibb.co/JvP3bQb/create-key-pair-command.png" title="Create Key-Pair Command" alt="Create Key-Pair Command"/></center>
 
-> :information_source: By default, the command will use the (valid) existing private key located at `BITPAY_PRIVATE_KEY_PATH`.
-> You may specify the `--fresh` or `-f` option to explicitly generate a fresh private key, from which tokens are derived.
+> :information_source: By default, the command will use the (valid) existing private key located
+> at `BITPAY_PRIVATE_KEY_PATH`.
+> You may specify the `--fresh` or `-f` option to explicitly generate a fresh private key, from which tokens are
+> derived.
 
 After successful API Token generation, you will need to approve it by visiting the provided link.
 
@@ -173,7 +177,8 @@ Route::bitPayWebhook(); // https://example.com/laravel-bitpay/webhook
 Route::bitPayWebhook('receive/webhooks/here'); // https://example.com/receive/webhooks/here
 ```
 
-> :information_source: To retrieve your newly created webhook route anywhere in your application, use: `route('laravel-bitpay.webhook.capture')`
+> :information_source: To retrieve your newly created webhook route anywhere in your application,
+> use: `route('laravel-bitpay.webhook.capture')`
 
 LaravelBitPay also offers the convenience of auto-populating your configured webhook url on applicable resources.
 Specifically when:
@@ -345,6 +350,19 @@ $endDate = date('Y-m-d');
 $invoices = LaravelBitpay::getInvoices($startDate, $endDate);
 ```
 
+#### Request an Invoice webhook to be resent
+
+```php
+// True if the webhook has been resent for the current invoice status, false otherwise.
+$webhookResent = LaravelBitpay::requestInvoiceWebhook('invoiceId_sGsdVsgheF');
+```
+
+### Refunds
+
+Refund requests are full or partial refunds associated to an invoice. Fully paid invoices can be refunded via the
+merchant's authorization to issue a refund, while underpaid and overpaid invoices are automatically executed by BitPay
+to issue the underpayment or overpayment amount to the customer.
+
 #### Refund an invoice
 
 The item Jane purchased was dead on arrival. Give back the lady her crypto:
@@ -921,7 +939,8 @@ Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
 
 ## Security
 
-If you discover any security related issues, please email [email protected] or [email protected] instead of using the issue tracker.
+If you discover any security related issues, please email [email protected] or [email protected] instead of
+using the issue tracker.
 
 ## Credits
 

composer.json

@@ -23,9 +23,9 @@
         }
     ],
     "require": {
-        "php": "^7.3 || ^8.0",
+        "php": "^7.4 || ^8.0 || ^8.1",
         "ext-json": "*",
-        "bitpay/sdk": "~6.0.2"
+        "bitpay/sdk": "~7.1.0"
     },
     "require-dev": {
         "phpunit/phpunit": ">=9.5"

src/Actions/ManageInvoices.php

@@ -3,10 +3,8 @@
 namespace Vrajroham\LaravelBitpay\Actions;
 
 use BitPaySDK\Exceptions\BitPayException;
-use BitPaySDK\Exceptions\RefundCancellationException;
 use BitPaySDK\Model\Invoice\Buyer;
 use BitPaySDK\Model\Invoice\Invoice;
-use BitPaySDK\Model\Invoice\Refund;
 use Vrajroham\LaravelBitpay\Constants\WebhookAutoPopulate;
 
 
@@ -103,103 +101,17 @@ public static function getInvoices(
     }
 
     /**
-     * Get BitPay refund instance.
+     * Request the last BitPay Invoice webhook to be resent.
      *
-     * @return Refund
-     */
-    public static function Refund(): Refund
-    {
-        return new Refund();
-    }
-
-    /**
-     * Create a BitPay refund.
+     * @link https://bitpay.com/api/#rest-api-resources-invoices-request-a-webhook-to-be-resent
      *
-     * @link https://bitpay.com/api/#rest-api-resources-invoices-refund-an-invoice
+     * @param string $invoiceId The id of the invoice for which you want the last webhook to be resent.
      *
-     * @param $invoice          Invoice A BitPay invoice object for which a refund request should be made.  Must have
-     *                          been obtained using the merchant facade.
-     * @param $refundEmail      string The email of the buyer to which the refund email will be sent
-     * @param $amount           float The amount of money to refund. If zero then a request for 100% of the invoice
-     *                          value is created.
-     * @param $currency         string The three digit currency code specifying the exchange rate to use when
-     *                          calculating the refund bitcoin amount. If this value is "BTC" then no exchange rate
-     *                          calculation is performed.
-     *
-     * @return bool True if the refund was successfully created, false otherwise.
-     * @throws BitPayException BitPayException class
+     * @return bool True if the webhook has been resent for the current invoice status, false otherwise.
+     * @throws  \BitPaySDK\Exceptions\BitPayException BitPayException class
      */
-    public static function createRefund(
-        Invoice $invoice,
-        string  $refundEmail,
-        float   $amount,
-        string  $currency
-    ): bool {
-        return (new self())->client->createRefund($invoice, $refundEmail, $amount, $currency);
-    }
-
-    /**
-     * Retrieve all refund requests on a BitPay invoice.
-     *
-     * @link https://bitpay.com/api/#rest-api-resources-invoices-retrieve-all-refund-requests-on-an-invoice
-     *
-     * @param $invoice  Invoice The BitPay invoice having the associated refunds.
-     *
-     * @return Refund[] An array of BitPay refund object with the associated Refund object updated.
-     * @throws BitPayException BitPayException class
-     */
-    public static function getRefunds(Invoice $invoice): array
+    public static function requestInvoiceWebhook(string $invoiceId): bool
     {
-        return (new self())->client->getRefunds($invoice);
+        return (new self())->client->requestInvoiceNotification($invoiceId);
     }
-
-    /**
-     * Retrieve a previously made refund request on a BitPay invoice.
-     *
-     * @link https://bitpay.com/api/#rest-api-resources-invoices-retrieve-a-refund-request
-     *
-     * @param $invoice  Invoice The BitPay invoice having the associated refund.
-     * @param $refundId string The refund id for the refund to be updated with new status.
-     *
-     * @return Refund A BitPay refund object with the associated Refund object updated.
-     * @throws BitPayException BitPayException class
-     */
-    public static function getRefund(Invoice $invoice, string $refundId): Refund
-    {
-        return (new self())->client->getRefund($invoice, $refundId);
-    }
-
-    /**
-     * Cancel a previously submitted refund request on a BitPay invoice.
-     *
-     * @link https://bitpay.com/api/#rest-api-resources-invoices-cancel-a-refund-request
-     *
-     * @param $invoiceId string The refund id for the refund to be canceled.
-     * @param $refund    Refund The BitPay invoice having the associated refund to be canceled.
-     *                   Must have been obtained using the merchant facade.
-     *
-     * @return bool True if the refund was successfully canceled, false otherwise.
-     * @throws RefundCancellationException RefundCancellationException class
-     */
-    public static function cancelRefund(string $invoiceId, Refund $refund): bool
-    {
-        return (new self())->client->cancelRefund($invoiceId, $refund);
-    }
-
-    // TODO: Awaiting upstream merge: https://github.com/bitpay/php-bitpay-client-v2/pull/69
-//    /**
-//     * Request the last BitPay Invoice webhook to be resent.
-//     *
-//     * @link https://bitpay.com/api/#rest-api-resources-invoices-request-a-webhook-to-be-resent
-//     *
-//     * @param string $invoiceId The id of the invoice for which you want the last webhook to be resent.
-//     * @param string $invoiceToken The resource token for the `invoiceId` you want the webhook to be resent.
-//     *
-//     * @return bool True if the webhook has been resent for the current invoice status, false otherwise.
-//     * @throws  \BitPaySDK\Exceptions\BitPayException BitPayException class
-//     */
-//    public static function requestInvoiceWebhook(string $invoiceId, string $invoiceToken): bool
-//    {
-//        return (new self())->client->requestInvoiceWebhook($invoiceId, $invoiceToken);
-//    }
 }

src/Actions/ManageRefunds.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Vrajroham\LaravelBitpay\Actions;
+
+use BitPaySDK\Exceptions\BitPayException;
+use BitPaySDK\Exceptions\RefundCancellationException;
+use BitPaySDK\Model\Invoice\Invoice;
+use BitPaySDK\Model\Invoice\Refund;
+
+
+trait ManageRefunds
+{
+
+    /**
+     * Get BitPay refund instance.
+     *
+     * @return Refund
+     */
+    public static function Refund(): Refund
+    {
+        return new Refund();
+    }
+
+    /**
+     * Create a BitPay refund.
+     *
+     * @link https://bitpay.com/api/#rest-api-resources-invoices-refund-an-invoice
+     *
+     * @param $invoice          Invoice A BitPay invoice object for which a refund request should be made.  Must have
+     *                          been obtained using the merchant facade.
+     * @param $refundEmail      string The email of the buyer to which the refund email will be sent
+     * @param $amount           float The amount of money to refund. If zero then a request for 100% of the invoice
+     *                          value is created.
+     * @param $currency         string The three digit currency code specifying the exchange rate to use when
+     *                          calculating the refund bitcoin amount. If this value is "BTC" then no exchange rate
+     *                          calculation is performed.
+     *
+     * @return bool True if the refund was successfully created, false otherwise.
+     * @throws BitPayException BitPayException class
+     */
+    public static function createRefund(
+        Invoice $invoice,
+        string  $refundEmail,
+        float   $amount,
+        string  $currency
+    ): bool {
+        return (new self())->client->createRefund($invoice, $refundEmail, $amount, $currency);
+    }
+
+    /**
+     * Retrieve all refund requests on a BitPay invoice.
+     *
+     * @link https://bitpay.com/api/#rest-api-resources-invoices-retrieve-all-refund-requests-on-an-invoice
+     *
+     * @param $invoice  Invoice The BitPay invoice having the associated refunds.
+     *
+     * @return Refund[] An array of BitPay refund object with the associated Refund object updated.
+     * @throws BitPayException BitPayException class
+     */
+    public static function getRefunds(Invoice $invoice): array
+    {
+        return (new self())->client->getRefunds($invoice);
+    }
+
+    /**
+     * Retrieve a previously made refund request on a BitPay invoice.
+     *
+     * @link https://bitpay.com/api/#rest-api-resources-invoices-retrieve-a-refund-request
+     *
+     * @param $invoice  Invoice The BitPay invoice having the associated refund.
+     * @param $refundId string The refund id for the refund to be updated with new status.
+     *
+     * @return Refund A BitPay refund object with the associated Refund object updated.
+     * @throws BitPayException BitPayException class
+     */
+    public static function getRefund(Invoice $invoice, string $refundId): Refund
+    {
+        return (new self())->client->getRefund($invoice, $refundId);
+    }
+
+    /**
+     * Cancel a previously submitted refund request on a BitPay invoice.
+     *
+     * @link https://bitpay.com/api/#rest-api-resources-invoices-cancel-a-refund-request
+     *
+     * @param $invoiceId string The refund id for the refund to be canceled.
+     * @param $refund    Refund The BitPay invoice having the associated refund to be canceled.
+     *                   Must have been obtained using the merchant facade.
+     *
+     * @return bool True if the refund was successfully canceled, false otherwise.
+     * @throws RefundCancellationException RefundCancellationException class
+     */
+    public static function cancelRefund(string $invoiceId, Refund $refund): bool
+    {
+        return (new self())->client->cancelRefund($invoiceId, $refund);
+    }
+}

src/LaravelBitpay.php

@@ -10,6 +10,7 @@
 use Vrajroham\LaravelBitpay\Actions\ManageLedgers;
 use Vrajroham\LaravelBitpay\Actions\ManagePayouts;
 use Vrajroham\LaravelBitpay\Actions\ManageRecipients;
+use Vrajroham\LaravelBitpay\Actions\ManageRefunds;
 use Vrajroham\LaravelBitpay\Actions\ManageSettlements;
 use Vrajroham\LaravelBitpay\Actions\ManageSubscriptions;
 use Vrajroham\LaravelBitpay\Traits\MakesHttpRequests;
@@ -25,6 +26,7 @@ class LaravelBitpay
     use ManageLedgers;
     use ManagePayouts;
     use ManageRecipients;
+    use ManageRefunds;
     use ManageSettlements;
     use ManageSubscriptions;