Update readme

Author: damms005

README.md

@@ -29,14 +29,17 @@ Currently, this package supports the following online payment processors/handler
 -   [Interswitch](https://www.interswitchgroup.com)**
 -   [UnifiedPayments](https://unifiedpayments.com)**
 
-_key_:
-`** implementation not yet complete for specified payment handler. PRs welcomed if you cannot afford to wait 😉`
+> [!NOTE]
+> _key_:
+> ** for the indicated providers, a few features may be missing. PRs welcomed if you cannot afford the wait 😉
 
+> [!TIP]
 > Your preferred payment handler is not yet supported? Please consider [opening the appropriate issue type](https://github.com/damms005/laravel-multipay/issues/new?assignees=&labels=&template=addition-of-new-payment-handler.md&title=Addition+of+new+payment+handler+-+%5Bpayment+handler+name+here%5D).
 
-> Adding a new payment handler is straight-forward. Simply add a class that extends `Damms005\LaravelMultipay\Services\PaymentHandlers\BasePaymentHandler`  and implement `Damms005\LaravelMultipay\Contracts\PaymentHandlerInterface`
+> [!TIP]
+> Adding a new payment handler is straight-forward. Simply add a class that extends `Damms005\LaravelMultipay\Services\PaymentHandlers\BasePaymentHandler` and implement `Damms005\LaravelMultipay\Contracts\PaymentHandlerInterface`
 
-> **Note** <br />
+> [!NOTE]
 > Payment providers that you so register as described above are resolvable from the [Laravel Container](https://laravel.com/docs/9.x/container) to improve the flexibility of this package and improve DX.
 
 ## Installation
@@ -60,7 +63,7 @@ php artisan migrate
 ```
 
 ### Demo Repo
-I published an open source app that uses this payment package. It is also an excellent example of a Laravel app that uses [Laravel Vite](https://laravel.com/docs/9.x/vite#main-content) and leverages on [Laravel Echo](https://laravel.com/docs/9.x/broadcasting#client-side-installation) to provide realtime experience via public and private channels using [Laravel Websocket](https://beyondco.de/docs/laravel-websockets), powered by [Livewire](https://laravel-livewire.com/docs). The app is called [NFT Marketplace. Click here to check it out ✌🏼](https://github.com/damms005/nft-marketplace)
+I [published an open source app](https://github.com/damms005/nft-marketplace) that uses this payment package. It is also an excellent example of a Laravel app that uses [Laravel Vite](https://laravel.com/docs/9.x/vite#main-content) and leverages on [Laravel Echo](https://laravel.com/docs/9.x/broadcasting#client-side-installation) to provide realtime experience via public and private channels using [Laravel Websocket](https://beyondco.de/docs/laravel-websockets), powered by [Livewire](https://laravel-livewire.com/docs).
 
 ### Test drive 🚀
 
@@ -90,14 +93,14 @@ FLW_SECRET_HASH='My_lovelysite123'
 -   Paystack: Paystack requires a secret key. Go to [the Paystack dashboard](https://dashboard.paystack.co/#/settings/developer) to obtain one, and use it to set the following variable:
 
 ```
-PAYSTACK_SECRET_KEY=FLWPUBK-xxxxxxxxxxxxxxxxxxxxx-X
+PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
 ```
 
 -   Remita: Ensure to set the following environment variables:
 
 ```
-REMITA_MERCHANT_ID=xxxxxxxxxxxxxxxxxxxxx-X
-REMITA_API_KEY=xxxxxxxxxxxxxxxxxxxxx-X
+REMITA_MERCHANT_ID=xxxxxxxxxxxxxxxxxxxxx
+REMITA_API_KEY=xxxxxxxxxxxxxxxxxxxxx
 ```
 
 > For most of the above environment variables, you should rather use the (published) config file to set the corresponding values.
@@ -126,17 +129,26 @@ Upon user confirmation of transaction, user is redirected to the appropriate pay
 When user is done with the transaction on the payment handler's end (either successfully paid, or declined transaction), user is redirected
 back to `/payment/completed` (`route('payment.finished.callback_url')` provided by this package) .
 
-> [!NOTE]
-> If the `Payment` has [`metadata`](#step-1) (supplied with the payment initiation request), with a key named `completion_url`, the user will be redirected to that URL instead on successful payment, with the transaction reference included as `transaction_reference` in the URL query string.
+### Metadata Usage
 
-> [!NOTE]
-> If the `Payment` has [`metadata`](#step-1) (supplied with the payment initiation request), and it contains a key named `payment_processor`, it will be used to dynamically set the payment handler for that particular transaction. Valid value is any of [the providers listed above](#currently-supported-payment-handlers)
+In the payment initiation request in [Step 1](#step-1), you can provide a `metadata` field. This field is stored in the `metadata` column of the `payments` table, and available as `AsArrayObject::class` property of the `Payment` model and it provides powerful customization options for individual payments.
 
-> [!NOTE]
-> If the `Payment` has [`metadata`](#step-1) (supplied with the payment initiation request), with a key named `split_code`, for Paystack transactions, it will be processed as [Paystack Multi-split Transaction](https://paystack.com/docs/payments/multi-split-payments).
+The metadata should be a valid JSON string containing key-value pairs that modify payment behavior.
 
-> [!NOTE]
-> If there are additional steps you want to take upon successful payment, listen for `SuccessfulLaravelMultipayPaymentEvent`. It will be fired whenever a successful payment occurs, with its corresponding `Payment` model.
+#### Available Metadata Keys
+
+**`completion_url`**
+- After successful payment, the user will be redirected to the URL specified by this key instead of the default payment completion page
+- When user is redirected to the specified URL, the transaction reference will be included as `transaction_reference` in the URL query string
+
+**`payment_processor`**
+- Use this key to dynamically set the payment handler for the specific transaction
+- Valid values are any of [the providers listed above](#currently-supported-payment-handlers)
+- This will override the default payment processor configuration
+
+**`split_code`** (Paystack only)
+- When using Paystack, you can use this key to specify a split code to process the transaction as a [Paystack Multi-split Transaction](https://paystack.com/docs/payments/multi-split-payments)
+- This feature is only available when using Paystack as the payment handler
 
 ## Payment Conflict Resolution (PCR)
 
@@ -146,16 +158,24 @@ If for any reason, your user/customer claims that the payment they made was succ
 /**
 * @var bool //true if payment was successful, false otherwise
 **/
-$outcome = LaravelMultipay::reQueryUnsuccessfulPayment( $payment )
+$outcome = LaravelMultipay::reQueryUnsuccessfulPayment($payment)
 ```
 
 The payment will be re-resolved and the payment will be updated in the database. If the payment is successful, the `SuccessfulLaravelMultipayPaymentEvent` event will be fired, so you can run any domain/application-specific procedures.
 
-## Payment Notifications (WebHooks)
-Some payment handlers provide a means for sending details of successful notifications. Usually, you will need to provide the payment handler with a URL to which the details of such notification will be sent. Should you need this feature, the notification URL is handled by `route('payment.external-webhook-endpoint' provided by this package)`.
+## WebHooks Payment Notifications (optional)
+One of the benefits of this package is to remove the need for you to have to deal with payment webhooks. Depending on your needs, the event handling may suffice for your use case.
+
+If you need webhook notifications from payment providers, use the webhook endpoint provided by this package: `route('payment.external-webhook-endpoint')`.
 
 > If you use this payment notification URL feature, ensure that in the handler for `SuccessfulLaravelMultipayPaymentEvent`, you have not previously handled the event for that same payment.
 
+## Events
+
+### SuccessfulLaravelMultipayPaymentEvent
+
+If there are additional steps you want to take upon successful payment, listen for `SuccessfulLaravelMultipayPaymentEvent`. This event will be fired whenever a successful payment occurs, with its corresponding `Payment` model.
+
 ## Testing
 
 ```bash