6254 api endpoints v2

doc/index.md

@@ -123,14 +123,20 @@ Will create payment.
 
 ### realizePreauthorizedPayment
 
-Will realize preauth payment
+Will realize preauth payment (V2 API endpoint).
 
 #### Parameters
 
 | name | type |  |
 | --- | --- | --- |
 | $params | RealizePreauthorizedPaymentParams | required |
 
+#### Return
+
+| return type |  |
+| --- | --- |
+| RealizePreauthorizedPaymentResult | Result with `getState()` returning 'paid' or 'waiting_for_confirmation' |
+
 ### cancelPreauthorizedPayment
 
 Will cancel preauth payment
@@ -182,48 +188,71 @@ Return information about transactions history
 
 ### realizeRegularSubscriptionPayment
 
-Realize subscription payment.
+Realize subscription payment (V2 API endpoint).
 
 #### Parameters
 
 | name | type |  | description |
 | --- | --- | --- | --- |
-| $uid | string | required | UID of parent payment |
+| $parentPaymentUid | string | required | UID of parent payment |
 | $params | RealizeRegularSubscriptionPaymentParams | required | |
 
+#### Return
+
+| return type |  |
+| --- | --- |
+| RecurringPaymentResult | Result with `getState()` and `isRecurringPaymentsAvailable()` |
+
 ### realizeIrregularSubscriptionPayment
 
-Realize subscription payment.
+Realize subscription payment (V2 API endpoint).
 
 #### Parameters
 
 | name | type |  | description |
 | --- | --- | --- | --- |
-| $uid | string | required | UID of parent payment |
+| $parentPaymentUid | string | required | UID of parent payment |
 | $params | RealizeIrregularSubscriptionPaymentParams | required | |
 
+#### Return
+
+| return type |  |
+| --- | --- |
+| RecurringPaymentResult | Result with `getState()` and `isRecurringPaymentsAvailable()` |
+
 ### realizeUsageBasedSubscriptionPayment
 
-Realize subscription payment.
+Realize subscription payment (V2 API endpoint).
 
 #### Parameters
 
 | name | type |  | description |
 | --- | --- | --- | --- |
-| $uid | string | required | UID of parent payment |
+| $parentPaymentUid | string | required | UID of parent payment |
 | $params | RealizeUsageBasedSubscriptionPaymentParams | required | |
 
+#### Return
+
+| return type |  |
+| --- | --- |
+| RecurringPaymentResult | Result with `getState()` and `isRecurringPaymentsAvailable()` |
 
 ### realizePaymentBySavedAuthorization
 
-Create new payment using saved authorization.
+Create new payment using saved authorization (V2 API endpoint).
 
 #### Parameters
 
 | name | type |  | description |
 | --- | --- | --- | --- |
-| $uid | string | required | UID of parent payment |
-| $params | RealizePaymentBySavedAuthorizationParams | required | |
+| $parentPaymentUid | string | required | UID of parent payment |
+| $params | RealizePaymentBySavedAuthorizationParams | required | Requires amount and currency code |
+
+#### Return
+
+| return type |  |
+| --- | --- |
+| RecurringPaymentResult | Result with `getState()` and `isRecurringPaymentsAvailable()` |
 
 ### getPaymentUrlsForPayment
 

doc/preauth-payments.md

@@ -1,6 +1,6 @@
 # Preauthorized payments
 
-A **preauthorized payment** allows you to reserve (authorize) funds on a customer’s account and capture them later.
+A **preauthorized payment** allows you to reserve (authorize) funds on a customer's account and capture them later.
 This is useful for cases like hotel bookings or rentals, where you charge the customer only after confirming service delivery.
 
 By setting `setIsDeposit(false)` when creating a payment, the payment is created as a **preauthorization** instead of a direct deposit.
@@ -26,13 +26,29 @@ $thePayClient->createPayment($params);
 Once you are ready to capture the funds, call `realizePreauthorizedPayment()`:
 
 ```php
+use ThePay\ApiClient\Model\RealizePreauthorizedPaymentResult;
+
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 $params = new \ThePay\ApiClient\Model\RealizePreauthorizedPaymentParams(100, 'PREAUTH_PAYMENT_001');
-$thePayClient->realizePreauthorizedPayment($params);
+$result = $thePayClient->realizePreauthorizedPayment($params);
+
+match ($result->getState()) {
+    RealizePreauthorizedPaymentResult::STATE_PAID =>
+        echo 'Preauthorized payment was realized successfully',
+
+    RealizePreauthorizedPaymentResult::STATE_WAITING_FOR_CONFIRMATION =>
+        echo 'Payment is being processed, you will receive a notification when complete',
+};
 ```
 
 You may capture less than the originally preauthorized amount, but never more.
 
+**Note about V2 API:**
+The V2 API supports asynchronous payment processing:
+- State `paid` means immediate success
+- State `waiting_for_confirmation` means the payment is being processed asynchronously
+- You will receive a notification when the async payment completes (state changes to `paid` or `preauth_cancelled`)
+
 ## Cancel a Preauthorized Payment
 
 If you decide not to capture the funds, you can cancel the preauthorization:
@@ -43,4 +59,4 @@ $thePayClient->cancelPreauthorizedPayment('PREAUTH_PAYMENT_001');
 ```
 
 **Note on fund release:**
-- While the preauthorization is cancelled immediately on ThePay’s side, banks may take some time to release the reserved funds back to the customer’s account.
+- While the preauthorization is cancelled immediately on ThePay's side, banks may take some time to release the reserved funds back to the customer's account.

doc/saving-authorization.md

@@ -1,7 +1,7 @@
 # Saving Card Authorization
 
-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.
+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.
 
 However, this feature must not be confused with — or used for — [subscription payments](subscription.md). Those have a separate workflow and rules.
 
@@ -29,22 +29,47 @@ Once the payment is successfully completed, the system will store a reusable aut
 After the original payment (with `save_authorization = true`) has been paid, you can realize a new payment using the stored authorization:
 
 ```php
+use ThePay\ApiClient\Model\RecurringPaymentResult;
+
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
 // 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');
+// Second parameter: amount in cents (required)
+// Third parameter: currency code (required)
+$params = new \ThePay\ApiClient\Model\RealizePaymentBySavedAuthorizationParams('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: UID of the parent payment (one created with saveAuthorization=true)
-// The method returns ApiResponse
-$response = $thePayClient->realizePaymentBySavedAuthorization('uid_savedauthtest', $params);
+// The method returns RecurringPaymentResult
+$result = $thePayClient->realizePaymentBySavedAuthorization('uid_savedauthtest', $params);
+
+match ($result->getState()) {
+    RecurringPaymentResult::STATE_PAID =>
+        echo 'Payment was realized using saved authorization',
+
+    RecurringPaymentResult::STATE_WAITING_FOR_CONFIRMATION =>
+        echo 'Payment is being processed, you will receive a notification when complete',
 
-if ($response->wasSuccessful()) {
-    echo 'Payment was realized using saved authorization';
+    RecurringPaymentResult::STATE_ERROR =>
+        echo 'Payment was not realized',
+};
+
+// Check if more payments can be realized with this saved authorization
+if (!$result->isRecurringPaymentsAvailable()) {
+    // Saved authorization is no longer valid, customer needs to authorize a new payment
+    echo 'Saved authorization is no longer valid, customer needs to authorize a new payment';
 }
 ```
+
+**Note about V2 API:**
+The V2 API introduces several important changes:
+- **Amount and currency are now required** - you must always specify both parameters
+- **Asynchronous processing**: Payment may have these states:
+  - `paid` - Payment realized successfully
+  - `error` - Payment realization failed
+  - `waiting_for_confirmation` - Payment is being processed asynchronously
+- **Parent availability tracking**: Check `isRecurringPaymentsAvailable()` to know if the saved authorization is still valid
+- You will receive a notification when async payments complete (state changes to `paid` or `error`)

doc/subscription.md

@@ -46,6 +46,8 @@ After the parent payment is paid, you may charge the customer again using one of
 ### Realizing a Regular (Fixed Interval & Fixed Amount) Subscription
 
 ```php
+use ThePay\ApiClient\Model\RecurringPaymentResult;
+
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
 // UID of the new (child) payment
@@ -56,17 +58,40 @@ $item = new \ThePay\ApiClient\Model\CreatePaymentItem('item', 'Magazine #2', 105
 $params->addItem($item);
 
 // Parent payment UID is passed as the first parameter.
-// Method returns an ApiResponse.
-$response = $thePayClient->realizeRegularSubscriptionPayment('uid_subscriptionpayment', $params);
+// Method returns a RecurringPaymentResult.
+$result = $thePayClient->realizeRegularSubscriptionPayment('uid_subscriptionpayment', $params);
+
+match ($result->getState()) {
+    RecurringPaymentResult::STATE_PAID =>
+        echo 'Subscription payment was realized',
+
+    RecurringPaymentResult::STATE_WAITING_FOR_CONFIRMATION =>
+        echo 'Payment is being processed, you will receive a notification when complete',
+
+    RecurringPaymentResult::STATE_ERROR =>
+        echo 'Payment was not realized',
+};
 
-if ($response->wasSuccessful()) {
-    echo 'Subscription payment was realized';
+// Check if more payments can be realized with this parent
+if (!$result->isRecurringPaymentsAvailable()) {
+    // No more payments can be realized with this parent, inform customer to create new subscription
+    echo 'Saved authorization is no longer valid, customer needs to authorize a new payment';
 }
 ```
 
+**Note about V2 API:**
+The V2 API supports asynchronous payment processing:
+- State `paid` means immediate success
+- State `error` means immediate failure
+- State `waiting_for_confirmation` means the payment is being processed asynchronously
+- You will receive a notification when the async payment completes (state changes to `paid` or `error`)
+- Always check `isRecurringPaymentsAvailable()` to know if the subscription should end
+
 ### Realizing an Irregular (Variable Interval & Fixed Amount) Subscription
 
 ```php
+use ThePay\ApiClient\Model\RecurringPaymentResult;
+
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
 // UID of the new (child) payment
@@ -77,17 +102,32 @@ $item = new \ThePay\ApiClient\Model\CreatePaymentItem('item', 'New book', 10520,
 $params->addItem($item);
 
 // Parent payment UID is passed as the first parameter.
-// Method returns an ApiResponse.
-$response = $thePayClient->realizeIrregularSubscriptionPayment('uid_subscriptionpayment', $params);
+// Method returns a RecurringPaymentResult.
+$result = $thePayClient->realizeIrregularSubscriptionPayment('uid_subscriptionpayment', $params);
+
+match ($result->getState()) {
+    RecurringPaymentResult::STATE_PAID =>
+        echo 'Subscription payment was realized',
 
-if ($response->wasSuccessful()) {
-    echo 'Subscription payment was realized';
+    RecurringPaymentResult::STATE_WAITING_FOR_CONFIRMATION =>
+        echo 'Payment is being processed, you will receive a notification when complete',
+
+    RecurringPaymentResult::STATE_ERROR =>
+        echo 'Payment was not realized',
+};
+
+// Check if more payments can be realized
+if (!$result->isRecurringPaymentsAvailable()) {
+    // Parent payment no longer available for new subscriptions
+    echo 'Parent payment no longer available for new subscriptions';
 }
 ```
 
 ### Realizing a Usage-Based (Fixed Interval & Variable Amount) Subscription
 
 ```php
+use ThePay\ApiClient\Model\RecurringPaymentResult;
+
 /** @var \ThePay\ApiClient\TheClient $thePayClient */
 
 // First param: UID of child payment
@@ -100,10 +140,23 @@ $params->addItem($item);
 
 
 // Parent payment UID is passed as the first parameter.
-// Method returns an ApiResponse.
-$response = $thePayClient->realizeUsageBasedSubscriptionPayment('uid_subscriptionpayment', $params);
+// Method returns a RecurringPaymentResult.
+$result = $thePayClient->realizeUsageBasedSubscriptionPayment('uid_subscriptionpayment', $params);
+
+match ($result->getState()) {
+    RecurringPaymentResult::STATE_PAID =>
+        echo 'Subscription payment was realized',
+
+    RecurringPaymentResult::STATE_WAITING_FOR_CONFIRMATION =>
+        echo 'Payment is being processed, you will receive a notification when complete',
+
+    RecurringPaymentResult::STATE_ERROR =>
+        echo 'Payment was not realized',
+};
 
-if ($response->wasSuccessful()) {
-    echo 'Subscription payment was realized';
+// Check if more payments can be realized
+if (!$result->isRecurringPaymentsAvailable()) {
+    // Parent payment no longer available for new subscriptions
+    echo 'Parent payment no longer available for new subscriptions';
 }
 ```