Add support for PaymentOrderCollection and PaymentOrder (#55)

* Initial commit

* Apply suggestions from code review

---------

Co-authored-by: Mior Muhammad Zaki <[email protected]>

README.md

@@ -36,6 +36,13 @@ PHP framework agnostic library for working with BillPlz API v3 and beyond...
     - [Banking](#banking)
         + [Registration Check by Bank Account](#registration-check-by-bank-account)
         + [Get FPX Banks List](#get-fpx-banks-list)
+    - [Payment Order Collection](#payment-order-collection)
+        + [Create a Payment Order Collection](#create-a-payment-order-collection)
+        + [Get existing Payment Order Collection](#get-a-payment-order-collection)
+    - [Payment Order](#payment-order)
+        + [Create a Payment Order](#create-payment-order)
+        + [Get existing Payment Order](#get-a-payment-order)
+        + [Get Payment Order Limit](#get-a-payment-order-limit)
 * [Handling Response](#handling-response)
     - [Getting the Response](#getting-the-response)
     - [Checking the Response HTTP Status](#checking-the-response-http-status)
@@ -887,6 +894,84 @@ return [
 
 > **Note**: You will hit 401, Invalid access error if you have not enabled Bank Direct by Billplz. Contact Billplz for information.
 
+<a name="payment-order-collection"></a>
+
+## Payment Order Collection
+Create an instance of Payment Order Collection:
+
+```php
+$paymentOrderCollection = $billplz->paymentOrderCollection();
+```
+
+<a name="create-a-payment-order-collection"></a>
+
+### Create Payment Order Collection
+```php
+$response = $paymentOrderCollection->create(
+    'My First API Payment Order Collection'
+);
+
+var_dump($response->toArray());
+```
+
+<a name="get-a-payment-order-collection"></a>
+
+### Get Payment Order Collection
+```php
+$response = $paymentOrderCollection->get(
+    '8f4e331f-ac71-435e-a870-72fe520b4563'
+);
+
+var_dump($response->toArray());
+```
+<a name="payment-order"></a>
+
+## Payment Order
+Create an instance of Payment Order:
+
+```php
+$paymentOrder = $billplz->paymentOrder();
+```
+
+<a name="create-a-payment-order"></a>
+
+### Create Payment Order
+```php
+$response = $paymentOrder->create(
+    '8f4e331f-ac71-435e-a870-72fe520b4563',
+    'MBBEMYKL',
+    '543478924652',
+    '820808062202',
+    'Michael Yap',
+    'Maecenas eu placerat ante.',
+    2000
+);
+
+var_dump($response->toArray());
+```
+
+> **Note**: You will hit 422, You do not have enough payments error if you are trying to make a payment with total that are exceeding your Payment Order Limit.
+
+<a name="get-a-payment-order"></a>
+
+### Get Payment Order
+```php
+$response = $paymentOrder->get(
+    'cc92738f-dfda-4969-91dc-22a44afc7e26'
+);
+
+var_dump($response->toArray());
+```
+
+<a name="get-a-payment-order-limit"></a>
+
+### Get Payment Order Limit
+```php
+$response = $paymentOrder->limit();
+
+var_dump($response->toArray());
+```
+
 ## Handling Response
 
 Every request made to Billplz would return `\Laravie\Codex\Response` which can fallback to `\Psr\Http\Message\ResponseInterface` which would allow developer to further inspect the response.

examples/v5/creating-payment-order-collection.php

@@ -0,0 +1,17 @@
+<?php
+require 'vendor/autoload.php';
+
+$api = '';
+$signatureKey = '';
+$paymentOrderCollectionId = '';
+
+$billplz = Billplz\Client::make($api, $signatureKey)->useSandbox();
+
+$response = $billplz->paymentOrderCollection()->create(
+    "test",
+    [
+        'callback_url' => 'http://example.com/webhook',
+    ],
+);
+
+var_dump($response->getStatusCode(), $response->toArray());

examples/v5/creating-payment-order.php

@@ -0,0 +1,20 @@
+<?php
+require 'vendor/autoload.php';
+
+$api = '';
+$signatureKey = '';
+$paymentOrderCollectionId = '';
+
+$billplz = Billplz\Client::make($api, $signatureKey)->useSandbox();
+
+$response = $billplz->paymentOrder()->create(
+    $paymentOrderCollectionId,
+    "MBBEMYKL", 
+    "123456789012",
+    "123456789012",
+    "Ameer Shah",
+    "Payment Order",
+    1000,
+);
+
+var_dump($response->getStatusCode(), $response->toArray());

examples/v5/getting-payment-order-collection.php

@@ -0,0 +1,14 @@
+<?php
+require 'vendor/autoload.php';
+
+$api = '';
+$signatureKey = '';
+$paymentOrderCollectionId = '';
+
+$billplz = Billplz\Client::make($api, $signatureKey)->useSandbox();
+
+$response = $billplz->paymentOrderCollection()->get(
+    $paymentOrderCollectionId
+);
+
+var_dump($response->getStatusCode(), $response->toArray());

examples/v5/getting-payment-order-limit.php

@@ -0,0 +1,11 @@
+<?php
+require 'vendor/autoload.php';
+
+$api = '';
+$signatureKey = '';
+
+$billplz = Billplz\Client::make($api, $signatureKey)->useSandbox();
+
+$response = $billplz->paymentOrder()->limit();
+
+var_dump($response->getStatusCode(), $response->toArray());

examples/v5/getting-payment-order.php

@@ -0,0 +1,14 @@
+<?php
+require 'vendor/autoload.php';
+
+$api = '';
+$signatureKey = '';
+$paymentOrderId = '';
+
+$billplz = Billplz\Client::make($api, $signatureKey)->useSandbox();
+
+$response = $billplz->paymentOrder()->get(
+    $paymentOrderId
+);
+
+var_dump($response->getStatusCode(), $response->toArray());

src/Checksum.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Billplz;
+
+class Checksum
+{
+    //V5 API introduces new security measures. 
+    public static function create(string $key, array $attributes): string
+    {
+        return hash_hmac('sha512', implode('', $attributes), (string) $key);
+    }
+}

src/Client.php

@@ -29,6 +29,7 @@ class Client extends \Laravie\Codex\Client
     protected $supportedVersions = [
         'v3' => 'Three',
         'v4' => 'Four',
+        'v5' => 'Five',
     ];
 
     /**
@@ -162,6 +163,26 @@ final public function payout(): Contracts\Payout
         return $this->uses('Payout', 'v4');
     }
 
+        /**
+     * Get payout instruction resource.
+     *
+     * @return \Billplz\Contracts\PaymentOrder
+     */
+    final public function paymentOrder(): Contracts\PaymentOrder
+    {
+        return $this->uses('PaymentOrder', 'v5');
+    }
+
+    /**
+     * Get payout instruction collection resource.
+     *
+     * @return \Billplz\Contracts\PaymentOrderCollection
+     */
+    final public function paymentOrderCollection(): Contracts\PaymentOrderCollection
+    {
+        return $this->uses('PaymentOrderCollection', 'v5');
+    }
+
     /**
      * Get bank resource.
      *

src/Contracts/PaymentOrder.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Billplz\Contracts;
+
+use Laravie\Codex\Contracts\Request;
+use Laravie\Codex\Contracts\Response;
+
+interface PaymentOrder extends Request
+{
+    /**
+     * Create a Payment Order
+     *
+     * @param  int  $total
+     * @param  array<string, mixed>  $optional
+     */
+    public function create(
+        string $paymentOrderCollectionId,
+        string $bankCode,
+        string $bankAccountNumber,
+        string $identityNumber,
+        string $name,
+        string $description,
+        $total,
+        array $optional = []
+    ): Response;
+
+    /**
+     * Get a Payment Order
+     */
+    public function get(
+        string $paymentOrderId,
+    ): Response;
+
+    /**
+     * Get a Payment Order Limit
+     */
+    public function limit(): Response;
+}

src/Contracts/PaymentOrderCollection.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Billplz\Contracts;
+
+use Laravie\Codex\Contracts\Request;
+use Laravie\Codex\Contracts\Response;
+
+interface PaymentOrderCollection extends Request
+{
+    /**
+     * Create a Payment Order Collection
+     *
+     * @param  \Money\Money|\Duit\MYR|int  $amount
+     * @param  array<string, mixed>  $optional
+     */
+    public function create(
+        string $title,
+        array $optional = []
+    ): Response;
+
+    /**
+     * Get a Payment Order Collection
+     */
+    public function get(string $paymentOrderCollectionId): Response;
+}

src/Five/PaymentOrder.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Billplz\Five;
+
+use Billplz\Checksum;
+use Billplz\Contracts\PaymentOrder as Contract;
+use Billplz\Request;
+use Laravie\Codex\Contracts\Response;
+
+class PaymentOrder extends Request implements Contract
+{
+    /**
+     * Version namespace.
+     *
+     * @var string
+     */
+    protected $version = 'v5';
+
+    /**
+     * Create a Payment Order
+     *
+     * @param  int  $total
+     */
+    public function create(
+        string $paymentOrderCollectionId,
+        string $bankCode,
+        string $bankAccountNumber,
+        string $identityNumber,
+        string $name,
+        string $description,
+        $total,
+        array $optional = []
+    ): Response {
+        $epoch = time();
+
+        $body['payment_order_collection_id'] = $paymentOrderCollectionId;
+        $body['bank_code'] = $bankCode;
+        $body['bank_account_number'] = $bankAccountNumber;
+        $body['identity_number'] = $identityNumber;
+        $body['name'] = $name;
+        $body['description'] = $description;
+        $body['total'] = $total;
+        $body['epoch'] = $epoch;
+        $body['checksum'] = Checksum::create($this->client->getSignatureKey(), [
+            $paymentOrderCollectionId,
+            $bankAccountNumber,
+            $total,
+            $epoch
+        ]);
+
+        $body = array_merge($body, $optional);
+
+        return $this->send('POST', 'payment_orders', [], $body);
+    }
+
+    /**
+     * Get a Payment Order
+     */
+    public function get(
+        string $paymentOrderId,
+    ): Response {
+        $epoch = time();
+
+        $body['payment_order_id'] = $paymentOrderId;
+        $body['epoch'] = $epoch;
+        $body['checksum'] = Checksum::create($this->client->getSignatureKey(), [
+            $paymentOrderId,
+            $epoch
+        ]);
+
+        return $this->send('GET', "payment_orders/{$paymentOrderId}", [], $body);
+    }
+
+    /**
+     * Get a Payment Order Limit
+     */
+    public function limit(
+    ): Response {
+        $epoch = time();
+
+        $body['epoch'] = $epoch;
+        $body['checksum'] = Checksum::create($this->client->getSignatureKey(), [
+            $epoch
+        ]);
+
+        return $this->send('GET', "payment_order_limit", [], $body);
+    }
+}