## Overview

The Reservepay Magento plugin lets you accept payments on your Magento store using Reservepay's pre-built payment form. The plugin handles the full checkout flow — redirecting customers to a secure payment page, processing the payment via the Reservepay API, and returning them to your order confirmation page.

## Prerequisites

Before installing the plugin, make sure you have the following:

* **Magento 2.3.x or higher** and **PHP 7.3 or higher, below PHP 8.0**
* **A Reservepay merchant account** with the following credentials (available in your merchant dashboard under developer settings):
  * **Merchant ID**
  * **Installation ID** — create an SDK installation for your website
  * **API Key** — create a new API key and keep it secret

## Installation

1.  **Download the module with Composer**
    Use Composer to add the module into your store:
    `composer require reservepay/reservepay-magento`

2.  **Enable the module**
    Run the following commands in your Magento root directory:

    ```bash
    bin/magento module:enable Reservepay_Payment
    bin/magento setup:upgrade
    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy
    bin/magento cache:flush
    ```

## Configuration

1.  Log in to the Magento Admin Panel.
2.  Navigate to **Stores > Configuration > Sales > Payment Methods**.
3.  Expand the **Reservepay** section.
4.  Configure the following settings:
    *   **Enabled**: Set to `Yes`.
    *   **Title**: The payment method title shown to customers (e.g., "Pay with Reservepay").
    *   **Merchant ID**: Enter your Reservepay Merchant ID.
    *   **Installation ID**: Enter your Reservepay Installation ID.
    *   **API Key**: Enter your secret API Key.
5.  Click **Save Config**.

## How it works

When a customer selects Reservepay at checkout and places their order, the following flow occurs:

1. **Redirect to payment page** — Magento redirects the customer to `/reservepay/payment/form`. The Reservepay SDK loads and renders an embedded payment form.

2. **Payment session created** — When the form initializes, the SDK fires `onPaymentSessionReady` with a `payment_session_id`. The plugin sends this to your Magento backend via a REST API call.

3. **Initiate payment flow** — Your backend calls `/merchants/initiate-payment-flow` with the session ID, order amount, and currency, authenticated with your API key. The returned `payment_id` is stored on the order.

4. **Customer completes payment** — The customer enters their payment details in the embedded form. On success, the SDK fires `onPaymentSuccess`.

5. **Verify and complete** — The plugin calls `/merchants/find-payment` from the backend to verify the payment status. If the status is `SUCCESSFUL`, the order is marked as paid and the customer is redirected to the order confirmation page.

If the payment fails at any point, the customer is redirected back to the checkout page to try again.

## Testing

To verify your integration is working:

1. Make sure the Reservepay payment method is enabled in your Magento stores configuration (see above).
2. Add a product to your cart and proceed to checkout.
3. Select **Reservepay** as the payment method and place the order.
4. Confirm you are redirected to the payment form page.
5. Complete a test payment and verify:
   * You are redirected to the order confirmation page.
   * The order status in Magento is updated correctly.

## Technical Details

*   **API Endpoints**: The module communicates with `https://api.reservepay.com/` to initiate payments and verify transaction status.
*   **Security**: Sensitive order data is validated using a secure, HTTP-only cookie (`payment_redirect_token`) to prevent unauthorized access during the payment redirect loop.
*   **Webhooks/Callbacks**: The module handles payment success and failure via the `reservepay/payment/paymentsuccess` and `reservepay/payment/paymentfail` controllers.