Merge pull request #99 from ThePay/6296-refunds-return-authorization-subscription

Documentation 3.0 - Refunds, customer return, saving authorization, s…

Author: jirkadajc

doc/refund-payment.md

@@ -1,30 +1,45 @@
-# Refund payment
+# Refund Payment
 
-Most paid payments can be automatically refund to customer, call createPaymentRefund($uid, $amount, $reason).
+Most paid payments can be automatically refunded back to the customer.
+To create a refund, call `createPaymentRefund($uid, $amount, $reason)`.
 
-Detect if payment is refundable by call getPaymentRefund($uid)->getAvailableAmount() !== 0.
+You can check whether a payment is refundable by inspecting the available refundable amount:
 
-A refunded amount can be smaller than availableAmount for payment but cannot be bigger,
-for one payment can be created multiple refunds.
+```php
+$available = $thePayClient->getPaymentRefund($uid)->getAvailableAmount();
+$isRefundable = ($available !== 0);
+```
+
+A refund can be **partial** or **full**:
+- You may refund less than the available amount
+- You may not refund more than the available amount
+- You may create multiple refunds for one payment, as long as sufficient refundable amount remains
 
-Basic load information about payment refund,
+## Loading Refund Information
 
-after client call can be rendered information about refund how you like,
-or refund form can be rendered if some amount for refund is available.
+You can load the refund information for a payment and render it however you prefer—either as details for the user or to display a refund form when a refund is possible.
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 $paymentRefundInfo = $thePayClient->getPaymentRefund('uid-454548');
 ```
 
-Recommended refund action processing,
+## Recommended Refund Processing Flow
 
-always check if refunded amount is available to avoid 403 api exception
-and if not available render some message for user
+Before creating a refund, always verify that the requested refund amount is still available.
+This prevents a `403` API exception and allows you to show a meaningful message to the user.
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
-if($thePayClient->getPaymentRefund('uid-454548')->getAvailableAmount() >= 10000) {
-    $thePayClient->createPaymentRefund('uid-454548', 10000, 'Partial refund because some items was delivered broken');
+$refundInfo = $thePayClient->getPaymentRefund('uid-454548');
+
+if ($refundInfo->getAvailableAmount() >= 10000) {
+    $thePayClient->createPaymentRefund(
+        'uid-454548',
+        10000,
+        'Partial refund because some items were delivered broken'
+    );
+} else {
+    // Render message: refund amount is not available
 }
 ```

doc/return-of-the-customer.md

@@ -1,27 +1,29 @@
 # Return of the Customer
 
-After payment creation, you will have to wait to return of the customer, keep in mind:
+After you create a payment, you redirect the customer to the payment gateway using the URL provided.
+Once the customer finishes (or abandons) the process at the gateway, they may be redirected back to your website.
 
-- the customer may not return to your website
-- the payment may not be paid in the moment of the return
+Keep in mind:
+- The customer may **not** return to your website
+- The payment may **not** be paid at the moment they return
 
-The customer will be returned to url specified in administration (in the project settings):
+## Configuring the Return URL
 
-![settings](img/settings.png)
+- The customer will be returned to url specified in administration (in the project settings):
 
-This value may be overridden for each payment in CreatePaymentParams by setReturnUrl() function.
+![settings](img/settings.png)
 
-There are two query parameters added to redirect url:
+You can override this value on a per-payment basis in `CreatePaymentParams` using the `setReturnUrl()` method.
 
-* payment_uid
-* project_id
+## Return URL Parameters
 
-In most cases you want to check the state of payment after customer's return:
+When the customer is redirected back, the following query parameters are appended:
+- payment_uid
+- project_id
 
-[See how to make TheClient](../.github/README.md#theclient-instance)
+You can use these identifiers to load the current state of the payment:
 
 ```php
-
 $uid = $_GET["payment_uid"];
 $projectId = $_GET["project_id"];
 

doc/saving-authorization.md

@@ -1,44 +1,48 @@
-# Saving card authorization
+# Saving Card Authorization
 
-It is possible to remember customer card information by using the save_authorization parameter upon payment creation.This allow easier and seamless payment creation, through following child payments, without additional customer card authorization.It shoud however NOT be confused with (and used for) [subscription payments](subscription.md).
+It is possible to store a customer’s card authorization by enabling the `save_authorization` parameter when creating a payment.
+This allows you to create follow-up (“child”) payments seamlessly, without requiring the customer to reauthorize their card.
 
-## Creating payment with save_authorization flag
+However, this feature must not be confused with — or used for — [subscription payments](subscription.md). Those have a separate workflow and rules.
+
+## Creating a Payment with `save_authorization`
 
 ```php
 
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
-$createPayment = new \ThePay\ApiClient\Model\CreatePaymentParams(10520, 'EUR', 'savedauthtest');
+$createPayment = new \ThePay\ApiClient\Model\CreatePaymentParams(10520, 'EUR', 'uid_savedauthtest', $customer);
 
-// set save_authorization to true
+// Enable saving of card authorization
 $createPayment->setSaveAuthorization(true);
 
 $payment = $thePayClient->createPayment($createPayment);
 
-// Get url where user can pay
+// Redirect customer to this URL to complete the payment
 echo $payment->getPayUrl(); // https://demo.gate.thepay.cz/5aa4f4af546a74848/pay/
 ```
 
-## Realizing new payment by saved authorization
+Once the payment is successfully completed, the system will store a reusable authorization token associated with the payment.
+
+## Creating a New Payment Using Saved Authorization
 
-After the created payment was paid, we can realize new payment by saved authorization:
+After the original payment (with `save_authorization = true`) has been paid, you can realize a new payment using the stored authorization:
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
-// first parameter is uid of new (child) payment
-// second parameter contains amount in cents, if sets to null it will use amount of parent payment, required if third parameter is set
-// third parameter contains currency code, if sets to null it will use currency code of parent payment, required if second parameter is set
-$params = new \ThePay\ApiClient\Model\RealizePaymentBySavedAuthorizationParams('childpayment', 1000, 'EUR');
+// First parameter: UID of the new (child) payment
+// Second parameter: amount in cents (optional; if null, parent amount is used; required if currency is set)
+// Third parameter: currency code (optional; if null, parent currency is used; required if amount is set)
+$params = new \ThePay\ApiClient\Model\RealizePaymentBySavedAuthorizationParams('uid_childpayment', 1000, 'EUR');
 
 // adding items is optional, if you do not add any item, items from parent payment will be used
 $item = new \ThePay\ApiClient\Model\CreatePaymentItem('item', 'Server setup', 1000, 1);
 $params->addItem($item);
 
-
-// first parameter is uid of parent payment (the one we create above with savedAuthorization set to true).
-// method will return ApiResponse
-$response = $thePayClient->realizePaymentBySavedAuthorization('subscriptionpayment', $params);
+// First parameter: UID of the parent payment (one created with saveAuthorization=true)
+// The method returns ApiResponse
+$response = $thePayClient->realizePaymentBySavedAuthorization('uid_savedauthtest', $params);
 
 if ($response->wasSuccessful()) {
     echo 'Payment was realized using saved authorization';

doc/subscription.md

@@ -1,102 +1,107 @@
-# Subscription payments
+# Subscription Payments
 
-It is possible to create long term subscription for your customers. The setup for subsription is done through regular endpoint for payment creation, but with the subscription properties set. The payment created can then be repeatedly paid by the customer, through a different endpoint.
+Subscription payments allow you to charge a customer repeatedly over time.
+A subscription is initialized through a standard payment creation request, but with subscription properties attached.
+Once the initial (parent) payment is completed, follow-up (child) payments can be realized using dedicated subscription endpoints.
 
-There are three different use cases with different endpoints for subscription payments, depending on payment time and payment amount needs.
-* Fixed time interval & fixed payment amount
-* Variable time interval & fixed payment amount
-* Fixed time interval & variable payment amount
+There are three main subscription types, depending on whether the time interval and payment amount are fixed or variable:
+- Fixed time interval & fixed amount
+- Variable time interval & fixed amount
+- Fixed time interval & variable amount
 
-The time interval or amount with fixed value is always set in the first (parent) payment upon payment creation. It is your responsibility to adhere to the values set in the parent payment. If you need to change the fixed payment amount or time period, a new subscription payment with different parameters must be used.
+Any value marked as fixed must be set in the parent payment, and it is your responsibility to adhere to it when creating child payments.
+If your subscription requires a different amount or interval, you must create a new parent subscription payment.
 
-**RECURRING PAYMENTS MUST BE ENABLED ON PROJECT**
+⚠️ **Important / Prerequisites**
+- **Recurring payments must be enabled on your project**.
 
-## Creating payment with subscription properties
+
+## Creating a Payment with Subscription Properties
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
-// prepare subscription properties (first parameter is type, second parameter is day period between payments)
+// Prepare subscription properties:
+// First parameter: subscription type
+// Second parameter: number of days between payments (for fixed interval types)
 $subscription = new \ThePay\ApiClient\Model\Subscription(
     \ThePay\ApiClient\ValueObject\SubscriptionType::REGULAR,
     30
 );
 
-// Create payment (105.20 € with unique id 'subscriptionpayment')
-$createPayment = new \ThePay\ApiClient\Model\CreatePaymentParams(10520, 'EUR', 'subscriptionpayment');
+// Create initial subscription payment (105.20 € with UID 'uid_subscriptionpayment')
+$createPayment = new \ThePay\ApiClient\Model\CreatePaymentParams(10520, 'EUR', 'uid_subscriptionpayment', $customer);
 $createPayment->setSubscription($subscription);
 
 $payment = $thePayClient->createPayment($createPayment);
 
-// Get url where user can pay
+// Redirect the customer to complete the payment
 echo $payment->getPayUrl(); // https://demo.gate.thepay.cz/5aa4f4af546a74848/pay/
 ```
 
 ## Realizing subscription payment
 
-After the created payment was paid, we can realize subscription:
+After the parent payment is paid, you may charge the customer again using one of the three subscription realization types.
 
-### Realizing regular subscription payment type
+### Realizing a Regular (Fixed Interval & Fixed Amount) Subscription
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
-// parameter is uid of new (child) payment
-$params = new \ThePay\ApiClient\Model\RealizeRegularSubscriptionPaymentParams('childpayment');
+// UID of the new (child) payment
+$params = new \ThePay\ApiClient\Model\RealizeRegularSubscriptionPaymentParams('uid_childpayment');
 
-// adding items is optional, if you do not add any item, items from parent payment will be used
+// You may optionally define items. If omitted, items from parent payment are reused.
 $item = new \ThePay\ApiClient\Model\CreatePaymentItem('item', 'Magazine #2', 10520, 1);
 $params->addItem($item);
 
-
-// first parameter is uid of parent payment (the one we create above with subscription property).
-// method will return ApiResponse
-$response = $thePayClient->realizeRegularSubscriptionPayment('subscriptionpayment', $params);
+// Parent payment UID is passed as the first parameter.
+// Method returns an ApiResponse.
+$response = $thePayClient->realizeRegularSubscriptionPayment('uid_subscriptionpayment', $params);
 
 if ($response->wasSuccessful()) {
     echo 'Subscription payment was realized';
 }
 ```
 
-### Realizing irregular subscription payment type
+### Realizing an Irregular (Variable Interval & Fixed Amount) Subscription
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
-// parameter is uid of new (child) payment
-$params = new \ThePay\ApiClient\Model\RealizeIrregularSubscriptionPaymentParams('childpayment2');
+// UID of the new (child) payment
+$params = new \ThePay\ApiClient\Model\RealizeIrregularSubscriptionPaymentParams('uid_childpayment2');
 
-// adding items is optional, if you do not add any item, items from parent payment will be used
+// You may optionally define items. If omitted, items from parent payment are reused.
 $item = new \ThePay\ApiClient\Model\CreatePaymentItem('item', 'New book', 10520, 1);
 $params->addItem($item);
 
-
-// first parameter is uid of parent payment (the one we create above with subscription property).
-// method will return ApiResponse
-$response = $thePayClient->realizeIrregularSubscriptionPayment('subscriptionpayment', $params);
+// Parent payment UID is passed as the first parameter.
+// Method returns an ApiResponse.
+$response = $thePayClient->realizeIrregularSubscriptionPayment('uid_subscriptionpayment', $params);
 
 if ($response->wasSuccessful()) {
     echo 'Subscription payment was realized';
 }
 ```
 
-### Realizing usage based subscription payment type
+### Realizing a Usage-Based (Fixed Interval & Variable Amount) Subscription
 
 ```php
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
-// first parameter is uid of new (child) payment
-// second parameter is amount in cents (in parent payment currency)
-$params = new \ThePay\ApiClient\Model\RealizeUsageBasedSubscriptionPaymentParams('childpayment3', 18000);
+// First param: UID of child payment
+// Second param: amount in cents (in the parent payment currency)
+$params = new \ThePay\ApiClient\Model\RealizeUsageBasedSubscriptionPaymentParams('uid_childpayment3', 18000);
 
-// adding items is optional, if you do not add any item, items from parent payment will be used
+// You may optionally define items. If omitted, items from parent payment are reused.
 $item = new \ThePay\ApiClient\Model\CreatePaymentItem('item', 'Server usage', 18000, 1);
 $params->addItem($item);
 
 
-// first parameter is uid of parent payment (the one we create above with subscription property).
-// method will return ApiResponse
-$response = $thePayClient->realizeUsageBasedSubscriptionPayment('subscriptionpayment', $params);
+// Parent payment UID is passed as the first parameter.
+// Method returns an ApiResponse.
+$response = $thePayClient->realizeUsageBasedSubscriptionPayment('uid_subscriptionpayment', $params);
 
 if ($response->wasSuccessful()) {
     echo 'Subscription payment was realized';