> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sitestorepro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Site Store Pro Payment Gateways and Webhooks

> Connect Stripe, Paddle, or PayPal as your primary checkout processor and register webhooks to keep order and subscription data in sync.

Site Store Pro ships with four payment processors ready to activate. You select one as your primary gateway, toggle between sandbox and production modes, and register webhook endpoints so the gateway can push real-time payment events back to your store. Navigate to **Admin → Checkout → Processors** (`/admin/ecommerce/checkout-processors`) to get started.

## Built-In Processors

| ID  | Processor          | SDK / Client              | Notes                                                    |
| --- | ------------------ | ------------------------- | -------------------------------------------------------- |
| `0` | **Test Gateway**   | Built-in                  | No credentials required; use for development and QA only |
| `1` | **Stripe**         | `stripe/stripe-php`       | Requires `STRIPE_KEY` and `STRIPE_SECRET` in `.env`      |
| `2` | **Paddle Billing** | `paddlehq/paddle-php-sdk` | Requires Paddle API key and client-side token in `.env`  |
| `3` | **PayPal**         | Built-in HTTP client      | Requires PayPal Client ID and Secret in `.env`           |

***

## Configuring Your Gateway

<Steps>
  <Step title="Navigate to Checkout Processors">
    Go to **Admin → Checkout → Processors** (`/admin/ecommerce/checkout-processors`).
  </Step>

  <Step title="Add your credentials to .env">
    Before activating a live gateway, add the required API keys to your `.env` file. Refer to your gateway dashboard for the correct key values.

    ```env theme={null}
    # Stripe
    STRIPE_KEY=pk_live_...
    STRIPE_SECRET=sk_live_...

    # Paddle
    PADDLE_API_KEY=...
    PADDLE_CLIENT_SIDE_TOKEN=...

    # PayPal
    PAYPAL_CLIENT_ID=...
    PAYPAL_CLIENT_SECRET=...
    ```
  </Step>

  <Step title="Select your primary gateway">
    Click the processor you want to use and select it as the **Primary Payment Gateway**.
  </Step>

  <Step title="Set the operating mode">
    Toggle between **Production** and **Sandbox / Test Mode**. Start in sandbox mode to validate your integration before taking live payments.
  </Step>

  <Step title="Save and test">
    Save your settings and place a test order to confirm the checkout flow is working end-to-end.
  </Step>
</Steps>

<Warning>
  Keep your gateway in **Sandbox / Test Mode** until you have verified the full checkout and webhook flow with test transactions. Switching to Production with unverified webhooks can result in missed order status updates and unprocessed subscription events.
</Warning>

***

## Webhook Endpoints

Register the webhook endpoints below in each gateway's developer dashboard. Webhooks allow the gateway to notify Site Store Pro when payments succeed, fail, or are refunded — keeping your order records accurate without polling.

<Note>
  Register your webhook endpoints in the gateway dashboard **before going live**. Without active webhooks, Site Store Pro cannot automatically update order statuses for asynchronous payment events such as delayed captures, refunds, or subscription renewals.
</Note>

<Tabs>
  <Tab title="Stripe">
    **Webhook endpoint to register:**

    ```text theme={null}
    https://yourdomain.com/webhooks/stripe
    ```

    **Required events to enable in the Stripe dashboard:**

    | Event                           | Purpose                                         |
    | ------------------------------- | ----------------------------------------------- |
    | `payment_intent.succeeded`      | Marks order as paid and triggers fulfillment    |
    | `payment_intent.payment_failed` | Flags order payment as failed                   |
    | `charge.refunded`               | Records refund in the Payments Ledger           |
    | `customer.subscription.created` | Activates a new subscription                    |
    | `customer.subscription.updated` | Syncs subscription plan changes                 |
    | `customer.subscription.deleted` | Cancels subscription access                     |
    | `invoice.payment_succeeded`     | Records successful subscription renewal payment |

    Add the webhook in your Stripe dashboard under **Developers → Webhooks → Add endpoint**. Copy your **Webhook Signing Secret** and add it to your `.env` as `STRIPE_WEBHOOK_SECRET`.
  </Tab>

  <Tab title="Paddle">
    **Webhook endpoint to register:**

    ```text theme={null}
    https://yourdomain.com/webhooks/paddle
    ```

    **Required events to enable in the Paddle dashboard:**

    | Event                        | Purpose                                     |
    | ---------------------------- | ------------------------------------------- |
    | `transaction.completed`      | Confirms a one-time or subscription payment |
    | `transaction.payment_failed` | Flags a failed payment attempt              |
    | `customer.created`           | Syncs new Paddle customer records           |
    | `subscription.created`       | Activates a new subscription                |
    | `subscription.updated`       | Syncs subscription plan or billing changes  |
    | `subscription.canceled`      | Cancels subscription access                 |

    Register the endpoint in your Paddle dashboard under **Developer Tools → Notifications**. Site Store Pro uses your `PADDLE_WEBHOOK_SECRET` to verify incoming event signatures.
  </Tab>

  <Tab title="PayPal">
    **Webhook endpoint to register:**

    ```text theme={null}
    https://yourdomain.com/webhooks/paypal
    ```

    **Required events to enable in the PayPal developer dashboard:**

    | Event                       | Purpose                                  |
    | --------------------------- | ---------------------------------------- |
    | `CHECKOUT.ORDER.APPROVED`   | Customer has approved the PayPal order   |
    | `PAYMENT.CAPTURE.COMPLETED` | Capture succeeded; order marked as paid  |
    | `PAYMENT.CAPTURE.DENIED`    | Capture failed; order flagged for review |

    Register the endpoint in **PayPal Developer → My Apps & Credentials → Webhooks**. Ensure the webhook is added to both your Sandbox and Live application entries as appropriate.
  </Tab>
</Tabs>