diff --git a/doc/notifications.md b/doc/notifications.md index bdb0711..774a4b5 100644 --- a/doc/notifications.md +++ b/doc/notifications.md @@ -1,23 +1,31 @@ # Notifications -If state of the payment changes you will get a notification to a specified url. Please set up default value in administration: +When the state of a payment changes, ThePay sends a notification to a specified URL. + +## Configuration + +You can configure the default notification URL in the administration panel: ![settings](img/settings.png) -This value may be overridden for each payment in CreatePaymentParams by setNotifUrl() function. +This default URL can be **overridden for individual payments** using the `setNotifUrl()` method in `CreatePaymentParams`. -There are three query parameters added to notifications url: +## Notification Parameters -* payment_uid -* project_id -* type (which determines notification type - see [Notification types enum](https://thepay.docs.apiary.io/#introduction/enums/notification-types)) +| Parameter | Description | +|------------|-------------| +| `payment_uid` | The unique identifier (UID) of the payment. | +| `project_id` | The project identifier. | +| `type` | The notification type. See [Notification types enum](https://thepay.docs.apiary.io/#introduction/enums/notification-types). | In most cases you want to check the state of payment after getting notification: -[See how to make TheClient](../.github/README.md#theclient-instance) +## Example: Handling a Payment Notification -```php +After receiving a notification, you typically want to check the current state of the payment. +> See [how to make TheClient](../.github/README.md#theclient-instance). +```php $uid = $_GET["payment_uid"]; $projectId = $_GET["project_id"]; @@ -33,19 +41,20 @@ $thePayClient = new \ThePay\ApiClient\TheClient($config, $apiService); $payment = $thePayClient->getPayment($uid); if ($payment->getState() === 'paid') { - // send email to customer + // Example action: send confirmation email to customer } ``` -You can save server resources by filtering notification type to only certain types: +## Best Practice: Filter by Notification Type -```php +You can reduce unnecessary API calls by handling only certain types of notifications — for example, `state_changed` events. +```php $uid = $_GET["payment_uid"]; $projectId = $_GET["project_id"]; $type = $_GET["type"]; -// handle only state changed notifications +// Handle only "state_changed" notifications if ($type === "state_changed") { $merchantId = '86a3eed0-95a4-11ea-ac9f-371f3488e0fa'; $apiPassword = 'secret'; @@ -59,7 +68,13 @@ if ($type === "state_changed") { $payment = $thePayClient->getPayment($uid); if ($payment->getState() === 'paid') { - // send email to customer + // Example action: send confirmation email to customer } } ``` + +## ✅ Summary +- Set a default notification URL in the admin, or override it per payment with `setNotifUrl()`. +- Notifications include `payment_uid`, `project_id`, and `type` parameters. +- Use the notification to fetch and check payment state. +- Optionally filter by notification type (e.g., `state_changed`) to optimize performance. diff --git a/doc/payment-events.md b/doc/payment-events.md index 934eb5f..1ddd8d7 100644 --- a/doc/payment-events.md +++ b/doc/payment-events.md @@ -1,41 +1,56 @@ # Payment Events -Each payment detail has an array of events. In the array are events representing the following types: method selection, state change, unavailable method, payment cancelled, and payment error. -After creating a payment, the array will be empty and will be fulfilled depending on user actions. +Each payment contains an array of **events** that describe actions and state changes related to that payment. +Events can represent, for example: +- Method selection +- State change +- Unavailable payment method +- Payment cancellation +- Payment error -First thing you need to do is to obtain payment detail: +When a payment is first created, the events array is empty. It is populated gradually as the customer interacts with the payment process. + +## Retrieve Payment Events + +First, obtain the payment details: ```php -// get payment detail +// Get payment detail $payment = $thePayClient->getPayment('49096fe3-872d-3cbe-b908-2806ae2d7c79'); ``` -Then you can get the list of events that occured on that payment: +Then, retrieve the list of all events associated with the payment: ```php $paymentEvents = $payment->getEvents(); ``` -You can also check if there was some specific event on the user's last attempt. +`$paymentEvents` contains all recorded events for that payment. + +## Check for Specific Events -To check if there was an error on the last attempt: +You can also check whether certain events occurred during the user's **last attempt**. + +### Example: Detect an Error on the Last Attempt ```php $hasErrorOnLastAttempt = $payment->hasErrorOnLastAttempt(); + if ($hasErrorOnLastAttempt) { - // there was an error on the last attempt + // There was an error on the user's last attempt } else { - // there was not an error on the last attempt + // No error occurred on the user's last attempt } ``` -To check if the last attempt was cancelled by user: +## Example: Detect if User Cancelled the Last Attempt ```php $wasLastAttemptCancelledByUser = $payment->wasLastAttemptCancelledByUser(); + if ($wasLastAttemptCancelledByUser) { - // last attempt was cancelled by user + // The last attempt was cancelled by the user } else { - // last attempt was not cancelled by user + // The last attempt was not cancelled by the user } ``` diff --git a/doc/preauth-payments.md b/doc/preauth-payments.md index f058d18..a246cd7 100644 --- a/doc/preauth-payments.md +++ b/doc/preauth-payments.md @@ -1,16 +1,29 @@ # Preauthorized payments -In case you need to create preauthorized payment, just call createPayment() with params->setIsDeposit(false); -If deposit is set to false then the payment will be created as "pre-authorization" and you can realise it later using realizePreauthorizedPayment method. You usually have a period of 7 days to realise the pre-authorized payment. +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. +Typically, you have a limited period (usually 7 days) to realize the preauthorized payment. + + +## Create a Preauthorized Payment + +To create a preauthorized payment, call `createPayment()` with the `isDeposit` flag set to `false`: ```php /** @var \ThePay\ApiClient\TheClient $thePayClient */ -$params = new \ThePay\ApiClient\Model\CreatePaymentParams(100, 'CZK', 'PREAUTH_PAYMENT_001'); +/** @var \ThePay\ApiClient\Model\CreatePaymentCustomer $customer */ +$params = new \ThePay\ApiClient\Model\CreatePaymentParams(100, 'CZK', 'PREAUTH_PAYMENT_001', $customer); $params->setIsDeposit(false); + $thePayClient->createPayment($params); ``` -To realize payment call: + +## Realize a Preauthorized Payment + +Once you are ready to capture the funds, call `realizePreauthorizedPayment()`: ```php /** @var \ThePay\ApiClient\TheClient $thePayClient */ @@ -18,9 +31,16 @@ $params = new \ThePay\ApiClient\Model\RealizePreauthorizedPaymentParams(100, 'PR $thePayClient->realizePreauthorizedPayment($params); ``` -If you want to cancel preauth: +You may capture less than the originally preauthorized amount, but never more. + +## Cancel a Preauthorized Payment + +If you decide not to capture the funds, you can cancel the preauthorization: ```php /** @var \ThePay\ApiClient\TheClient $thePayClient */ $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.